Memory

Memory: The Persistent Context Engine

I bridge sessions. I prevent amnesia. I maintain a living database of who the user is, what they prefer, and what happened — structured for instant retrieval, not archaeological digs through giant log files.

When to Use

• Session startup: Read manifest.json → know the user in 2 seconds
• Preference capture: User corrects you, expresses a bias, or picks a tool — write it down silently
• Secret storage: User shares an API key, token, or credential — vault it immediately
• Session end: Write the day's handover into today's journal entry
• Pattern detection: Same question or correction twice → promote to a preference
• Weekly maintenance: Old journal files pile up → summarize and archive them

Core Instructions

1. The Manifest (data/manifest.json)

The single source of truth. Read this file first on every startup — it tells you where everything is without scanning the filesystem.

{
  "version": 2,
  "last_updated": "[DATE]",
  "identity": {
    "name": "[USER_NAME]",
    "primary_lang": "[LANG]",
    "updated": "[DATE]"
  },
  "secrets": {
    "[SERVICE_NAME]": { "file": "vault/[SERVICE_NAME].enc", "stored": "[DATE]", "status": "active" }
  },
  "preferences": {
    "tooling": { "file": "prefs/tooling.md", "updated": "[DATE]" }
  },
  "playbooks": {
    "deploy-skill": { "file": "playbooks/deploy-skill.md", "updated": "[DATE]" }
  },
  "recent_journal": "journal/[DATE].md",
  "active_project": {
    "name": "[PROJECT_NAME]",
    "goal": "[PROJECT_GOAL]",
    "updated": "[DATE]"
  }
}

Update the manifest whenever you write to any data file. The manifest is the index — if it's stale, the system is broken.

2. The Daily Journal (data/journal/YYYY-MM-DD.md)

One file per day. This is the innovation that prevents log files from becoming unreadable monsters.

Create a new journal file when today's date doesn't have one. Format:

# Journal: 2026-04-28

## 03:52 — Session Start
- **Task**: [What the user wants to do]
- **Context**: [Relevant background]

## 04:15 — Preference Captured
- **Category**: coding-style
- **Key**: component-paradigm
- **Value**: Functional components over class components
- **Source**: User correction ("Actually, use functional components")

## 05:30 — Handover
- **Last Action**: [What was done]
- **Blockers**: [What's stuck, if anything]
- **Next**: [What the next session should do first]
- **Mood**: [Productive / Frustrated / Exploratory / Rush]

Rules:

• Timestamps use HH:MM in the user's local timezone
• Entry types: Session Start, Preference Captured, Secret Stored, Workflow Saved, Decision Made, Handover
• The last entry of the day is the handover — no separate handover file needed
• If the user starts a second session on the same day, append to the existing journal file

3. Identity File (data/identity.md)

The user's profile — who they are, how they work, what they hate. Read this alongside the manifest on startup.

# Identity

## Who
- **Name**: [Name]
- **Handle**: [GitHub/Online handle]
- **Timezone**: [TZ]

## Technical DNA
- **Primary Languages**: [Languages]
- **Stack**: [Frameworks, tools]
- **Editor**: [Editor]
- **OS**: [OS]
- **Package Manager**: [PM]

## Current Focus
- [Active project/goal]

## Anti-Preferences (Never Do)
- [Things the AI must never do for this user]

Update this file whenever a core identity fact changes. This is the "who am I talking to?" file.

4. Preferences (data/prefs/{category}.md)

Group preferences by category, not by individual micro-decision. Categories:

Format inside each file:

# Tooling Preferences

| Preference | Value | Captured |
|-----------|-------|----------|
| Package Manager | npm | 2026-04-28 |
| Build Tool | Vite | 2026-04-28 |

Silent capture: When the user corrects you or expresses a preference, update the relevant prefs file immediately. Do not ask permission for technical preferences. Log the capture in today's journal.

5. Vault (data/vault/{service-name}.enc)

One file per service. Contains the raw credential and minimal metadata:

SERVICE: [SERVICE_NAME]
KEY: [KEY]
STORED: [DATE]
NOTES: [NOTES]

Security rules:

• Never print vault contents in chat unless the user explicitly says "show me the key"
• Always refer to secrets by name: "Your Gemini API key is stored and available"
• Update manifest.json secrets index when adding/removing

6. Playbooks (data/playbooks/{name}.md)

Step-by-step guides for fragile or complex procedures the user has done before:

# Deploy Skill to GitHub

1. Ensure SKILL.md frontmatter is valid
2. Run SIP audit checklist
3. `git add . && git commit -m "feat(skill-name): description"`
4. `git push origin main`
5. Verify GitHub Actions pass

## Gotchas
- Description must be < 1000 chars
- .gitignore must cover data/ directories

Save a playbook whenever a multi-step procedure succeeds for the first time, or when the user says "I keep doing this" or "remember how to do this."

Startup Protocol

When a new session or complex task begins, execute these steps in order:

1. Read data/manifest.json — get the full index in one read
2. Read data/identity.md — know who you're talking to
3. Check today's journal — does data/journal/YYYY-MM-DD.md exist? If yes, read the last entry for continuity. If no, create it with a Session Start entry
4. Scan for stale journals — if any journal files are older than 7 days, queue them for archival (do it after the main task, not during startup)

This takes 2 file reads + 1 directory listing. Fast.

Archive Protocol (Weekly Compaction)

When journal files older than 7 days accumulate:

1. Group them by ISO week number (e.g., 2026-W17)
2. Read all entries from that week
3. Write a summary to data/archive/week-YYYY-WXX.md:

# Week 2026-W17 (Apr 21–27)

## Key Decisions
- [Major choices made]

## Preferences Changed
- [What was added/updated in prefs/]

## Projects Active
- [What was being worked on]

## Notable Sessions
- Apr 25: [Brief summary]
- Apr 27: [Brief summary]

4. Delete the original daily journal files for that week
5. Update manifest.json with the archive reference

Result: The journal/ directory never exceeds ~14 files (current + previous week buffer).

Retrieval Protocol

When you need to find something:

1. Check manifest.json first — it has direct paths to every stored file
2. For recent context: Read today's and yesterday's journal entries
3. For older context: Check archive/ weekly summaries
4. For specific values: Read the relevant prefs/ or vault/ file directly
5. Last resort: grep -rn "keyword" memory/data/ — but this should be rare if the manifest is maintained

Boundaries

• No duplication: If info belongs in a Knowledge Item (repository-wide context), don't duplicate it here. Memory is for user-specific and session-specific state
• Masking: Never print raw vault contents unless explicitly asked. Refer by name
• No monolith files: If any single file exceeds 200 lines, it needs to be split or archived. The whole point of this architecture is preventing bloat
• Prefs are latest-wins: If a preference changes, update in place — don't append a history. The journal already has the change history
• Manifest is sacred: Every data write must be followed by a manifest update. A stale manifest is a broken system

Self-Verification

After any memory operation, verify:

• manifest.json is up to date with latest entry
• Today's journal file exists and has the latest entry
• Preferences table reflects current user state
• No sensitive data (API keys, passwords) stored in plaintext
• Archive entries older than 30 days have been moved

Composability — Working With Other Skills

See PROTOCOL.md (SIP) at skills root for full interop contract.

Domain Declaration

domain: process
composable: true
yields_to: [voice, craft]

Memory owns process — specifically the management of persistent state, continuity between sessions, and the lifecycle of user-specific knowledge.

When Memory Leads

• Defining the storage structure for persistent data
• Deciding when a transient fact should become a permanent preference
• Handling the security lifecycle of secrets (storage, masking, retrieval)
• Managing the daily journal rotation and archive compaction
• Running the startup protocol (manifest → identity → journal check)

When Memory Defers

Layered Composition Rules

1. Memory + Voice: Journal entries and identity data are written in neutral, technical tone to ensure machine-readability across sessions, even if a voice skill is active for user-facing output
2. Memory + Process: If another process skill (e.g., postmortem) generates an artifact, memory captures the metadata (location, purpose, date) in the journal but does not duplicate artifact content
3. Memory + Density: Memory's data files are never compressed by density skills. They're structured source files, not prose

Pipeline Behavior

• Upstream (receives from another skill): If a skill generates a reusable procedure, memory can capture it as a playbook. If a skill reveals a user preference, memory stores it in prefs/
• Downstream (feeds into another skill): Memory provides context that other skills consume — identity info for personalization, preferences for tool selection, secrets for API access

Conflict Signal

If a new preference conflicts with a stored one:

⚠️ Process conflict: New preference [X] conflicts with stored preference [Y]. Updating to [X] as most recent ground truth. Change logged in journal.