Adaptive Private Memory Engine

Adaptive Private Memory Engine (APME) v2

Non-Negotiable Rules

1. Load only what the task needs. Never read all memory.
2. Update only at continuity risk. Not after every exchange.
3. Memory never enters skills, repos, commits, PRs, or shared artifacts.
4. Skill stays publishable. Zero personal content here.
5. Token efficiency is a primary constraint — not an afterthought.
6. Fail closed on privacy. On ambiguity, skip the write.

Memory Home Structure

~/.claude/memory/
  INDEX.md            ← Routing index (hard cap: 60 lines, pointers only)
  ALIASES.md          ← Keyword/alias → file path map
  RESUME.md           ← Active resumable state (max 20 entries)
  preferences/
    stable.md         ← Communication style, general approach
    writing.md        ← Tone, format, voice
    tools.md          ← Environment, CLI, app preferences
  projects/
    active/           ← One file per active project
    paused/           ← Paused with resume notes
    archive/          ← Completed/abandoned (compact summaries only)
  workflows/          ← Recurring multi-step patterns
  decisions/          ← Important choices with rationale
  lessons/            ← Lessons learned, failure patterns, hard-won insights
  patterns/           ← Reusable approaches, templates, proven techniques
  .cache/             ← Session routing cache (ephemeral, never sensitive)

Write path rule: Before any write, verify target starts with ~/.claude/memory/. If uncertain — skip the write.

Activation Decision

Run this before touching any memory file. Stop at the first match.

Is personal context needed for this task?
  NO  → Skip memory. Proceed.
  YES → Identify signal type:

  Signal: known project name / alias        → ALIASES.md → project file (direct)
  Signal: "resume", "continue", "left off"  → RESUME.md
  Signal: preference / style question       → preferences/[type].md
  Signal: "why did we", "what was the"      → decisions/ or lessons/
  Signal: recurring pattern / "how we do"   → workflows/ or patterns/
  Signal: saving / pausing work             → Classify → write to RESUME.md
  Signal: new info worth keeping            → Classify (see Write Policy)
  Signal: maintenance flag                  → Check scale/drift triggers
  Signal: unknown route                     → INDEX.md for routing

False positive suppression — do NOT activate for:

• Pure technical questions with no personal context
• Casual conversation or one-liners
• Tasks fully answered by current file/codebase
• Generic "how do I" questions with no personal history

Staged Retrieval Protocol

Follow in order. Stop as soon as sufficient context exists.

Never read detail (step 7) before attempting summary (step 6). Never re-read a file already loaded this session unless source changed. Never load unrelated categories even if memory exists there.

Trigger Taxonomy

All 10 trigger types. Require at least one clear signal before activating.

Precision rule: Single ambiguous words do not trigger. Require phrase-level signal or explicit request.

Memory Taxonomy

Nine categories. Use the right one — don't force fit.

Archive is compact — outcome + key decisions only, not full project detail. Lessons are discovery notes — what was surprising, what failed, what to avoid. Patterns are prescriptive — what works reliably and how to apply it.

Memory Write Policy

Classify before writing. Prevents bloat and drift.

Writing rules:

• Update existing entries. Do not duplicate.
• Active projects: next step + brief status only. No transcripts.
• Decisions: one-sentence rationale. Not reasoning logs.
• Lessons: one paragraph max. What happened, what to do differently.
• Patterns: steps + key variations. Not exhaustive docs.
• Use [unconfirmed: DATE] for anything uncertain.
• Write at continuity risk — not mechanically after every turn.
• Sensitive: store the pattern or intent, never raw personal detail.
• After any write: update INDEX.md if new file created.

Session Cache Rules

.cache/ stores resolved routing for the current session only.

Write to cache: When a route is resolved (alias → file, or INDEX lookup → file path). Read from cache: At step 3 of retrieval — before any other file read. Cache entry format: [trigger keyword] → [resolved file path] — [timestamp] Invalidate: If source file was modified this session, or session ends. Never cache: Sensitive lookups, write operations, or anything containing personal detail. Clear freely: Cache can be deleted at any time with no data loss.

Resumable State Format

Compact handoff note. Not a transcript.

## Resume: [Task Name] — [YYYY-MM-DD]
**Objective:** [one sentence — what is being accomplished]
**Status:** [what is complete]
**Next:** [exact next action — specific enough to act on immediately]
**Blockers:** [none / list]
**Key refs:** [file paths or decision anchors — safe to note]
**Confidence:** [high / medium / low]
**Stale after:** [date or event, e.g. "after PR merged"]
**Sensitivity:** [low / medium / high]

Hard rules:

• Max 10 lines per entry
• Max 20 entries total in RESUME.md
• Archive on completion
• Delete when stale
• Never store credentials, keys, or full session transcripts

INDEX.md Contract

Fast routing index. Pointers only — no detail inline.

# Memory Index — [YYYY-MM-DD]
_Files: [n] | Stale flags: [n]_

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

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

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

## Workflows / Patterns / Lessons
- [name](workflows/name.md) | [name](patterns/name.md) | [topic](lessons/topic.md)

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

## Maintenance
Last checked: [date] | Action needed: [none / describe]

Hard limit: 60 lines. If exceeded — compress summaries, archive stale entries.

Privacy Enforcement

Tiered model. Not constant full audits.

Hard privacy rules — no exceptions:

1. Memory never written into repo directories.
2. Memory never in ~/claude-skill-vault/ or any skill file.
3. CLAUDE.md contains routing rules only — no personal data corpus.
4. Generated summaries, docs, exports: verify clean before output.
5. If workflow risks personal memory exposure — reroute or refuse. Never silently proceed.
6. This skill file contains zero personal content. Safe to publish as-is.

Maintenance Schedule

Lightweight and event-based by default. Heavy only when triggered.

Lightweight triggers (fix immediately, < 2 min)

Moderate triggers (next available, < 10 min)

Heavy maintenance (explicit request or threshold breach)

Never run heavy maintenance on routine sessions. Never reread all memory to verify unchanged state.

Agent Orchestration

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

When agents help:

Eight agent constraints — all apply:

1. Agent use is optional. Only when it saves real effort or cost.
2. Agents must not increase token load for trivial tasks.
3. Claude is the final authority on all memory writes, privacy checks, and structural changes.
4. Sensitive memory is minimized or excluded before passing to any agent.
5. No agent may externalize, restate, or broadly summarize personal memory.
6. Parallel agents only when tasks are independent and parallelism reduces total cost.
7. Simple tasks — no agent fanout. One operation = direct execution.
8. Agent outputs are compact and action-oriented. Claude applies them.

Quick Reference

Need memory?            → Activation Decision
Known alias/project?    → ALIASES.md (or .cache/) → direct load
Unknown route?          → INDEX.md → category file → detail if needed
Writing memory?         → Classify first → update existing compact
Resuming work?          → RESUME.md → load matching entry
Ending task?            → Continuity risk? Yes → write. No → skip.
Maintenance?            → Lightweight by default. Check triggers.
Privacy check?          → Tiered. Fail closed. Skip write on doubt.
Session cache?          → .cache/ — reuse routes, clear freely, never sensitive

Templates and entry schemas → memory-schema.md Skill token efficiency analysis → skill-optimizer.md