内容
# 🧠 mcp-memory-os — 便携式记忆、安全及自我修复层，为 AI 代理提供支持
[](LICENSE)
[](https://www.python.org)
[](https://github.com)
**停止构建无状态代理。** 将 Cursor、Claude Desktop 和自定义代理脚本转变为生产级开发者。 **mcp-memory-os** （由 UALL 提供支持）是一个轻量级、无依赖的引擎，您可以将其放入任何仓库中，为您的 AI 开发者提供长期记忆、执行安全保护和自我修复循环。
```
┌────────────────────────────────────────┐
│ AI 代理（Cursor/Claude） │
└──────────────────┬─────────────────────┘
│ （MCP / CLI）
┌──────────────────▼─────────────────────┐
│ mcp-memory-os │
└──────┬───────────┬──────────────┬──────┘
│ │ │
┌─────────────▼─────┐┌────▼────────┐┌────▼─────────────┐
│ 混合内存 ││ 治理 ││ 自我修复 │
│ SQLite FTS5 + 图谱││ 策略门 ││ 日志关联 │
└───────────────────┘└─────────────┘└──────────────────┘
```
---
## ⚡ 价值主张
| 功能 | 标准 AI 代理 | mcp-memory-os 增强型代理 |
| :--- | :--- | :--- |
| **上下文保留** | 单会话，忘记过去的文件路径和修复 | 混合 FTS5 + 实体关系知识图谱 |
| **执行安全** | 盲目运行任意命令（危险） | 命令前守卫匹配您的安全策略 |
| **持续学习** | 重复相同的错误并无限循环 | 故障关联挖掘 + 主动自我修复提示 |
| **状态跟踪** | 手动 git 提交（或无） | 成功质量门后自动验证 Git 检查点 |
---
## 🛠️ 代理循环
mcp-memory-os 将代理的行为组织成一个结构化的、连续的强化循环：
```mermaid
graph TD
A["初始化上下文（/task）"] --> B["记忆召回（/recall）"]
B --> C["影子跟踪命令（tracer.py）"]
C --> D["故障自动修复（self_heal.py）"]
D --> E["挖掘日志获取经验（/dream）"]
E --> F["评估和进化技能（/graduate）"]
F --> G["运行质量和 lint 门（/verify）"]
G --> H["Git 检查点状态（/checkpoint）"]
H --> A
```
---
## 🚀 安装和设置
### 1. 安装反重力插件（CLI/IDE 协调）
如果您在 Google 反重力（或支持反重力的 CLI/IDE）中开发，请安装插件以公开全局 MCP 服务器和执行钩子策略：
* **定位插件文件夹：** 确保此仓库中的 `plugin/` 目录可访问。
* **复制到全局插件目录：**
* **macOS / Linux：** 将 `plugin/` 目录复制到 `~/.gemini/config/plugins/uall-plugin/`
* **Windows：** 将 `plugin/` 目录复制到 `C:\Users\<username>\.gemini\config\plugins\uall-plugin\` （例如，`C:\Users\Johnny Cage\.gemini\config\plugins\uall-plugin\`）
* **重启代理：** 重启您的反重力 CLI 或重新加载您的 IDE 窗口以注册新的插件配置。
安装后：
* `hooks.json` 中定义的全局命令前安全检查将拦截命令。
* 全局 `uall-server` MCP 工具集变得可用。
---
### 2. 初始化项目（部署模板）
要在任何代码库工作区中运行 mcp-memory-os：
* **选项 A：运行 MCP 服务器工具（最简单）**
如果您已安装反重力插件并连接，您的代理可以直接调用 `uall_bootstrap` 工具。只需告诉您的代理：
> *"请使用 mcp-memory-os 初始化此项目"*
* **选项 B：运行初始化脚本**
将 `uall_bootstrap.py` 和 `uall.py` 复制到目标项目根目录并运行：
```bash
python uall_bootstrap.py
```
这会创建本地 `.agent/` 目录骨架，生成配置存根，并初始化 Git。
* **选项 C：通过主安装程序部署（可选）**
将预配置的模板包部署到目标目录：
```bash
python uall_master_installer.py /path/to/target/project
```
---
### 3. 设置 IDE 集成（MCP 服务器）
mcp-memory-os 公开一个本地模型上下文协议（MCP）服务器，以便 Cursor、Claude Desktop 或 VSCode 可以原生访问其工具。
在您的 IDE 的 MCP 设置中添加以下内容：
```json
{
"mcpServers": {
"agent-os": {
"command": "python",
"args": [".agent/tools/mcp_server.py"],
"cwd": "."
}
}
}
```
*（有关详细设置和配置，请参阅 [MCP_SETUP.md](file:///C:/Users/Johnny%20Cage/Projects/UALL-Antigravity/MCP_SETUP.md)）
---
## 📋 每日工作流程指南
设置完成后，通过项目根目录中的 `uall.py` 运行命令以管理您的 AI 代理：
### 1. 初始化任务上下文
在代理启动前，将工作区链接到特定的任务票（例如 Jira、Linear 或 GitHub 问题）：
```bash
python uall.py /task TASK-101
```
### 2. 召回项目记忆
让代理在编写代码前搜索语义历史、实体关系和主动避免失败的提示：
```bash
python uall.py /recall "JWT 身份验证逻辑"
```
### 3. 映射代码库结构（Graphifyy）
映射工作区中的所有类、方法、导入和调用。当安装 `graphify` 时，UALL 的图构建器将使用它作为主要的 AST/语义提取引擎，将这些关系直接输入到 `/recall` 内存索引中：
* **扫描和提取代码库：**
```bash
python uall.py /graphify
```
* **查询图连接：**
```bash
python uall.py /graphify --query "哪个模块包含用户登录处理程序？"
```
* **显示交互式可折叠树：**
```bash
python uall.py /graphify --tree
```
*（在 `graphify-out/GRAPH_TREE.html` 处输出交互式可视化）
### 4. 影子跟踪命令
使用 `tracer.py` 包装每个 shell 命令（例如编译、linting 或包安装），以便 mcp-memory-os 可以记录指标、跟踪文件和拦截错误：
```bash
python .agent/tools/tracer.py "npm install"
```
### 5. 自动修复故障
如果命令失败，请运行修复程序以分析逐期跟踪并自动生成上下文感知的主动提示：
```bash
python uall.py /heal
```
### 6. 运行质量和安全门
在提交前验证代码更改。此操作运行 Semgrep 安全检查、Ruff 格式化规则和 Pytest 套件：
```bash
python uall.py /verify
```
### 7. Git 检查点验证状态
当 `/verify` 返回 `VALID` 时，解锁并使用 Git 签名检查点提交保存当前进度：
```bash
python uall.py /checkpoint "初始身份验证实现"
```
*（如果代理破坏了您的代码，请使用 `python uall.py /recover` 立即回滚）
---
## 📦 架构和目录布局
mcp-memory-os 完全在便携式 `.agent/` 目录内本地运行：
```
.agent/
├── GOVERNANCE.md # 安全策略、风险等级和能力授予
├── PLAYBOOK.md # 从毕业的经验中自动生成的知识库
├── AGENTS.md # 角色定义和标准操作程序
├── memory/
│ ├── episodic/ # 命令期间捕获的每日 JSONL 事件日志
│ ├── candidate_lessons/ # 候选学习，等待毕业
│ ├── graduated/ # LESSONS.md + LESSONS.jsonl（源代码）
│ ├── graph/ # entities.md + relationships.jsonl 知识图谱
│ └── .index/ # SQLite FTS5 搜索索引数据库
├── skills/
│ ├── core/ # 内置系统指令
│ ├── domain/ # 毕业的项目特定技能
│ └── pending/ # 暂存技能，等待人工审查
├── protocols/
│ ├── semgrep_rules.yaml # 静态安全和结构检查
│ ├── hook_patterns.json # 事件驱动的前/后工具钩子
│ └── self_healing_hints.md # 从命令失败中构建的动态提示
└── tools/ # Python 引擎脚本（verify、recall、self_heal 等）
```
---
## 💎 主要功能
### 🧠 1. 混合语义和图谱记忆
标准搜索是不够的。mcp-memory-os 将 **SQLite FTS5 全文索引** 与 **实体关系知识图谱** 相结合，以跟踪代码依赖关系、以前的重构和文件映射。
* `/recall <query>` 查询词汇索引和代码关系以构建高度相关的上下文。
### 🛡️ 2. 命令前治理
保护您的环境。当您的代理尝试执行终端命令（例如 `git`、`docker`、`rm`）时，mcp-memory-os 工具钩子拦截器会根据 [.agent/GOVERNANCE.md](file:///C:/Users/Johnny%20Cage/Projects/UALL-Antigravity/.agent/GOVERNANCE.md) 验证命令。
* 自动批准安全命令（1 级）。
* 提示或记录中等风险活动（2 级）。
* 阻止高风险或未经授权的命令（3 级），直到获得批准。
### 🩹 3. 自我修复故障
当任务失败时，`tracer.py` 捕获跟踪信息和退出代码。`self_heal.py` 相关性重复故障以在 [protocols/self_healing_hints.md](file:///C:/Users/Johnny%20Cage/Projects/UALL-Antigravity/.agent/protocols/self_healing_hints.md) 中编写主动提示，这些提示将在代理下次尝试类似命令时自动注入到上下文中。
### 💾 4. 验证检查点和恢复
永远不要让代理破坏您的代码。
* `/verify` 运行 Semgrep 规则、Ruff 检查和 pytest 套件。
* 成功后，它解锁 `/checkpoint "<msg>"`，它创建代码和代理内存的 Git 签名快照。
* 如果代理偏离轨道，`/recover` 立即回滚代码库和脑状态到上一个验证的检查点。
---
> [!IMPORTANT]
> **mcp-memory-os** 完全开源、本地优先且不包含外部 API 依赖。所有内存、数据库索引和事件日志都直接存储在代码库的 `.agent/` 文件夹中。
---
## 🌟 支持和贡献
如果这个项目帮助您构建更好的代理，请给我们一个星 ⭐！欢迎贡献、错误报告和建议。
