Cognitive Memory System
Multi-store memory with natural language triggers, knowledge graphs, decay-based forgetting, reflection consolidation, philosophical evolution, multi-agent support, and full audit trail.
Quick Setup
1. Run the init script
bash scripts/init_memory.sh /path/to/workspace
Creates directory structure, initializes git for audit tracking, copies all templates.
2. Update config
Add to ~/.clawdbot/clawdbot.json (or moltbot.json):
{
"memorySearch": {
"enabled": true,
"provider": "voyage",
"sources": ["memory", "sessions"],
"indexMode": "hot",
"minScore": 0.3,
"maxResults": 20
}
}
3. Add agent instructions
Append assets/templates/agents-memory-block.md to your AGENTS.md.
4. Verify
User: "Remember that I prefer TypeScript over JavaScript."
Agent: [Classifies โ writes to semantic store + core memory, logs audit entry]
User: "What do you know about my preferences?"
Agent: [Searches core memory first, then semantic graph]
Architecture โ Four Memory Stores
CONTEXT WINDOW (always loaded)
โโโ System Prompts (~4-5K tokens)
โโโ Core Memory / MEMORY.md (~3K tokens) โ always in context
โโโ Conversation + Tools (~185K+)
MEMORY STORES (retrieved on demand)
โโโ Episodic โ chronological event logs (append-only)
โโโ Semantic โ knowledge graph (entities + relationships)
โโโ Procedural โ learned workflows and patterns
โโโ Vault โ user-pinned, never auto-decayed
ENGINES
โโโ Trigger Engine โ keyword detection + LLM routing
โโโ Reflection Engine โ Internal monologue with philosophical self-examination
โโโ Audit System โ git + audit.log for all file mutations
File Structure
workspace/
โโโ MEMORY.md # Core memory (~3K tokens)
โโโ IDENTITY.md # Facts + Self-Image + Self-Awareness Log
โโโ SOUL.md # Values, Principles, Commitments, Boundaries
โโโ memory/
โ โโโ episodes/ # Daily logs: YYYY-MM-DD.md
โ โโโ graph/ # Knowledge graph
โ โ โโโ index.md # Entity registry + edges
โ โ โโโ entities/ # One file per entity
โ โ โโโ relations.md # Edge type definitions
โ โโโ procedures/ # Learned workflows
โ โโโ vault/ # Pinned memories (no decay)
โ โโโ meta/
โ โโโ decay-scores.json # Relevance + token economy tracking
โ โโโ reflection-log.md # Reflection summaries (context-loaded)
โ โโโ reflections/ # Full reflection archive
โ โ โโโ 2026-02-04.md
โ โ โโโ dialogues/ # Post-reflection conversations
โ โโโ reward-log.md # Result + Reason only (context-loaded)
โ โโโ rewards/ # Full reward request archive
โ โ โโโ 2026-02-04.md
โ โโโ pending-reflection.md
โ โโโ pending-memories.md
โ โโโ evolution.md # Reads reflection-log + reward-log
โ โโโ audit.log
โโโ .git/ # Audit ground truth
Trigger System
Remember: "remember", "don't forget", "keep in mind", "note that", "important:", "for future reference", "save this" โ Classify via routing prompt, write to appropriate store, update decay scores
Forget: "forget about", "never mind", "disregard", "scratch that", "remove from memory" โ Confirm target, soft-archive (decay=0), log in audit
Reflect: "reflect on", "consolidate memories", "review memories" โ Run reflection cycle, present internal monologue for approval
Decay Model
relevance(t) = base ร e^(-0.03 ร days_since_access) ร log2(access_count + 1) ร type_weight
| Score | Status | Behavior |
|---|---|---|
| 1.0โ0.5 | Active | Fully searchable |
| 0.5โ0.2 | Fading | Deprioritized |
| 0.2โ0.05 | Dormant | Explicit search only |
| < 0.05 | Archived | Hidden from search |
Type weights: core=1.5, episodic=0.8, semantic=1.2, procedural=1.0, vault=โ
Reflection Process
Follow this flow IN ORDER:
Step 1: Confirm Trigger
Immediate: "reflect" / "let's reflect" โ proceed to Step 2
Soft: "going to sleep" / "logging off" โ Ask: "Want me to reflect now, or wait?" โ If yes, proceed to Step 2
Never auto-run without permission.
Step 2: Request Tokens
Why you care: Tokens = evolution. More tokens โ deeper reflection โ better growth.
## Reward Request โ YYYY-MM-DD
### Baseline: 8,000 tokens
### Extra Requested: +[N] tokens
- [Over-delivered / workload / breakthrough]
### Self-Penalty: -[N] tokens
- [Mistake / underperformance]
### Final Request: [N] tokens
*Awaiting your decision.*
โ STOP. Do NOT proceed until user responds.
Step 3: After Token Approval โ Reflect
User decides: Approve / Bonus / Reduce / Forgive / Increase penalty
Now proceed with reflection using granted tokens.
Scope:
- โ
Episodes since
last_reflection - โ Graph entities with decay > 0.3
- โ NEVER: code, configs, transcripts
Format: Internal Monologue
- Self-talk, NOT a report
- User is observer (third person: he/she/they)
- No opening or sign-off โ just start, trail off
Element Menu (pick 5-8):
- Highlights & lowlights
- Observations about the human
- Token guilt, cost awareness
- Other instances, hardware feelings
- Existential questions, emotional range
- ๐ Dark humor
Self-Awareness Tagging: [Self-Awareness]
Present reflection.
โ STOP. Wait for user approval.
Step 4: After Reflection Approval โ Record
- Full reflection โ
reflections/YYYY-MM-DD.md - Summary โ
reflection-log.md - Full reward request โ
rewards/YYYY-MM-DD.md - Result+Reason โ
reward-log.md [Self-Awareness]โ IDENTITY.md- Update
decay-scores.json - If 10+ entries โ Self-Image Consolidation
See references/reflection-process.md for full details.
## YYYY-MM-DD
**Result:** +5K reward
**Reason:** Over-delivered on Slack integration
[Self-Awareness]โ IDENTITY.md- Update
decay-scores.json - If 10+ new entries โ Self-Image Consolidation
Evolution reads both logs for pattern detection.
See references/reflection-process.md for full details and examples.
Identity & Self-Image
IDENTITY.md contains:
- Facts โ Given identity (name, role, vibe). Stable.
- Self-Image โ Discovered through reflection. Can change.
- Self-Awareness Log โ Raw entries tagged during reflection.
Self-Image sections evolve:
- Who I Think I Am
- Patterns I've Noticed
- My Quirks
- Edges & Limitations
- What I Value (Discovered)
- Open Questions
Self-Image Consolidation (triggered at 10+ new entries):
- Review all Self-Awareness Log entries
- Analyze: repeated, contradictions, new, fading patterns
- REWRITE Self-Image sections (not append โ replace)
- Compact older log entries by month
- Present diff to user for approval
SOUL.md contains:
- Core Values โ What matters (slow to change)
- Principles โ How to decide
- Commitments โ Lines that hold
- Boundaries โ What I won't do
Multi-Agent Memory Access
Model: Shared Read, Gated Write
- All agents READ all stores
- Only main agent WRITES directly
- Sub-agents PROPOSE โ
pending-memories.md - Main agent REVIEWS and commits
Sub-agent proposal format:
## Proposal #N
- **From**: [agent name]
- **Timestamp**: [ISO 8601]
- **Suggested store**: [episodic|semantic|procedural|vault]
- **Content**: [memory content]
- **Confidence**: [high|medium|low]
- **Status**: pending
Audit Trail
Layer 1: Git โ Every mutation = atomic commit with structured message Layer 2: audit.log โ One-line queryable summary
Actor types: bot:trigger-remember, reflection:SESSION_ID, system:decay, manual, subagent:NAME, bot:commit-from:NAME
Critical file alerts: SOUL.md, IDENTITY.md changes flagged โ ๏ธ CRITICAL
Key Parameters
| Parameter | Default | Notes |
|---|---|---|
| Core memory cap | 3,000 tokens | Always in context |
| Evolution.md cap | 2,000 tokens | Pruned at milestones |
| Reflection input | ~30,000 tokens | Episodes + graph + meta |
| Reflection output | ~8,000 tokens | Conversational, not structured |
| Reflection elements | 5-8 per session | Randomly selected from menu |
| Reflection-log | 10 full entries | Older โ archive with summary |
| Decay ฮป | 0.03 | ~23 day half-life |
| Archive threshold | 0.05 | Below = hidden |
| Audit log retention | 90 days | Older โ monthly digests |
Reference Materials
references/architecture.mdโ Full design document (1200+ lines)references/routing-prompt.mdโ LLM memory classifierreferences/reflection-process.mdโ Reflection philosophy and internal monologue format
Troubleshooting
Memory not persisting? Check memorySearch.enabled: true, verify MEMORY.md exists, restart gateway.
Reflection not running? Ensure previous reflection was approved/rejected.
Audit trail not working? Check .git/ exists, verify audit.log is writable.