Cognitive Memory

Memory store: ~/.memory/DOMAIN/ Operations script: /home/user/ken/orchestrator/memory_ops.py

Session Start Protocol

At the beginning of every session, recall relevant memories:

python3 /home/user/ken/orchestrator/memory_ops.py recall "" --domain ken --limit 10
python3 /home/user/ken/orchestrator/memory_ops.py tree --domain ken

Present a brief summary to the user:

• Recent changes and current state
• Open questions or low-confidence memories
• Any contradictions flagged but not yet resolved

Seven Cognitive Operations

1. REMEMBER — Encode new knowledge

python3 /home/user/ken/orchestrator/memory_ops.py encode ken <type> "content" \
  --tags tag1,tag2 --related id1,id2

Types: insight, decision, pattern, fact, preference

Importance → confidence mapping:

• 0.9: Critical decisions, corrections, structural changes
• 0.7: Important observations, verified facts
• 0.5: General notes, routine work
• 0.3: Temporary states, minor observations

2. RECALL — Semantic search

python3 /home/user/ken/orchestrator/memory_ops.py recall "natural language query" --domain ken --limit 10

Recall now uses TF-IDF semantic matching. You don't need exact keywords — conceptually related memories surface automatically. Each result includes a _score field.

Trust but verify: If a recalled memory has low confidence or a low score, say so. Don't present uncertain memories as facts.

3. UPDATE — Version a memory

python3 /home/user/ken/orchestrator/memory_ops.py update <id> "corrected content" --domain ken

Creates a new version. The old memory is preserved with reduced confidence and a superseded_by pointer. Use this when facts change — don't forget and re-encode, update.

4. LINK — Connect related memories

python3 /home/user/ken/orchestrator/memory_ops.py link <id_a> <id_b>

Creates a bidirectional edge. Use when you discover two memories are related — a breeding decision connects to a flock validation insight, a recipe correction connects to a transcription note.

5. CONSOLIDATE — Maintain memory health

python3 /home/user/ken/orchestrator/memory_ops.py consolidate --domain ken

Decays unrecalled memories, removes dead ones, and reports potential duplicates (>80% similarity). Run periodically or at session end.

6. TREE — See what we know

python3 /home/user/ken/orchestrator/memory_ops.py tree --domain ken

Shows memory count, types, edge connections, and version chains per domain.

7. FORGET — Intentional removal

python3 /home/user/ken/orchestrator/memory_ops.py forget <id> --domain ken

What Memory Is NOT

• Memory does NOT replace primary data files in this repository
• Memory does NOT override primary sources
• Memory does NOT store raw data — it stores conclusions about data
• Memory does NOT act autonomously — you decide when to remember and recall

Soli Deo Gloria

Careful, not clever. What we remember matters. What we forget matters too.

Domain-Specific: Hub / Orchestrator (Ken)

What to Encode

• Orchestrator decisions: Configuration changes, mode adjustments, adapter tuning
• Cross-repo observations: Patterns that span multiple repositories
• API behavior: Model response quirks, rate limits hit, cost patterns
• Skill development: What worked when building skills, patterns to reuse
• Infrastructure changes: Environment setup issues, dependency conflicts resolved

Encoding Patterns

# After an orchestrator configuration change
python3 /home/user/ken/orchestrator/memory_ops.py encode ken decision \
  "Switched Gemini adapter from free to paid tier for recipe mode. Free tier was hitting rate limits on batch operations." \
  --tags orchestrator,gemini,rate-limit,recipe

# After a cross-repo observation
python3 /home/user/ken/orchestrator/memory_ops.py encode shared pattern \
  "All 4 recipe repos need validation hooks. Deployed to Grandmasrecipes/Grannysrecipes first, then MomsRecipes/Allrecipes." \
  --tags hooks,recipes,deployment

What NOT to Encode

• API keys (never encode secrets)
• Full model responses (encode conclusions, not raw output)
• Things already in CLAUDE.md files across repos

v3 Upgrades (Research-Driven)

Protected Memories

Foundational knowledge that should NEVER decay, regardless of recall frequency.

# Encode as protected from the start
python3 /home/user/ken/orchestrator/memory_ops.py encode ken fact "content" --protected

# Protect an existing memory
python3 /home/user/ken/orchestrator/memory_ops.py protect <id> --domain ken

When to protect:

• Vocabulary conventions ("oleo means margarine")
• Core identity facts ("Kelsier is the gold standard sire")
• Architectural decisions that downstream work assumes
• Definitions that other memories reference implicitly

Auto-protection: Memories with 3+ graph edges are automatically protected during consolidation — if many things reference it, it is foundational by definition.

Cross-Domain Recall

Recall now searches ALL domains by default. Each result includes _domain so you know where it came from. This enables cross-pollination — a breeding pattern in sheep might inform resource organization in recipes.

# Search everywhere (default)
python3 /home/user/ken/orchestrator/memory_ops.py recall "optimization strategy"

# Restrict to one domain when you know what you want
python3 /home/user/ken/orchestrator/memory_ops.py recall "optimization strategy" --domain ken

Graph Centrality Scoring

Well-connected memories score higher in recall. A memory linked to 5 other memories ranks above an isolated memory with the same text similarity. This rewards knowledge that has been woven into the graph.

Score formula: similarity * confidence * (0.70 + 0.15*recency + 0.15*centrality)

Graph Traversal

Explore the knowledge graph from any memory:

# Direct neighbors
python3 /home/user/ken/orchestrator/memory_ops.py neighbors <id> --depth 1

# Neighbors of neighbors
python3 /home/user/ken/orchestrator/memory_ops.py neighbors <id> --depth 2

Tiered Storage (Active + Archive)

Old, low-confidence, unprotected memories are automatically archived during consolidation (>180 days, <0.3 confidence). Archived memories:

• Are preserved in ~/.memory/_archive/
• Are excluded from default recall (use --include-archive to search them)
• Can be promoted back: python3 memory_ops.py promote <id>
• Maintain graph edges for integrity

# Manually archive
python3 /home/user/ken/orchestrator/memory_ops.py archive <id> --domain ken

# Search including archive
python3 /home/user/ken/orchestrator/memory_ops.py recall "old topic" --include-archive

# Bring something back
python3 /home/user/ken/orchestrator/memory_ops.py promote <id>

Enhanced Consolidation

Consolidate is now smarter:

1. Decay — only unrecalled, unprotected, >7-day-old memories (protected are immune)
2. Auto-protect — memories with 3+ edges get protected automatically
3. Auto-merge — memories with >85% similarity are merged (tags combined, lower one archived)
4. Auto-archive — old (>180d), low-confidence (<0.3), unprotected memories move to archive
5. Near-duplicate flagging — 70-85% similarity reported for manual review