什么是 持久化记忆？

持久化记忆是一种复杂的架构，旨在通过为事实、决策和指令提供永久存储解决方案，克服 AI 代理的环境限制。通过集成三个不同的层——用于人类可读性的 Markdown、用于语义向量搜索的 ChromaDB 以及用于关联知识图谱的 NetworkX——该技能确保了机构知识在代理重启后依然存在。在 Openclaw Skills 生态系统中，该系统充当代理的长期大脑，使其能够保持一致的人格和技术意识。

该技能最关键的方面之一是它修复常见记忆索引问题的能力。默认情况下，许多代理会忽略 SOUL.md 或 AGENTS.md 等基本指令文件。该技能重新配置代理的记忆搜索参数以确保优先处理这些文件，使指令合规性成为自动功能而非可选功能。

下载入口:https://github.com/openclaw/skills/tree/main/skills/jakebot-ops/persistent-memory

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

持久化记忆 应用场景

• 在长期开发环境中维护架构决策和经验教训。
• 以可搜索的格式存储有关团队成员、存储库 URL 和基础设施详细信息的机构事实。
• 通过将 SOUL.md 等指令文件索引到核心记忆搜索路径中，确保代理遵循严格的行为准则。
• 为代理提供引用日常日志和会话历史的能力，以回答有关过去工作的复杂问题。

1. 人类可读的 Markdown 文件（MEMORY.md、日常日志和参考文档）作为主要真相来源 (L1)。
2. 系统利用索引脚本通过 ChromaDB 将这些文件处理为向量嵌入，以实现语义搜索能力 (L2)。
3. 同时，索引器构建 NetworkX 知识图谱以映射关系和实体遍历 (L3)。
4. 专门的配置脚本更新内部记忆搜索块，以包含默认系统经常忽略的关键文件。
5. 代理在生成响应之前查询此多层系统，以确保准确性、上下文感知以及对工作空间规则的合规性。

持久化记忆 配置指南

要初始化记忆系统并确保正确的 Openclaw Skills 集成，请从工作区根目录执行统一设置脚本：

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

此脚本会自动安装 Python 依赖项（ChromaDB、NetworkX、sentence-transformers），创建向量数据库，并为指令合规性配置搜索集成。

持久化记忆 数据架构与分类体系

持久化记忆技能将信息组织成层级结构，以实现最高效率和清晰度：

强烈建议使用 reference/ 目录来存储机构事实，例如 people.md、repos.md 和 infrastructure.md。

name: persistent-memory
version: 3.0.0
description: Three-layer persistent memory system (Markdown + ChromaDB vectors + NetworkX knowledge graph) for long-term agent recall across sessions. One-command setup with automatic OpenClaw integration. Use when the agent needs to remember decisions, facts, context, or institutional knowledge between sessions.

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

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 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)

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

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

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:

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