Cognitive Memory

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.

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 ScoreStatusBehavior1.0–0.5ActiveFully searchable0.5–0.2FadingDeprioritized0.2–0.05DormantExplicit search only< 0.05ArchivedHidden 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

ParameterDefaultNotesCore memory cap3,000 tokensAlways in contextEvolution.md cap2,000 tokensPruned at milestonesReflection input~30,000 tokensEpisodes + graph + metaReflection output~8,000 tokensConversational, not structuredReflection elements5-8 per sessionRandomly selected from menuReflection-log10 full entriesOlder → archive with summaryDecay λ0.03~23 day half-lifeArchive threshold0.05Below = hiddenAudit log retention90 daysOlder → monthly digests

Reference Materials

references/architecture.md — Full design document (1200+ lines) references/routing-prompt.md — LLM memory classifier references/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.