campy-memory

Files (2)

• SKILL.md
• __init__.py

SKILL.md (first lines)

# Campy Memory Skill

**Purpose:** Use HippoCampy (Campy) as a reliable durable memory system without bloating your context window.

Campy continuously captures your decisions, constraints, plans, and lessons as you work. This skill teaches you when to recall that memory, which tool to use, and how to keep your context lean.

## Core Rule

**Do not recall on every turn. Do not bloat context. Recall only when a decision needs memory.**

Campy writes passively. You recall actively and selectively.

---

## Write vs Recall

### Write (Passive - Always On)

Campy captures:
- **Decisions** - what you decided and why
- **Constraints** - what you must or cannot do
- **Plans** - your implementation strategies
- **Lessons** - what you learned that applies elsewhere
- **Entity relationships** - how concepts connect
- **Contradictions** - when expectations differ from reality

You do nothing. The system listens to your messages and stores the core signal.

### Recall (Active - You Decide)

You call a recall tool when you need:
- Prior choices or context
- Timeline of what happened
- Lessons from similar work
- Workflow procedures
- Changes since another session

---

## Recall Decision Tree

### **Q: What kind of decision are you making?**

#### Prior decisions, architecture, constraints, or preferences
-> **`current_truth`**
- Use when: "What did we decide?", "What are the constraints?", "Is feature X enabled?"
- Example: "What architecture did we settle on for the installer?"

#### What changed since last session or another agent
-> **`diff_since`**
- Use when: "What changed?", "Since the last time...", "What did the other agent do?"
- Example: "What's different since the last session?"

#### Sequence, timeline, or debugging history
-> **`reconstruct_timeline`**
- Use when: "What happened in order?", "How did we get here?", "Walk me through the debug steps"
- Example: "What was the sequence of steps that led to this bug?"

#### Planning similar work
-> **`recall_plans`**
- Use when: "How did we do this before?", "Similar project", "Implement X like we did Y"
- Example: "I need to set up an installer. What did we learn from the last one?"

#### Reusable workflow or procedure
-> **`recall_procedures`**
- Use when: "How do we usually do this?", "Standard workflow", "Process we use"
- Example: "What's our standard testing procedure?"

#### Lessons learned or cross-session learning
-> **`recall_relevant_lessons`**
- Use when: "What did we learn?", "Don't repeat the mistake", "Best practice from before"
- Example: "What lessons did we learn from the last release?"

#### Similar past project (analogy)
-> **`analogical_search`**
- Use when: "This is like...", "Similar situation before", "Analogous problem"
- Example: "We had a similar performance problem before. What did we do?"

#### ARC mechanics, world model, scene graph, or puzzle patterns
-> **`recall_mechanic_priors`** or **`recall_scene_graph_priors`**
- Use when: "ARC", "world model", "mechanic", "puzzle pattern"
- Example: "What world-model mechanics did we discover for this type of puzzle?"

#### Context window or token health
-> **`context_status`**
- Use when: "How much context is left?", "Token budget", "Context bloat check"
- Example: "Am I at risk of context bloat? How many tokens are loaded?"

#### Multi-entity query spanning facts, decisions, and data (Bundle Compilation)
-> **`compile_context`**
- Use when: You need a *heterogeneous context bundle* that combines facts, constraints, graph data, and tabular data
- Example: "Brief me on everything we know about this module's architecture, constraints, and historical performance"
- Output: Pre-assembled context bundle formatted for your agent type, token budget respected

##### When to Use compile_context

- **Multi-topic queries:** Your question references multiple distinct entities or concepts
- **Need structured context:** You want facts, constraints, related items, and data all together
- **Large context available:** The normal recall tools would require multiple calls or manual assembly
- **Agent supports formatted bundles:** Your client (Claude Code, Codex, Gemini) supports structured markdown or JSON output

##### Token Budget & Output Format

`compile_context` respects your token budget and returns pre-compressed output:

- **Default budget:** 32,000 tokens (configurable)
- **Output formats:** 
  - `generic` - JSON (compatible everywhere)
  - `claude_code` - Markdown with headers and metadata
  - `codex` - Ultra-compact comments (60 chars/line)
  - `claude_desktop` - Conversational prose with citations
  - `chatgpt_desktop` - Friendly bullet points with emojis
  - `arc` - Structured JSON for ARC agent

**Key benefit:** Bundle is already token-budgeted. Inject directly into your prompt without re-summarizing.

#### Simple local edit or current context sufficient
-> **Do not recall**
- Example: "Add a comment to this function" or "Fix the typo on line 42"

From engramist/hippocampy, Apache-2.0.

More from engramist/hippocampy