persistent-memory

三层持久内存系统（Markdown + ChromaDB 向量 + NetworkX 知识图）用于跨会话的长期代理回忆。通过自动 OpenClaw 集成进行一命令设置。当代理需要记住会话之间的决策、事实、背景或机构知识时使用。

## 概述（中文）

三层持久内存系统（Markdown + ChromaDB 向量 + NetworkX 知识图）用于跨会话的长期代理回忆。通过自动 OpenClaw 集成进行一命令设置。当代理需要记住会话之间的决策、事实、背景或机构知识时使用。

## 原文

# Persistent Memory

Adds persistent three-layer memory to any OpenClaw workspace. The agent gains semantic recall across sessions — decisions, facts, lessons, and institutional knowledge survive restarts.

## Architecture

| Layer | Technology | Purpose |
|-------|-----------|---------|
| L1: Markdown | MEMORY.md + daily logs + reference/ | Human-readable curated knowledge |
| L2: Vector | ChromaDB + all-MiniLM-L6-v2 | Semantic search across all memories |
| L3: Graph | NetworkX | Relationship traversal between concepts |

All three layers sync together. The indexer updates L2 and L3 from L1 automatically.

## ⚠️ Critical Integration: OpenClaw Memory Configuration

**Problem:** OpenClaw has its own built-in memory search system, but by default it only indexes `MEMORY.md` and `memory/*.md` files. Critical workspace files like `SOUL.md` (agent directives), `AGENTS.md` (behavior rules), and `PROJECTS.md` (active work) are **ignored**.

**Impact:** Agents can violate explicit directives because they're not found in memory searches. This causes operational failures where agents ignore their own rules.

**Solution:** The `configure_openclaw.py` script adds a `memorySearch` configuration block to OpenClaw that indexes all critical workspace files. This makes directive compliance **automatic** rather than optional.

## Setup

**One command from workspace root:**

```bash
bash skills/persistent-memory/scripts/unified_setup.sh
```

This automatically:
- ✅ Creates 3-layer memory system (Markdown + Vector + Graph)
- ✅ Installs all Python dependencies (ChromaDB, NetworkX, sentence-transformers)
- ✅ Configures OpenClaw memorySearch integration (directive compliance)
- ✅ Indexes existing MEMORY.md if present
- ✅ Sets up daily maintenance automation

**No manual configuration needed.** The script handles everything including OpenClaw integration that prevents agents from ignoring workspace directives (SOUL.md, AGENTS.md, etc.).

## Daily Usage

### Writing Memories

- **MEMORY.md** — Curated long-term knowledge (decisions, architecture, lessons learned). Update after significant events.
- **memory/YYYY-MM-DD.md** — Daily logs. Raw notes of what happened each day.
- **reference/*.md** — Institutional facts (people, repos, infrastructure, business rules). The agent's encyclopedia.

### Indexing (after editing any memory file)

```bash
vector_memory/venv/bin/python vector_memory/indexer.py
```

The indexer parses MEMORY.md, reference/*.md, and memory/*.md into vector embeddings and rebuilds the knowledge graph. Run after every edit to keep layers in sync.

### Searching

```bash
vector_memory/venv/bin/python vector_memory/search.py "your query"
```

Returns top-3 semantically similar chunks with source file and section.

### Sync Status Check

```bash
vector_memory/venv/bin/python vector_memory/auto_retrieve.py --status
```

Reports sync health: MEMORY.md hash vs indexed state, chunk count, graph size. Use in heartbeats to detect drift.

## Agent Behavior Rules

Add these to AGENTS.md or SOUL.md:

### Pre-Response (mandatory)
Before answering questions about prior work, decisions, dates, people, or preferences — search memory first. Use `memory_search` or run `auto_retrieve.py` with the query. Never say "I don't remember" without checking.

**CRITICAL:** OpenClaw's built-in memory search should now automatically find directive files (SOUL.md, AGENTS.md) if `configure_openclaw.py` was run. If memory searches are not finding agent rules or workspace directives, the OpenClaw integration is missing or broken.

### Pre-Action (mandatory)
Before executing any action that references an external identifier (URL, handle, email, repo name, address) — query `reference/` files for the exact value. If not found, query vector memory. If still not found, ask the user. **Never fabricate identifiers.**

### Post-Edit (mandatory)
After editing MEMORY.md or any file in reference/ or memory/ — re-index:
```bash
vector_memory/venv/bin/python vector_memory/indexer.py
```

### Heartbeat Integration
Add to HEARTBEAT.md:
```
## Memory Sync Check
Run `vector_memory/venv/bin/python vector_memory/auto_retrieve.py --status` and if status is OUT_OF_SYNC, re-index with `vector_memory/venv/bin/python vector_memory/indexer.py`.
```

## Reference Directory (Optional but Recommended)

Create `reference/` in the workspace root as the agent's institutional knowledge base:

```
reference/
├── people.md          — Contacts, roles, communication details
├── repos.md           — GitHub repositories, URLs, status
├── infrastructure.md  — Hosts, IPs, ports, services
├── business.md        — Company info, strategies, rules
└── properties.md      — Domain-specific entities (deals, products, etc.)
```

These files are vector-indexed alongside MEMORY.md. The agent queries them before any action involving external identifiers. Facts accumulate over time — the agent that never forgets.

## File Structure After Setup

```
workspace/
├── MEMORY.md              — Curated long-term memory (L1)
├── memory/
│   ├── 2026-02-17.md      — Daily log
│   └── heartbeat-state.json — Sync tracking
├── reference/             — Institutional knowledge (optional)
│   ├── people.md
│   └── ...
└── vector_memory/
    ├── indexer.py          — Index all markdown into vectors + graph
    ├── search.py           — Semantic search CLI
    ├── graph.py            — NetworkX knowledge graph
    ├── auto_retrieve.py    — Status checker + auto-retrieval
    ├── chroma_db/          — Vector database (gitignored)
    ├── memory_graph.json   — Knowledge graph (auto-generated)
    └── venv/               — Python venv (gitignored)
```

## Troubleshooting

- **"No module named chromadb"** — Run setup.sh again or activate the venv: `source vector_memory/venv/bin/activate`
- **OUT_OF_SYNC status** — Run the indexer: `vector_memory/venv/bin/python vector_memory/indexer.py`
- **Empty search results** — Check that MEMORY.md has content and the indexer has been run at least once
- **SIGSEGV on indexing** — Usually caused by incompatible ML libs. The setup script pins known-good versions.
- **Agent ignoring SOUL.md/AGENTS.md directives** — OpenClaw integration missing. Run `python skills/persistent-memory/scripts/configure_openclaw.py` to fix.
- **Memory searches not finding workspace files** — Check OpenClaw configuration: `openclaw config get | grep memorySearch`
- **"Configuration verification failed"** — Restart OpenClaw manually: `openclaw gateway restart`

---

## 中文说明

# 持久内存

为任意 OpenClaw 工作区添加持久的三层内存。代理由此获得跨会话的语义回忆能力——决策、事实、经验教训和机构知识在重启后依然保留。

## 架构

| 层级 | 技术 | 用途 |
|-------|-----------|---------|
| L1：Markdown | MEMORY.md + 每日日志 + reference/ | 人类可读的精选知识 |
| L2：向量 | ChromaDB + all-MiniLM-L6-v2 | 跨所有记忆的语义搜索 |
| L3：图 | NetworkX | 概念之间的关系遍历 |

三层会一同同步。索引器自动根据 L1 更新 L2 和 L3。

## ⚠️ 关键集成：OpenClaw 内存配置

**问题：** OpenClaw 有自己内置的内存搜索系统，但默认只索引 `MEMORY.md` 和 `memory/*.md` 文件。诸如 `SOUL.md`（代理指令）、`AGENTS.md`（行为规则）和 `PROJECTS.md`（进行中的工作）等关键工作区文件会被**忽略**。

**影响：** 代理可能违反明确的指令，因为它们没有在内存搜索中被找到。这会导致代理无视自身规则的运行失败。

**解决方案：** `configure_openclaw.py` 脚本会向 OpenClaw 添加一个 `memorySearch` 配置块，用于索引所有关键工作区文件。这使指令合规变为**自动**而非可选。

## 设置

**在工作区根目录执行一条命令：**

```bash
bash skills/persistent-memory/scripts/unified_setup.sh
```

该命令会自动：
- ✅ 创建三层内存系统（Markdown + 向量 + 图）
- ✅ 安装所有 Python 依赖（ChromaDB、NetworkX、sentence-transformers）
- ✅ 配置 OpenClaw memorySearch 集成（指令合规）
- ✅ 索引现有的 MEMORY.md（如果存在）
- ✅ 设置每日维护自动化

**无需手动配置。** 脚本会处理一切，包括防止代理无视工作区指令（SOUL.md、AGENTS.md 等）的 OpenClaw 集成。

## 日常使用

### 写入记忆

- **MEMORY.md** —— 精选的长期知识（决策、架构、经验教训）。在重大事件后更新。
- **memory/YYYY-MM-DD.md** —— 每日日志。记录每天发生情况的原始笔记。
- **reference/*.md** —— 机构事实（人员、仓库、基础设施、业务规则）。代理的百科全书。

### 索引（在编辑任何记忆文件后）

```bash
vector_memory/venv/bin/python vector_memory/indexer.py
```

索引器将 MEMORY.md、reference/*.md 和 memory/*.md 解析为向量嵌入，并重建知识图。每次编辑后运行，以保持各层同步。

### 搜索

```bash
vector_memory/venv/bin/pyt