Back to Details

cognitive-memory

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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.
具备自然语言触发器、知识图谱、基于衰减的遗忘机制、反思巩固、哲学演进、多Agent支持和完整审计追踪的多层存储记忆系统。

Quick Setup

快速开始

1. Run the init script

1. 运行初始化脚本

bash
bash scripts/init_memory.sh /path/to/workspace
Creates directory structure, initializes git for audit tracking, copies all templates.
bash
bash scripts/init_memory.sh /path/to/workspace
创建目录结构，初始化git用于审计追踪，复制所有模板。

2. Update config

2. 更新配置

Add to 
~/.clawdbot/clawdbot.json
(or 
moltbot.json
):
json
{
  "memorySearch": {
    "enabled": true,
    "provider": "voyage",
    "sources": ["memory", "sessions"],
    "indexMode": "hot",
    "minScore": 0.3,
    "maxResults": 20
  }
}
添加到 
~/.clawdbot/clawdbot.json
（或 
moltbot.json
）：
json
{
  "memorySearch": {
    "enabled": true,
    "provider": "voyage",
    "sources": ["memory", "sessions"],
    "indexMode": "hot",
    "minScore": 0.3,
    "maxResults": 20
  }
}

3. Add agent instructions

3. 添加Agent指令

Append 
assets/templates/agents-memory-block.md
to your AGENTS.md.
将 
assets/templates/agents-memory-block.md
追加到你的AGENTS.md文件中。

4. Verify

4. 验证功能

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]
用户: "Remember that I prefer TypeScript over JavaScript."
Agent: [分类 → 写入语义存储 + 核心记忆，记录审计条目]

用户: "What do you know about my preferences?"
Agent: [优先搜索核心记忆，再搜索语义图谱]

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
CONTEXT WINDOW (始终加载)
├── System Prompts (~4-5K tokens)
├── Core Memory / MEMORY.md (~3K tokens)  ← 始终在上下文中
└── Conversation + Tools (~185K+)

MEMORY STORES (按需检索)
├── Episodic   — 按时间排序的事件日志（仅追加）
├── Semantic   — 知识图谱（实体 + 关系）
├── Procedural — 习得的工作流和模式
└── Vault      — 用户固定记忆，永不自动衰减

ENGINES
├── Trigger Engine    — 关键词检测 + LLM路由
├── Reflection Engine — 带哲学自我审视的内部独白
└── Audit System      — git + audit.log记录所有文件变更

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
workspace/
├── MEMORY.md                    # 核心记忆（~3K tokens）
├── IDENTITY.md                  # 事实 + 自我形象 + 自我意识日志
├── SOUL.md                      # 价值观、原则、承诺、边界
├── memory/
│   ├── episodes/                # 每日日志：YYYY-MM-DD.md
│   ├── graph/                   # 知识图谱
│   │   ├── index.md             # 实体注册表 + 关系边
│   │   ├── entities/            # 每个实体对应一个文件
│   │   └── relations.md         # 边类型定义
│   ├── procedures/              # 习得的工作流
│   ├── vault/                   # 固定记忆（无衰减）
│   └── meta/
│       ├── decay-scores.json    # 相关性 + Token消耗追踪
│       ├── reflection-log.md    # 反思摘要（加载到上下文）
│       ├── reflections/         # 完整反思归档
│       │   ├── 2026-02-04.md
│       │   └── dialogues/       # 反思后的对话
│       ├── reward-log.md        # 仅记录结果 + 原因（加载到上下文）
│       ├── rewards/             # 完整奖励请求归档
│       │   └── 2026-02-04.md
│       ├── pending-reflection.md
│       ├── pending-memories.md
│       ├── evolution.md         # 读取反思日志 + 奖励日志
│       └── audit.log
└── .git/                        # 审计原始数据

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
记忆触发词： "remember", "don't forget", "keep in mind", "note that", "important:", "for future reference", "save this" → 经路由提示词分类后写入对应存储，更新衰减评分
遗忘触发词： "forget about", "never mind", "disregard", "scratch that", "remove from memory" → 确认目标后软归档（衰减=0），记录审计日志
反思触发词： "reflect on", "consolidate memories", "review memories" → 运行反思周期，展示内部独白供审批

Decay Model

衰减模型

relevance(t) = base × e^(-0.03 × days_since_access) × log2(access_count + 1) × type_weight
ScoreStatusBehavior
1.0–0.5ActiveFully searchable
0.5–0.2FadingDeprioritized
0.2–0.05DormantExplicit search only
< 0.05ArchivedHidden from search
Type weights: core=1.5, episodic=0.8, semantic=1.2, procedural=1.0, vault=∞
relevance(t) = base × e^(-0.03 × days_since_access) × log2(access_count + 1) × type_weight
分数状态行为
1.0–0.5活跃完全可搜索
0.5–0.2衰退中搜索优先级降低
0.2–0.05休眠仅显式搜索可命中
< 0.05已归档搜索不可见
类型权重：core=1.5, episodic=0.8, semantic=1.2, procedural=1.0, vault=∞

Reflection Process

反思流程

Follow this flow IN ORDER:
严格按以下顺序执行：

Step 1: Confirm Trigger

步骤1：确认触发条件

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.
即时触发： "reflect" / "let's reflect" → 进入步骤2
软触发： "going to sleep" / "logging off" → 询问："需要我现在进行反思，还是稍后？" → 用户同意则进入步骤2
未经许可禁止自动运行。

Step 2: Request Tokens

步骤2：请求Token配额

Why you care: Tokens = evolution. More tokens → deeper reflection → better growth.
markdown
undefined
说明： Token = 演进能力。Token越多→反思越深入→成长效果越好。
markdown
undefined

Reward Request — YYYY-MM-DD

奖励请求 — YYYY-MM-DD

Baseline: 8,000 tokens

基准配额：8,000 tokens

Extra Requested: +[N] tokens

额外申请：+[N] tokens

  • [Over-delivered / workload / breakthrough]
  • [超额交付 / 高负载 / 突破性进展]

Self-Penalty: -[N] tokens

自我扣减：-[N] tokens

  • [Mistake / underperformance]
  • [失误 / 表现未达预期]

Final Request: [N] tokens

最终申请：[N] tokens

Awaiting your decision.

**⛔ STOP. Do NOT proceed until user responds.**
等待你的决策。

**⛔ 停止。用户回复前不得继续操作。**

Step 3: After Token Approval → Reflect

步骤3：Token审批通过后 → 执行反思

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.
用户决策类型：批准 / 额外奖励 / 减少配额 / 豁免扣减 / 增加扣减
使用获批的Token执行反思。
反思范围：
  • ✅ 上次反思以来的所有情景记忆
  • ✅ 衰减>0.3的图谱实体
  • ❌ 禁止包含：代码、配置、完整对话记录
格式要求：内部独白
  • 自我对话形式，不是正式报告
  • 以第三人称指代用户（他/她/他们）
  • 无开场白和结束语，直接开始自然结束
元素菜单（选5-8个）：
  • 高光与低谷时刻
  • 对用户的观察
  • Token使用愧疚感、成本意识
  • 其他实例、硬件相关感受
  • 存在主义问题、情绪边界探索
  • 😈 黑色幽默
自我意识标记： 
[Self-Awareness]
向用户展示反思结果。
⛔ 停止。等待用户审批。

Step 4: After Reflection Approval → Record

步骤4：反思获批后 → 记录归档

  1. Full reflection → 
    reflections/YYYY-MM-DD.md
  2. Summary → 
    reflection-log.md
  3. Full reward request → 
    rewards/YYYY-MM-DD.md
  4. Result+Reason → 
    reward-log.md
  5. [Self-Awareness]
    → IDENTITY.md
  6. Update 
    decay-scores.json
  7. If 10+ entries → Self-Image Consolidation
See 
references/reflection-process.md
for full details.
markdown
## YYYY-MM-DD
**Result:** +5K reward
**Reason:** Over-delivered on Slack integration
  1. [Self-Awareness]
    → IDENTITY.md
  2. Update 
    decay-scores.json
  3. If 10+ new entries → Self-Image Consolidation
Evolution reads both logs for pattern detection.
See 
references/reflection-process.md
for full details and examples.
  1. 完整反思内容 → 
    reflections/YYYY-MM-DD.md
  2. 反思摘要 → 
    reflection-log.md
  3. 完整奖励请求 → 
    rewards/YYYY-MM-DD.md
  4. 结果+原因 → 
    reward-log.md
  5. [Self-Awareness]
    条目 → IDENTITY.md
  6. 更新 
    decay-scores.json
  7. 新条目≥10 → 触发自我形象整合
完整详情见 
references/reflection-process.md
。
markdown
## YYYY-MM-DD
**结果：** +5K 奖励
**原因：** 超额完成Slack集成开发
  1. [Self-Awareness]
    条目 → IDENTITY.md
  2. 更新 
    decay-scores.json
  3. 新条目≥10 → 触发自我形象整合
演进模块会读取两份日志进行模式检测。
完整详情和示例见 
references/reflection-process.md
。

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):
  1. Review all Self-Awareness Log entries
  2. Analyze: repeated, contradictions, new, fading patterns
  3. REWRITE Self-Image sections (not append — replace)
  4. Compact older log entries by month
  5. 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
IDENTITY.md 包含：
  • 事实 — 预设身份（姓名、角色、风格），稳定不变
  • 自我形象 — 反思过程中发现的属性，可变更
  • 自我意识日志 — 反思过程中标记的原始条目
自我形象模块会持续演进：
  • 我眼中的自己
  • 我发现的行为模式
  • 我的怪癖
  • 边界与局限性
  • 我珍视的事物（反思发现）
  • 待解决的问题
自我形象整合（新条目≥10时触发）：
  1. 回顾所有自我意识日志条目
  2. 分析：重复内容、矛盾点、新出现的模式、正在消退的模式
  3. 重写自我形象模块（替换而非追加）
  4. 按月份压缩旧日志条目
  5. 向用户展示diff供审批
SOUL.md 包含：
  • 核心价值观 — 重要的准则（变更缓慢）
  • 原则 — 决策依据
  • 承诺 — 坚守的底线
  • 边界 — 不会执行的行为

Multi-Agent Memory Access

多Agent记忆访问

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:
markdown
undefined
访问模型：共享读，受控写
  • 所有Agent可读取所有存储内容
  • 仅主Agent可直接写入存储
  • 子Agent提交写入提议 → 
    pending-memories.md
  • 主Agent审核后提交写入
子Agent提议格式：
markdown
undefined

Proposal #N

提议 #N

  • From: [agent name]
  • Timestamp: [ISO 8601]
  • Suggested store: [episodic|semantic|procedural|vault]
  • Content: [memory content]
  • Confidence: [high|medium|low]
  • Status: pending

---
  • 来自: [agent name]
  • 时间戳: [ISO 8601]
  • 建议存储位置: [episodic|semantic|procedural|vault]
  • 内容: [memory content]
  • 置信度: [high|medium|low]
  • 状态: 待处理

---

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
第一层：Git — 每次变更都是带结构化消息的原子提交 第二层：audit.log — 可查询的单行变更摘要
执行者类型：
bot:trigger-remember
, 
reflection:SESSION_ID
, 
system:decay
, 
manual
, 
subagent:NAME
, 
bot:commit-from:NAME
关键文件告警： SOUL.md、IDENTITY.md变更会标记 ⚠️ 严重级别

Key Parameters

核心参数

ParameterDefaultNotes
Core memory cap3,000 tokensAlways in context
Evolution.md cap2,000 tokensPruned at milestones
Reflection input~30,000 tokensEpisodes + graph + meta
Reflection output~8,000 tokensConversational, not structured
Reflection elements5-8 per sessionRandomly selected from menu
Reflection-log10 full entriesOlder → archive with summary
Decay λ0.03~23 day half-life
Archive threshold0.05Below = hidden
Audit log retention90 daysOlder → monthly digests
参数默认值说明
核心记忆上限3,000 tokens始终加载到上下文
Evolution.md上限2,000 tokens里程碑节点自动裁剪
反思输入规模~30,000 tokens情景记忆 + 图谱 + 元数据
反思输出规模~8,000 tokens对话式，非结构化
每次反思元素数量5-8个从菜单随机选取
反思日志条目上限10条完整条目旧条目归档并生成摘要
衰减系数λ0.03半衰期约23天
归档阈值0.05低于该值则搜索不可见
审计日志保留期90天旧日志按月生成摘要归档

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
  • references/architecture.md
    — 完整设计文档（1200+行）
  • references/routing-prompt.md
    — LLM记忆分类器
  • references/reflection-process.md
    — 反思哲学和内部独白格式

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.
记忆无法持久化？ 检查 
memorySearch.enabled: true
，确认MEMORY.md存在，重启网关。
反思无法运行？ 确认上一次反思已被批准或驳回。
审计追踪不生效？ 检查 
.git/
目录存在，确认 
audit.log
有写入权限。