| name | cognitive-memory |
| description | Cross-repository cognitive memory system with semantic search. Persists knowledge across sessions using TF-IDF recall, memory versioning, knowledge graph edges, and confidence decay. Memory is cognition, not storage. |
| trigger | [{"keyword":["memory","remember","recall","forget","what do we know","last session","previous session","what was","do you remember"]},{"intent":["recalling past context","storing new knowledge","resolving contradictions","session continuity"]},{"event":"session_start"}] |
| priority | high |
| version | 3.0.0 |
Cognitive Memory System v3
Memory as stewardship: what we remember shapes how we serve.
What's New in v2
- Semantic search: TF-IDF + cosine similarity replaces keyword matching. "deworming resistance" finds "FAMACHA scoring" and "parasite resistance" even without shared words.
- Memory versioning:
update creates a new version, preserves the original with supersedes chain.
- Knowledge graph:
link creates bidirectional edges between related memories.
- Duplicate detection:
consolidate flags memories with >80% similarity.
- Recency boost: Recent memories score higher. Old unrecalled memories decay.
Overview
This skill provides persistent cognitive memory across Claude Code sessions. It is NOT a database — it is a reasoning layer that encodes selectively, consolidates contradictions, recalls semantically, and forgets intentionally.
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 photography --limit 10
python3 /home/user/ken/orchestrator/memory_ops.py tree --domain photography
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 photography <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 photography --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 photography
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 photography
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 photography
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 photography
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: Photography E-Commerce (Flickers of Majesty)
What to Encode
- Product decisions: Why a print was added/removed, pricing changes, sizing decisions
- Design patterns: What worked for product pages, gallery layouts, conversion insights
- Voice calibration: Descriptions that passed voice-audit vs. ones that drifted
- Technical lessons: Image processing quirks, WebP conversion issues, print lab requirements
- Customer patterns: What buyers respond to (without storing personal data)
Encoding Patterns
python3 /home/user/ken/orchestrator/memory_ops.py encode photography decision \
"Mountain Majesty added at $49-$299 range. Metal prints for this image because the blacks need to go absolute. Canvas softens it too much." \
--tags mountain-majesty,product,pricing,metal
python3 /home/user/ken/orchestrator/memory_ops.py encode photography pattern \
"Product descriptions work best at 2-3 sentences. One about the moment, one about the medium, one about where it belongs. Anything more reads like catalog copy." \
--tags voice,product-description,pattern
What NOT to Encode
- Product HTML (that's in the product pages)
- CSS standards (that's in the standards files)
- Image files or metadata
v3 Upgrades (Research-Driven)
Protected Memories
Foundational knowledge that should NEVER decay, regardless of recall frequency.
python3 /home/user/ken/orchestrator/memory_ops.py encode photography fact "content" --protected
python3 /home/user/ken/orchestrator/memory_ops.py protect <id> --domain photography
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.
python3 /home/user/ken/orchestrator/memory_ops.py recall "optimization strategy"
python3 /home/user/ken/orchestrator/memory_ops.py recall "optimization strategy" --domain photography
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:
python3 /home/user/ken/orchestrator/memory_ops.py neighbors <id> --depth 1
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
python3 /home/user/ken/orchestrator/memory_ops.py archive <id> --domain photography
python3 /home/user/ken/orchestrator/memory_ops.py recall "old topic" --include-archive
python3 /home/user/ken/orchestrator/memory_ops.py promote <id>
Enhanced Consolidation
Consolidate is now smarter:
- Decay — only unrecalled, unprotected, >7-day-old memories (protected are immune)
- Auto-protect — memories with 3+ edges get protected automatically
- Auto-merge — memories with >85% similarity are merged (tags combined, lower one archived)
- Auto-archive — old (>180d), low-confidence (<0.3), unprotected memories move to archive
- Near-duplicate flagging — 70-85% similarity reported for manual review