Memory Management
Tiered memory system that makes an AI agent a continuous collaborator across sessions.
Architecture
The memory system has six tiers, configurable per project:
Tier 1: HOT CACHE (always loaded at boot -- ~200 lines target)
+-- <primer_file> Role, identity, constraints
+-- <boot_digest_file> Tactical status, active tasks
+-- <boot_contract_file> Immutable constraints
+-- <snapshot_file> Cognitive Hologram (1 sentence per file)
Tier 2: RLM SUMMARY LEDGER (fast keyword lookup -- loaded on demand)
+-- <summary_cache_file> Pre-generated text summaries: docs, protocols, research
Plugin: rlm-factory | Skill: rlm-search | Profile: project
+-- <tool_cache_file> Pre-generated text summaries: plugins, skills, scripts
Plugin: rlm-factory | Skill: rlm-search | Profile: tools
Tier 3: VECTOR STORE (semantic embedding search -- loaded on demand)
+-- <vector_db_backend> ChromaDB via vector-db plugin / vector-db-agent skill
Profile: knowledge | Port: configured in vector_profiles.json
Tier 4: DEEP STORAGE (filesystem -- authoritative source, loaded on demand)
+-- <domain_data_dir>/ Research topics: {topic}/analysis.md
+-- <design_docs_dir>/ ADRs, RFCs
+-- <governance_dir>/ Protocols, playbooks
Tier 5: VAULT (Obsidian -- linked knowledge graph, loaded on demand)
+-- <vault_dir>/ Plugin: obsidian-integration
Skills: obsidian-vault-crud, obsidian-canvas-architect,
obsidian-graph-traversal, obsidian-bases-manager
Env: VAULT_PATH or OBSIDIAN_VAULT_PATH
Tier 6: SOUL (external persistence -- optional, synced at session seal)
+-- <traces_file> Plugin: project-specific (e.g. huggingface-utils)
e.g. lineage/, data/, soul_traces.jsonl on HF Hub
Projects define their own file paths for each slot. Tiers may be omitted or added based on project complexity.
Lookup Flow (3-Phase Search Protocol)
When searching for information, ALWAYS escalate in order. Never skip ahead.
Query arrives ->
1. HOT CACHE Instant. Boot files cover ~90% of context needs.
2. DEEP STORAGE (topic/decision) Load specific domain dir or design doc by subject.
3. RLM SUMMARY LEDGER (Phase 1) Keyword search via query_cache.py.
4. VECTOR STORE (Phase 2) Semantic search via query.py + ChromaDB.
5. GREP / EXACT SEARCH (Phase 3) rg/grep scoped to paths from Steps 3 or 4.
6. Ask user Unknown? Learn it and persist it.
Phase 1 -- RLM Summary Scan (Table of Contents)
RLM is amortized prework: each file read ONCE, summarized ONCE, cached as plain text JSON.
Searching summaries is O(1) keyword lookup -- no embeddings, no inference.
bash
python3 plugins/rlm-factory/skills/rlm-search/scripts/query_cache.py \
--profile plugins "what does the vector query tool do"
python3 plugins/rlm-factory/skills/rlm-search/scripts/query_cache.py \
--profile project --list
Use Phase 1 when: You need to understand what a file does, find which file owns a feature,
or navigate the codebase without reading individual files.
Escalate to Phase 2 when: The summary is insufficient or no match found.
Phase 2 -- Vector Store Semantic Search (Back-of-Book Index)
Embedding-based nearest-neighbor search across all indexed chunks. Returns ranked
parent chunks with RLM Super-RAG context pre-injected.
bash
python3 plugins/vector-db/skills/vector-db-agent/scripts/query.py \
"nearest-neighbor embedding search implementation" \
--profile knowledge --limit 5
Use Phase 2 when: You need specific code snippets, patterns, or implementations.
Escalate to Phase 3 when: You have a file path (from Phase 1 or 2) and need an exact line.
Phase 3 -- Grep / Exact Search (Ctrl+F)
Precise keyword or regex match. Always scope to paths discovered in earlier phases.
bash
# Scoped to a specific path (use paths from Phase 1/2)
grep_search "VectorDBOperations" plugins/vector-db/skills/
# Ripgrep for regex
rg "def query" plugins/vector-db/ --type py
Anti-patterns: Never run a full-repo grep without scoping. Never skip Phase 1.
Dependencies
-- RLM Summary Ledger (Tier 2)
| Component | Value |
|---|
| Plugin | |
| Skill (write) | -- distill, inject, audit, cleanup |
| Skill (read) | -- query the ledger |
| Script: Phase 1 search | skills/rlm-search/scripts/query_cache.py
|
| Script: inject summary | skills/rlm-curator/scripts/inject_summary.py
|
| Script: audit coverage | skills/rlm-curator/scripts/inventory.py
|
| Script: shared config | skills/rlm-curator/scripts/rlm_config.py
|
| Cache files | .agent/learning/rlm_summary_cache.json
.agent/learning/rlm_tool_cache.json
|
-- Vector Store (Tier 3)
| Component | Value |
|---|
| Plugin | |
| Skill | -- ingest, query, operations |
| Script: Phase 2 search | skills/vector-db-agent/scripts/query.py
|
| Script: ingest files | skills/vector-db-agent/scripts/ingest.py
|
| Script: operations | skills/vector-db-agent/scripts/operations.py
|
| Script: config | skills/vector-db-agent/scripts/vector_config.py
|
| Backend | ChromaDB ( with fallback) |
-- Linked Vault (Tier 5)
| Component | Value |
|---|
| Plugin | plugins/obsidian-integration/
|
| Skill: vault setup | -- prerequisites, config, exclusion filters |
| Skill: read/write notes | skills/obsidian-vault-crud/
|
| Skill: markdown | skills/obsidian-markdown-mastery/
|
| Skill: canvas | skills/obsidian-canvas-architect/
|
| Skill: graph | skills/obsidian-graph-traversal/
|
| Skill: bases | skills/obsidian-bases-manager/
|
| Script: CRUD | skills/obsidian-vault-crud/scripts/vault_ops.py
|
| Script: parse | obsidian-parser/parser.py
|
| Requires | (lossless YAML frontmatter), Obsidian Desktop |
| Env | -- absolute path to the vault root |
Promotion / Demotion Rules
Promote to Hot Cache when:
- Knowledge is referenced in 3+ consecutive sessions
- It's critical for active work (current spec, active protocol)
- It's a constraint or identity anchor
Demote to Deep Storage when:
- Spec/feature is completed and merged
- Governing document is superseded by newer version
- Topic research is concluded
- Technical decision is ratified (move from draft to archive)
What Goes Where
| Type | Hot Cache | On-Demand Tier |
|---|
| Active tasks | Boot digest | -- |
| Identity/role | Primer file | -- |
| Constraints | Boot contract | -- |
| Session state | Snapshot file | Tier 6 Soul (traces) |
| Research topics | Summary in snapshot | Tier 4: |
| Design decisions | Referenced by ID | Tier 4: design_docs_dir/{id}_{name}.md
|
| Governing docs | Referenced by ID | Tier 4: governance_dir/{id}_{name}.md
|
| Plugins/scripts/tools | -- | Tier 2: RLM Summary Ledger (tool cache) |
| Docs/protocols/research | -- | Tier 2: RLM Summary Ledger (summary cache) |
| System docs | -- | Tier 2 RLM + Tier 3 Vector Store |
| Linked notes, canvases | -- | Tier 5: Vault (Obsidian) |
| External persistence | -- | Tier 6: Soul (HuggingFace or equivalent) |
Session Memory Workflow
At Session Start (Boot)
- Load hot cache files in order (primer -> contract -> digest -> snapshot)
- Integrity check validates snapshot is current
- If snapshot stale -> flag for refresh at session end
During Session
- New learning -> Write to
<domain_data_dir>/{topic}/
- New decision -> Create design document draft
- New tool -> Register in tool inventory
- Correction -> Update relevant file + note in disputes log if contradicting
At Session End (Seal)
- Update snapshot file with new content learned this session
- Seal validates no drift since last audit
- Persist traces to external storage (if configured)
Conventions
- Hot cache target: ~200 lines total across all boot files
- Snapshot: 1 sentence per file, machine-readable
- Topic folders:
- Document numbering: 3-digit, sequential
- Always capture corrections and contradictions in a disputes log
Configuration
Projects configure the memory system by setting file paths in their project-specific plugin:
| Variable | Purpose |
|---|
| Path to cognitive primer / role definition |
| Path to tactical boot digest |
| Path to immutable constraints |
| Path to learning snapshot (hologram) |
| Directory for domain research |
| Directory for design docs (e.g. ADRs) |
| Directory for governing docs (e.g. Protocols) |
Architecture Diagrams
| Diagram | What It Shows |
|---|
| memory_architecture.mmd | Full 4-tier memory system with exact plugin/skill/script names per tier |
| memory_lookup_flow.mmd | 3-phase search sequence: Hot Cache -> RLM Ledger -> Vector Store -> Grep |
| memory_session_lifecycle.mmd | Session Boot -> Active -> Seal lifecycle with all event types |