Memory

Memory 是一个面向 Coding Agent 的本地优先 MCP 记忆系统。

它的目标不是把整个代码库粗暴塞进上下文，而是通过“语义检索 + 代码骨架 + 依赖图谱 + 按需源码读取”这条分层链路，让 Agent 用更低的 Token 成本获得更精准的代码上下文。

当前版本：0.1.0

项目定位

在复杂代码库里，Agent 常见的两个问题是：

• 看不到全局结构，只能局部猜测
• 一次性读取太多源码，导致上下文成本过高

Memory 通过 4 个核心 MCP Tool，把“先定位、再勘探、再评估影响、最后按需读源码”的流程标准化：

• search_index：语义检索模块/文件入口
• get_skeleton：获取类、函数签名和 Docstring
• get_dependency：查询调用/依赖关系
• fetch_source：按文件或行号范围读取源码

核心特性

• 本地优先：所有核心能力都围绕本地运行设计，不依赖外部 API
• MCP 标准接入：以MCP Server 方式暴露能力，便于接入不同 Agent
• 双轨记忆：同时维护 Tree Memory 和 Graph Memory
• 增量同步：支持基于文件变更的增量解析与索引刷新
• 显式降级：索引缺失、解析失败、快照损坏时不会静默失败
• 热路径优化：对关键查询路径增加只读缓存与显式失效机制

系统图

当前能力范围

• Python src/ 包结构与测试基础设施
• Tree / Graph / Vector 存储适配层
• TreeMemory、GraphMemory、MemoryManager 核心编排
• 4 个 MCP Tool 的 Schema 契约与包装层
• 首次全量索引与缓存复用启动路径
• Python 增量 AST 解析、依赖提取与批处理 File Watcher
• 关键查询链路的缓存、失效与基准回归

当前仍然刻意保持的边界：

• server 启动入口不负责托管 watcher 常驻生命周期
• MVP 以 Python 为主，不在本阶段扩展完整多语言解析能力

安装

推荐环境：

• Python 3.11+

安装方式：

pip install .

如果你要参与开发，请改用：

pip install -e .[dev]

快速开始

直接启动 MCP Server：

python -m memory.server

如果你只想验证启动装配是否正常，而不是进入 stdio 常驻服务，可以在本地脚本中调用：

from memory.server import bootstrap_server

payload = bootstrap_server()
print(payload)

在 MCP Client 中接入

更推荐使用uv进行 (xd) 示例配置：

{
  "mcpServers": {
    "memory": {
      "type": "local",
      "command": [
        "uv",
        "--directory",
        "path/memory",
        "run",
        "-m",
        "memory.server"
      ],
      "enabled": true
    }
  }
}

将path/memory换为实际memory mcp位置 如果你的客户端配置格式和上面的 mcpServers 示例不完全一致，优先复用相同的 command / args / cwd 语义，再按客户端自身配置 schema 适配。

安装配套skill

将use-meemory-mcp-tools放入skills文件夹

运行机制

启动时，服务会先判断本地持久化产物是否可复用：

• 若缺少 tree / graph / vector 任一关键产物，进入 full_index_required 路径，执行首次全量索引
• 若本地产物完整可用，进入 reuse_cached_index 路径，直接复用缓存启动

当前入口职责只包含：

• 配置读取
• 项目根识别
• 存储布局准备
• 运行时装配
• 首次全量索引判定与执行
• MCP Tool 注册与 stdio 启动

存储目录

默认数据目录：

~/.memory/
└── <project_hash>/
    ├── tree.json
    ├── graph.json
    └── chroma/

说明：

• tree.json：树状记忆快照，保存项目/模块/文件骨架节点
• graph.json：依赖图谱快照，保存调用、依赖、继承等关系
• chroma/：本地向量索引目录，供 search_index 使用

项目结构

Memory/
├── docs/
├── src/memory/
│   ├── core/
│   ├── models/
│   ├── skills/
│   ├── storage/
│   ├── sync/
│   ├── config.py
│   └── server.py
├── tests/
├── pyproject.toml
├── README.md
└── LICENSE

性能与可靠性说明

• 文档目标是关键查询路径尽量逼近 <500ms
• 当前优化策略以本地快照复用、只读缓存和显式失效为主
• 遇到解析失败、快照损坏、索引缺失时，系统优先选择显式降级，而不是静默返回不可信结果

需要注意的是，当前基准更偏向本地测试环境下的热路径验证，不应直接等同于所有机器、所有规模项目下的统一性能承诺。

适用场景

这个项目适合：

• 需要给 Coding Agent 提供结构化代码记忆的本地工具链
• 希望在 MCP 体系下做代码检索、骨架勘探与依赖分析
• 想把“按需加载源码”作为默认开发策略的一部分

如果你要的是完整的云端知识库、远程向量服务，或者多语言全量生产级索引平台，这个仓库当前并不是那类产品定位。

贡献

欢迎通过 Issue 或 Pull Request 参与改进。

提交改动时，建议同时关注：

• MCP Tool 契约是否保持稳定
• 增量更新后缓存是否正确失效
• 文档是否与实现保持一致
• 是否引入了不必要的远程依赖

许可证

本项目采用 MIT License。

作者

• GuGuGuGun