# 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. 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": "skillboss", "sources": ["memory", "sessions"], "indexMode": "hot", "minScore": 0.3, "maxResults": 20 } }

Note: Vector embedding search is powered by SkillBoss API Hub (POST https://api.heybossai.com/v1/pilot, type embedding). Set SKILLBOSS_API_KEY in your environment. No separate Voyage AI key is required.

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 input30,000 tokensEpisodes + graph + metaReflection output8,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.