内容
# 内存套件
适用于 AI 编程代理（Claude Code 及其他套件）的便携式、基于文件的**内存系统**：一个 CLI（`memoryctl`）和一个 MCP 服务器，将原始会话/历史来源转换为规范化的记录、原子事实、嵌入、搜索索引和审查门控摘要。
> 状态：**工程预览（黄色）**。下面的管道已实现并经过单元测试（289 个测试，在 Linux CI 3.11/3.12 和本地 Windows 上均为绿色）。尚未证明的是广泛的跨主机可移植性和 Windows 优先的引导安装程序 - 参见[已证明 vs 未证明](#已证明-vs-未证明)。
---
## 描述
`memory-harness-kit`（`memoryctl` 包）是适用于 AI 代理的**便携式文件内存**。它将“原始”来源（Claude Code 会话记录、git 历史、项目 `STATUS/HANDOFF` 文档、每日笔记、telegram 导出）转换为结构化、可搜索的内存 - 并通过 MCP 在每次会话启动时将其返回给代理。
所有内存都只是单个实例目录中的普通文件（`state/`、`runtime/`、`logs/`、`quarantine/`）：可见、可备份和版本控制，无需外部数据库。
### 内存功能
- **收集** 来自多个来源的原材料：会话记录、git 提交、项目文档、日记。
- **规范化** 为确定性记录（`records.jsonl`）并过滤类似机密的值。
- **提取原子**: 事件、实体、关系、**决策**（decisions）、**结果**（outcomes，例如“测试通过/失败”）、代码锚点 - 带有**链接**（linking）和**验证**（grounding）。
- **索引以便搜索**: 分块 → 嵌入 → 紧凑、矢量、BM25 和图索引。
- **语义搜索**: 混合搜索（矢量 + BM25）、带有回退的 `recall`、无需外部 API 的本地嵌入模型。
- **总结**: 每日/每周/每月总结；通过 cron 子代理的单独路径。
- **审查回路**: 重复模式检测和图审查队列 - **无自动提升**，全部通过显式审查包。
- **与 Claude Code 集成**: MCP 服务器自动启动，生命周期钩子（SessionStart/PreCompact/Stop）静默排空队列并重新构建索引。
### 管道
1. **基础** - `sources → normalize → atomics`。收集来源、规范化和提取原子（事件/实体/关系/决策/结果 + 链接 + 验证）。
2. **检索** - `chunk → embed → index → search`。嵌入（fastembed ONNX **或** 本地 EmbeddingGemma GGUF）、矢量 + BM25 + 图索引、混合搜索和召回。
3. **总结** - 从规范化和原子层生成每日/每周/每月总结，以及子代理提供者（LLM 总结通过 cron 子代理）。
4. **边车/审查** - 检索堆栈健康检查、重复审查、图审查队列；所有审查门控，无自动提升。
5. **集成/生命周期** - 用于 Claude Code 的 MCP 服务器、生命周期钩子、计划任务和一键安装程序（`scripts/bootstrap.ps1`，Windows 优先）。
### 已测试
总共 **289 个测试**，在本地（Windows）和 Ubuntu 的 CI 上（Python 3.11/3.12）均为绿色。
- **基础**: 收集器（5）、会话记录（29）、决策（16）、结果（17）、链接（20）、验证（17）、规范化和原子。
- **检索**: 嵌入（29）、索引（14）、BM25（5）、图（5）、搜索（6）。在 Linux 上的 CI 中运行 **实际的 fastembed 矢量召回** 的专用作业。
- **总结**: 聚合器（13）、子代理提供者（22）。
- **边车/MCP**: 边车（5）、MCP 服务器（12）。
- **打包**: 在本地和 GitHub Actions 中证明了 wheel/sdist 安装（`make ci-artifact-proof`）。
尚未**证明**的是：当前 Linux-CI 和 Windows 开发环境以外的广泛跨主机可移植性；Windows 优先的引导安装程序（手动，无自动测试）；调度器编排；原始 OpenClaw 运行时完整的替代。
---
## 功能
`memory-harness-kit` 将原始代理历史转换为可搜索的、基于文件的内存，并通过 MCP 将其返回。所有内容都作为一个实例根目录下的普通文件存在（`state/`、`runtime/`、`logs/`、`quarantine/`）- 可检查、可备份、无外部数据库。
**管道**:
| 管道 | 流程 | 关键模块 |
| --- | --- | --- |
| **基础** | 来源 → 规范化 → 原子 | `collectors/`、`normalize/`、`atomics/` （事件、实体、关系、决策、结果、链接、验证） |
| **检索** | 分块 → 嵌入 → 索引 → 搜索 | `embeddings/` （fastembed ONNX / 本地 EmbeddingGemma GGUF）、`indexes/` （紧凑、矢量、BM25、混合、图）、`search/` |
| **总结** | 记录/原子 → 每日/每周/每月 + 子代理 | `summarize/` （聚合器、子代理提供者） |
| **边车/审查** | 健康检查 + 重复 + 审查队列 | `sidecars/`、`indexes/review_queues` （审查门控、无自动提升） |
| **集成/生命周期** | MCP + 钩子 + 调度器 + 引导 | `mcp_server.py`、`scripts/hooks/`、`scripts/bootstrap.ps1` |
## 已证明 vs 未证明
**已证明（已实现 + 已测试）**:
- 289 个单元/契约测试在本地 Windows 和 GitHub Actions Ubuntu（Python 3.11 / 3.12）上均为绿色；
- 打包：wheel + sdist 安装证明，在本地和 CI 中（`make ci-artifact-proof`）；
- **实时** 检索：在 Linux 上，专用的 CI 作业安装 `[embeddings]` 额外包并运行实际的 fastembed 矢量召回；
- 完整的基础 + 检索 + 总结 + 边车管道在真实实例上运行端到端。
**未证明**:
- 当前 Linux-CI 和 Windows 开发环境以外的广泛跨主机可移植性；
- Windows 优先的引导安装程序（`scripts/bootstrap.ps1`）- 它在实践中有效，但没有自动证明；
- 调度器 / 任务调度器编排连接；
- 原始 OpenClaw 运行时的完整替代。
## CLI
所有命令都接受 `--root <instance>` 并支持 `--json`。
**设置和验证**
- `memoryctl doctor` - 基本环境总结（不是就绪验证器）
- `memoryctl init --root <path>` - 创建通用实例脚手架
- `memoryctl init-openclaw --root <path> --workspace-root <path>` - OpenClaw 绑定脚手架（`install-openclaw` 是已弃用的别名）
- `memoryctl validate --root <path>` - 验证配置、脚手架布局、适配器绑定
**基础管道**
- `memoryctl inventory-sources` - 收集有界源库存 + 清单
- `memoryctl inventory-git [--repo <path> ...]` - 收集 git 提交历史 → `git_commits.jsonl`
- `memoryctl ingest-session --session-id <id>` - 存储原始会话记录
- `memoryctl list-raw-sessions` - 列出存储的记录
- `memoryctl normalize-records` - 将库存规范化为确定性 `records.jsonl`
- `memoryctl build-foundation` - 库存 → 规范化 → 原子，一次传递
**检索管道**
- `memoryctl build-retrieval` - 分块 + 嵌入 + 紧凑/矢量索引（`embed-atomics` 是别名；来自 `memoryctl.yaml` 的提供者）
- `memoryctl build-index` - 关键词索引超过分块的 BM25
- `memoryctl build-graph-index` - 关系/图索引 + 审查队列候选者
- `memoryctl search --query <q> [--mode vector|bm25|hybrid]` - 嵌入分块的混合检索
- `memoryctl recall --query <q>` - 紧凑索引优先，矢量回退
**总结管道**
- `memoryctl build-summaries` - 每日 / 每周 / 每月总结
- `memoryctl summary-requests [--pending]` - 列出 LLM 总结请求包（子代理路径）
- `memoryctl apply-summary --request <packet>` - 将子代理生成的总结写回
**边车和集成**
- `memoryctl health-check` - 诊断基础/嵌入/索引层 → `ok|degraded|missing`
- `memoryctl recurrence-review` - 检测重复模式 → 审查包（无自动提升）
- `memoryctl recurrence-status` - 狭窄的 OpenClaw 重复状态切片
- `memoryctl mcp-serve` - 启动 MCP 标准输入/输出服务器（由 Claude Code 自动加载）
## 安装
### 手动（便携式核心）
```bash
cd /path/to/memory-harness-kit
python3 -m venv .venv
. .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e . # 核心（PyYAML）
pip install -e ".[embeddings]" # + fastembed ONNX 矢量检索
pip install -e ".[gguf]" # + 进程内 EmbeddingGemma GGUF 提供者
memoryctl doctor --json
```
通用实例烟雾测试：
```bash
memoryctl init --root /tmp/memory-instance
memoryctl validate --root /tmp/memory-instance --json # -> 状态：ok
memoryctl build-foundation --root /tmp/memory-instance --json
```
### 一键引导（Windows 优先）
`scripts/bootstrap.ps1` 将一个全新的克隆转换为工作安装（虚拟环境、嵌入式后端、配置、MCP 注册、计划任务、生命周期钩子）。它是幂等的，并支持 `-DryRun`。参见 [docs/Bootstrap_install.md](docs/Bootstrap_install.md)。
```powershell
powershell -ExecutionPolicy Bypass -File scripts\bootstrap.ps1 -DryRun
```
### Claude Code 集成
复制 `.claude/settings.example.json` → `.claude/settings.json`，设置 `<REPO_ROOT>` 和 `<INSTANCE_ROOT>`。然后，`memory` MCP 服务器自动加载；参见 [CLAUDE.md](CLAUDE.md) 以获取会话协议。
## CI
`make ci-smoke`（隔离的虚拟环境、可编辑安装、单元/契约套件、`init` + `validate` 烟雾测试）和 `make ci-artifact-proof`（轮子/sdist 构建 + 安装 + CLI 证明）。GitHub Actions 在 Ubuntu 3.11/3.12 上运行两者，以及实时 fastembed 检索作业 - 参见 [.github/workflows/ci-smoke.yml](.github/workflows/ci-smoke.yml)。
## 发布姿态
- 包版本 `0.1.0`，暂无公共发布标签；
- 许可证：Apache-2.0 通过顶级 [LICENSE](LICENSE)；
- 裁决：`yellow` / 工程预览 - 在故意切割更广泛的共享发布门控之前，将其视为预发布；
- 版本/标签/更改日志纪律： [docs/Release_policy.md](docs/Release_policy.md)， [CHANGELOG.md](CHANGELOG.md)。
## 文档地图
- [docs/Start_here.md](docs/Start_here.md) - 规范的 onboarding 地图和文档优先级
- [docs/Architecture.md](docs/Architecture.md) - 层（便携式核心 / 适配器 / 协调）
- [docs/Config_contract.md](docs/Config_contract.md) - `memoryctl.yaml` 形状
- [docs/Install_semantics.md](docs/Install_semantics.md) - 确切的命令承诺和边界
- [docs/Operator_install_guide.md](docs/Operator_install_guide.md) - 操作员安装/验证路径
- [docs/DevOps_readiness_checklist.md](docs/DevOps_readiness_checklist.md) - 已证明 vs 待证明的梯子
- [AGENTS.md](AGENTS.md) / [CLAUDE.md](CLAUDE.md) - 代理面对的入口
