Adaptive Private Memory Engine

Adaptive Private Memory Engine (APME)

Core Rules (Non-Negotiable)

1. Load only what the current task needs. Never read all memory.
2. Update only when continuity would otherwise be lost.
3. Personal memory never goes in skills, repos, CLAUDE.md body, commits, PRs, or shared artifacts.
4. The skill stays publishable and persona-free.
5. Token efficiency is a primary design constraint, not an afterthought.

Memory Home

All private memory lives at ~/.claude/memory/ — outside repos, skill vault, and any tracked content.

~/.claude/memory/
  INDEX.md          ← Fast routing index (≤50 lines, pointers only)
  ALIASES.md        ← Keyword/alias → file path mapping
  RESUME.md         ← Resumable state entries
  preferences/
    stable.md       ← Communication style, tool defaults, general prefs
    writing.md      ← Tone, format, voice preferences
    tools.md        ← Environment, CLI, app preferences
  projects/
    active/         ← One file per active project
    paused/         ← Paused with resume notes
    archive/        ← Completed or abandoned
  workflows/        ← Recurring multi-step patterns
  decisions/        ← Important choices with rationale
  .cache/           ← Session routing cache (clearable, never sensitive)

Path safety rule: Before any write, confirm target is within ~/.claude/memory/. If uncertain — skip the write.

Activation Decision

Does this task require personal context?
  NO  → Skip memory entirely. Proceed with task.
  YES → What type?
          Project alias triggered      → ALIASES.md → direct to project file
          "Resume", "where were we"    → RESUME.md
          Preference / style question  → preferences/[relevant].md
          New info worth saving        → Classify first (see Write Policy)
          Unknown                      → INDEX.md for routing
          Maintenance signal           → Check scale/drift (see Maintenance)

False positive suppression: Do NOT activate memory for:

• Pure factual / technical questions with no personal context
• Casual conversation
• Tasks explicitly scoped to current context only
• Questions answered by the current codebase or file

Staged Retrieval Protocol

Follow in order. Stop as soon as sufficient context is assembled.

1. Decide if memory is needed at all. If not — stop here.
2. Classify the task: project, preference, workflow, decision, or resume.
3. Check ALIASES.md for a direct route. If found — load only that target.
4. If no alias hit, load INDEX.md. Use it for routing only.
5. Load the relevant category summary file.
6. Open a specific detail file only if summary is insufficient.
7. Check .cache/ for routing results from this session. Reuse if valid.
8. Do not re-read any file already loaded this session.
9. Return compact working context. Exclude everything unrelated.
10. Stop.

Never jump to step 6 without trying steps 3–5 first.

Trigger Taxonomy

Trigger precision: Require at least one clear signal. Ambiguous single-word references do not auto-trigger. Ask or proceed without memory rather than guess.

Memory Write Policy

Classify before writing. This takes 5 seconds and prevents bloat.

Writing rules:

• Update existing entries; do not duplicate.
• Active projects: next step + brief status only. No transcripts.
• Decisions: one-sentence rationale. Not reasoning logs.
• Prefer compact table updates over paragraph additions.
• Use [unconfirmed] labels for provisional information.
• Write at continuity risk points — not after every exchange.
• Sensitive material: store the pattern, not the raw personal data.

Resumable State Format

Use when work may be interrupted or needs a handoff. Entries stay under 10 lines.

## Resume: [Task Name] — [YYYY-MM-DD]
**Objective:** [one sentence]
**Status:** [what is done]
**Next:** [exact next action]
**Blockers:** [list or "none"]
**Key refs:** [safe file paths or decision links, if any]
**Confidence:** [high / medium / low]
**Stale after:** [date or event trigger]
**Sensitivity:** [low / medium / high]

Archive when complete. Delete when stale. Never let RESUME.md exceed 20 entries.

INDEX.md Contract

The INDEX.md must stay compact and fast to load.

# Memory Index — [YYYY-MM-DD]

## Active Projects
- [Name](projects/active/name.md) — [one-line status]

## Paused Projects
- [Name](projects/paused/name.md) — [paused since date]

## Preferences
- [stable](preferences/stable.md) — [tag]
- [writing](preferences/writing.md) — [tag]
- [tools](preferences/tools.md) — [tag]

## Active Resumes
- [task name] — see RESUME.md

## Aliases
See ALIASES.md for full trigger map.

## Maintenance
Last checked: [date] | File count: [n] | Stale flags: [n]

Hard limit: 50 lines. If exceeded — compress or archive.

Privacy Enforcement

Tiered model. Not constant full audits.

Hard privacy rules:

1. Memory never written into any repo directory.
2. Memory never in ~/claude-skill-vault/ or any skill file.
3. CLAUDE.md contains routing instructions and operational rules only — never personal data.
4. Generated docs, exports, summaries: scan for personal content before output.
5. If a workflow would expose personal memory — reroute or refuse. Never silently proceed.
6. Skill files (including this one) remain publishable with zero personal content.

Fail closed on privacy. On ambiguity — skip the write, never guess.

Maintenance Schedule

Default: lightweight and event-based. Heavy: only when triggered.

Lightweight maintenance (< 5 min equivalent): fix aliases, compress one file, update INDEX.

Heavy maintenance (full dedup, taxonomy optimization) only when:

• Memory home exceeds 40 files
• Multiple stale markers present
• Explicit request
• Agent-assisted optimization is clearly cost-effective

Do not run maintenance on every session. Do not reread all files to check unchanged state.

Agent Orchestration

Optional. Use only when it materially reduces cost or improves quality.

Agent constraints:

• Agents receive no raw sensitive personal content.
• Outputs are compact, action-oriented, and applied by Claude.
• Claude writes all final memory changes.
• No agent externalizes or broadly restates personal memory.
• Simple tasks — no agent dispatch.

Quick Reference

Need memory at all?         → Activation Decision flowchart
Known project or alias?     → ALIASES.md → direct load
No direct route?            → INDEX.md → category summary → detail if needed
Writing memory?             → Classify first. Update compact.
Resuming work?              → RESUME.md → load entry
Ending meaningful task?     → Assess continuity risk. Write if needed.
Maintenance needed?         → Lightweight first, check triggers
Privacy concern?            → Tiered check. Fail closed.
Session routing cache?      → `.cache/` — reuse if valid, clear freely

Templates and schemas: see memory-schema.md Skill efficiency optimization: see skill-optimizer.md