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 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.