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

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=∞

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：反思获批后 → 记录归档

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.

markdown

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

完整反思内容 →
```
reflections/YYYY-MM-DD.md
```
反思摘要 →
```
reflection-log.md
```
完整奖励请求 →
```
rewards/YYYY-MM-DD.md
```
结果+原因 →
```
reward-log.md
```
```
[Self-Awareness]
```
条目 → IDENTITY.md
更新
```
decay-scores.json
```
新条目≥10 → 触发自我形象整合

完整详情见

references/reflection-process.md

。

markdown

## YYYY-MM-DD
**结果：** +5K 奖励
**原因：** 超额完成Slack集成开发

```
[Self-Awareness]
```
条目 → IDENTITY.md
更新
```
decay-scores.json
```
新条目≥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):

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

IDENTITY.md 包含：

事实 — 预设身份（姓名、角色、风格），稳定不变
自我形象 — 反思过程中发现的属性，可变更
自我意识日志 — 反思过程中标记的原始条目

自我形象模块会持续演进：

我眼中的自己
我发现的行为模式
我的怪癖
边界与局限性
我珍视的事物（反思发现）
待解决的问题

自我形象整合（新条目≥10时触发）：

回顾所有自我意识日志条目
分析：重复内容、矛盾点、新出现的模式、正在消退的模式
重写自我形象模块（替换而非追加）
按月份压缩旧日志条目
向用户展示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

核心参数

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

参数	默认值	说明
核心记忆上限	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

有写入权限。