brain-cms

用于 OpenClaw 代理的连续内存系统 (CMS)。用受大脑启发的多层记忆架构取代平面 MEMORY.md — 语义模式、海马路由器 (INDEX.md)、向量存储 (LanceDB + nomic-embed-text) 以及用于整合的自动化 NREM/REM 睡眠周期。基于神经科学研究（LTP、扩散激活、CMS 理论）。在设置持久代理内存、提高上下文效率或降低长时间运行代理的令牌成本时使用。触发因素：大脑、记忆系统、CMS、长期记忆、向量存储、睡眠周期、NREM、REM、记忆架构、语义记忆、情境效率。

# Brain CMS 🧠

A neuroscience-inspired memory architecture for OpenClaw agents.
Replaces flat file injection with sparse, semantic, frequency-gated memory loading.

## What This Installs

```
memory/
├── INDEX.md          ← Hippocampus: topic router + cross-links
├── ANCHORS.md        ← Permanent high-significance event store
└── schemas/          ← Domain-specific semantic schemas (you create these)

memory_brain/
├── index_memory.py   ← Embeds schemas into LanceDB vector store
├── query_memory.py   ← Semantic similarity search
├── nrem.py           ← NREM sleep cycle (compression + anchor promotion)
├── rem.py            ← REM sleep cycle (LLM consolidation via Ollama)
└── vectorstore/      ← LanceDB database (auto-created)
```

## Setup (one-time)

```bash
# 1. Run the installer
python3 ~/.openclaw/workspace/skills/brain-cms/install.py

# 2. Index your schemas
cd ~/.openclaw/workspace/memory_brain
.venv/bin/python3 index_memory.py

# 3. Test retrieval
.venv/bin/python3 query_memory.py "your topic here" --sources-only
```

## How It Works

**Boot sequence:** Load MEMORY.md (lean core) + today's daily log. Nothing else.

**When a topic appears:** Read `memory/INDEX.md` → load only the relevant schemas (spreading activation). Check `memory/ANCHORS.md` for high-significance events.

**For ambiguous topics:** Run semantic search:
```bash
memory_brain/.venv/bin/python3 memory_brain/query_memory.py "message text" --sources-only
```

**Auto-schema creation:** When a new significant project or domain appears:
1. Create `memory/<topic>.md`
2. Add to INDEX.md with triggers + priority + cross-links
3. Re-index: `memory_brain/.venv/bin/python3 memory_brain/index_memory.py`

**Sleep cycles:**
```bash
# NREM — run on shutdown (~30s, no LLM)
cd ~/.openclaw/workspace/memory_brain && .venv/bin/python3 nrem.py

# REM — run weekly (2-5 min, uses local llama3.2:3b, free)
cd ~/.openclaw/workspace/memory_brain && .venv/bin/python3 rem.py
```

## Memory Layers (CMS)

| Layer | Files | When loaded | Purpose |
|-------|-------|-------------|---------|
| Working | `MEMORY.md` + today log | Every session | Core context |
| Episodic | `memory/YYYY-MM-DD.md` | Session boot | Recent events |
| Semantic | `memory/*.md` schemas | On trigger | Domain knowledge |
| Anchors | `memory/ANCHORS.md` | On CRITICAL topics | Permanent ground truth |
| Vector | `memory_brain/vectorstore/` | On demand | Semantic search |

## Tagging Anchors
In any daily log, tag high-significance events:
```
[ANCHOR] Major demo success — full pipeline working end-to-end
```
NREM auto-promotes these to ANCHORS.md on next shutdown.

## Token Savings
Typical MEMORY.md: 150-300 lines injected every session.
With Brain CMS: ~50-line core + schemas loaded only when relevant.
Estimated savings: 40-60% reduction in context tokens per session.

## Requirements
- Python 3.10+
- Ollama (for embeddings + REM consolidation)
- 500MB+ storage for vector store and models
- `lancedb`, `numpy`, `pyarrow`, `requests` (auto-installed)

---

## 中文说明

# Brain CMS 🧠

一个受神经科学启发的 OpenClaw 代理内存架构。
用稀疏、语义化、频率门控的内存加载取代扁平文件注入。

## 此技能安装的内容

```
memory/
├── INDEX.md          ← Hippocampus: topic router + cross-links
├── ANCHORS.md        ← Permanent high-significance event store
└── schemas/          ← Domain-specific semantic schemas (you create these)

memory_brain/
├── index_memory.py   ← Embeds schemas into LanceDB vector store
├── query_memory.py   ← Semantic similarity search
├── nrem.py           ← NREM sleep cycle (compression + anchor promotion)
├── rem.py            ← REM sleep cycle (LLM consolidation via Ollama)
└── vectorstore/      ← LanceDB database (auto-created)
```

## 设置（一次性）

```bash
# 1. Run the installer
python3 ~/.openclaw/workspace/skills/brain-cms/install.py

# 2. Index your schemas
cd ~/.openclaw/workspace/memory_brain
.venv/bin/python3 index_memory.py

# 3. Test retrieval
.venv/bin/python3 query_memory.py "your topic here" --sources-only
```

## 工作原理

**启动序列：** 加载 MEMORY.md（精简核心）+ 今天的每日日志。其他什么都不加载。

**当某个主题出现时：** 读取 `memory/INDEX.md` → 仅加载相关的 schema（扩散激活）。检查 `memory/ANCHORS.md` 中的高重要性事件。

**对于含糊的主题：** 运行语义搜索：
```bash
memory_brain/.venv/bin/python3 memory_brain/query_memory.py "message text" --sources-only
```

**自动创建 schema：** 当出现一个新的重要项目或领域时：
1. 创建 `memory/<topic>.md`
2. 添加到 INDEX.md，附带触发词 + 优先级 + 交叉链接
3. 重新索引：`memory_brain/.venv/bin/python3 memory_brain/index_memory.py`

**睡眠周期：**
```bash
# NREM — run on shutdown (~30s, no LLM)
cd ~/.openclaw/workspace/memory_brain && .venv/bin/python3 nrem.py

# REM — run weekly (2-5 min, uses local llama3.2:3b, free)
cd ~/.openclaw/workspace/memory_brain && .venv/bin/python3 rem.py
```

## 内存层级（CMS）

| 层级 | 文件 | 何时加载 | 用途 |
|-------|-------|-------------|---------|
| 工作记忆 | `MEMORY.md` + today log | 每个会话 | 核心上下文 |
| 情景记忆 | `memory/YYYY-MM-DD.md` | 会话启动时 | 近期事件 |
| 语义记忆 | `memory/*.md` schemas | 触发时 | 领域知识 |
| 锚点 | `memory/ANCHORS.md` | 遇到 CRITICAL 主题时 | 永久性基准事实 |
| 向量 | `memory_brain/vectorstore/` | 按需 | 语义搜索 |

## 标记锚点
在任何每日日志中，标记高重要性事件：
```
[ANCHOR] Major demo success — full pipeline working end-to-end
```
NREM 会在下次关机时自动将这些事件提升到 ANCHORS.md。

## 令牌节省
典型的 MEMORY.md：每个会话注入 150-300 行。
使用 Brain CMS：约 50 行核心 + 仅在相关时加载的 schema。
预计节省：每个会话上下文令牌减少 40-60%。

## 要求
- Python 3.10+
- Ollama（用于嵌入 + REM 整合）
- 500MB+ 用于向量存储和模型的存储空间
- `lancedb`、`numpy`、`pyarrow`、`requests`（自动安装）