memex

memex：面向 Agent 软件工程的可信工程上下文

开源 MCP 服务和钩子服务，可在代码变更时持续更新 Claude Code 和 Codex 的工程上下文，并暂缓应用证据已发生变化的编辑。

memex.stifler.in

守护进程、钩子服务和 MCP 服务，可将提交和文件变更转化为结构化工程知识，并在保留时效性和来源信息的前提下将其提供给 Agent，而不会让 memex 成为个人记忆或原始会话状态的来源。

memex 会为你的代码库构建双时态知识图谱（模块、符号、决策、问题、证据和代码演变）。v1 还会接入 Claude Code 和 Codex：每个会话启动时都会获得恰当的上下文，每次编辑都会根据当前代码进行检查，并准确告知 Agent 发生了什么变化。

memex 所在位置

评估记录见 BENCHMARK.md，版本历史见 CHANGELOG.md，问题报告流程见 SECURITY.md， 参与项目开发的方法见 CONTRIBUTING.md。

https://github.com/user-attachments/assets/b14e3185-ea36-4ae5-bd18-2d34e6bf7be4

60 秒了解 memex v1。如果播放器无法加载，下载视频。

实时上下文（v1）

编码 Agent 基于代码快照工作。队友推送代码，另一个 Agent 编辑文件，分支发生变化，而 Agent 仍继续依据之前读取的内容操作。v1 会在 Claude Code 和 Codex 中保持该快照最新：

uv tool install memex-mcp          # installs the `memex` command
cd your-repo
memex v1 doctor                    # what is set up, what is missing, what to do next
memex v1 install claude            # hooks in .claude/settings.json; global settings untouched
memex v1 install codex --neo4j-uri bolt://localhost:7687   # optional, for Codex

memex 需要你已在运行的 Neo4j 5 服务（无需 Docker）。钩子只会写入检出目录自身的项目配置，memex 也绝不会索取或存储你的客户端凭据。完整指南、主机配置示例和回滚说明： docs/v1/25_ONBOARDING.md。

flowchart LR
    A[Your repository<br/>files + git] --> B[memex watcher<br/>tree-sitter + Gemini]
    B --> C[Neo4j graph<br/>bitemporal facts]
    C --> D[memex core<br/>ContextPacket selection]
    D --> H[Hook service<br/>session start · edit checks · resume notice]
    D --> E[Hermes MemoryProvider<br/>automatic read-only prefetch]
    D --> F[MCP tools<br/>explicit lookup]
    H --> G[Claude Code / Codex]
    E --> G
    F --> G

    style B fill:#cfe8ff,stroke:#0066cc,color:#000
    style C fill:#fff4cf,stroke:#cc9900,color:#000
    style H fill:#d4f5d4,stroke:#2d8f2d,color:#000

安装

通过 Claude Code marketplace

/plugin marketplace add STiFLeR7/claude-plugins
/plugin install memex-mcp@stifler-marketplace

重启 Claude Code 会话。

安装或升级后的首次启动会下载 memex 的 Python 依赖项（约 40 秒），可能会超过 Claude Code 的 MCP 连接超时时间。请先预热，再重启：

npx -y stifler-memex-mcp --help     # one-time download; later starts take a few seconds

如果 Claude Code 仍显示连接超时，请打开 /mcp 并重新连接 memex。如果工具提示 memex 无法连接 Neo4j，请启动 Neo4j（例如 docker start memex-neo4j）；工具无需重启即可恢复。

手动安装

docker compose -f docker/docker-compose.yml up -d
cat > .env <<EOF
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=memex-local
GEMINI_API_KEY=your-key-here
EOF
npx stifler-memex-mcp init --repo .
npx stifler-memex-mcp watch --repo .
npx stifler-memex-mcp serve --repo .

Hermes 集成

Hermes 集成为只读模式。Hermes 会保留个人记忆、原始会话状态和执行状态。memex 通过有界的 ContextPacket 提供代码库工程上下文；它不会导入 Hermes 的 state.db、转录内容、提示词或工具结果。

将 memex 提供方添加到 Hermes 的配置文件中：

memory:
  provider: memex
plugins:
  memex:
    repo_path: /absolute/path/to/repository
    prefetch_timeout_seconds: 7
    max_items: 8
    max_chars: 12000

如果尚未安装 Hermes，请通过 MCP get_engineering_context 工具使用相同的上下文选择器。这两种方式共用与协议无关的 memex 核心，并在检索不可用时放行。

团队自托管部署

适用于共享团队环境（一个 Neo4j + 一个 memex-server，默认启用身份验证，Neo4j 的端口绝不暴露给主机）：

bash docker/bootstrap-team-env.sh
docker compose -f docker/docker-compose.team.yml up -d

完整流程、初始管理员密钥的保存方法，以及需要避免的 down -v 陷阱，请参阅 docker/TEAM-DEPLOY.md。

概览

生命周期

flowchart TD
    Init[memex init<br/>extract baseline] --> Watch[memex watch<br/>daemon + git hooks]
    Watch -->|commit| Extract[tree-sitter extract<br/>symbols, imports, lockfile]
    Extract --> Synth[Gemini Flash<br/>diff → Decision nodes]
    Synth --> Write[Graphiti add_episode<br/>+ post-hoc bitemporal SET]
    Write --> Decay[Scheduler<br/>nightly confidence decay]
    Decay -->|stale edges| Archive[expired_at = now]

    Serve[memex serve<br/>MCP stdio/HTTP] -.->|reads| Write
    Agent[AI agent] -->|14 MCP tools| Serve
    Serve -->|record_decision / record_problem| Write

    Cluster[memex cluster<br/>Leiden over hybrid edges] -.->|every N commits| Write

    style Init fill:#e8f4ff,color:#000
    style Watch fill:#fff4cf,color:#000
    style Synth fill:#ffe0cc,color:#000
    style Serve fill:#d4f5d4,color:#000

MCP 工具

共 14 个工具：8 个读取、4 个写入、2 个分析。

读取

写入

双时态置信度

置信度不是一个会发生变化的存储数值。它会在查询时根据 base_confidence、验证状态、自上次强化以来的时间以及访问次数计算。

flowchart LR
    Edge[Edge created<br/>base_confidence] --> Q{Validated by<br/>a human?}
    Q -->|yes| Slow[Slow regime<br/>half-life ~139d]
    Q -->|no| Fast[Fast regime<br/>stale at exactly 30d]
    Slow --> Score[Composite score<br/>conf × recency × rehearsal]
    Fast --> Score
    Score -->|below floor| Stale[get_stale_context surfaces it]
    Score -->|access| Bump[last_reinforced_at updated]
    Bump --> Score

    style Slow fill:#d4f5d4,color:#000
    style Fast fill:#ffd4d4,color:#000

分层集群

memex cluster 对混合边图运行分层 Leiden：

衡量你的节省

memex 会在本地 SQLite 数据库（~/.config/memex/telemetry.db）中跟踪 Token 减少指标和人工审核操作。

你可以随时使用 CLI 查询节省情况：

memex stats

也可以查看原始 JSON 负载：

memex stats --json

也可以指定特定的代码仓库范围：

memex stats --repo /path/to/repo

这会返回以下内容的汇总：

• 周期摘要：today、last 7 days、last 30 days 和 lifetime 的调用次数、返回的 Token 数、朴素 Token 数（所请求文件的大小）、节省的 Token 数以及 Token 减少百分比。
• 热门工具：按节省的 Token 总数排序的最有价值工具。
• Agent 客户端：活跃的 Agent（Claude Code、Gemini CLI、Cursor、Codex）及其 Token 节省分布。
• 验证健康度：已验证、未验证和相互印证的节点总数，以及距离上次审核经过的天数。

同样的统计信息也可通过 HTTP MCP 传输方式获取：

GET /stats?repo=/path/to/repo
Authorization: Bearer <your-key>

连接你的 Agent

{
  "mcpServers": {
    "memex": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

{
  "mcpServers": {
    "memex": {
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

{
  "mcpServers": {
    "memex": {
      "command": "npx",
      "args": ["-y", "stifler-memex-mcp", "serve", "--repo", "."]
    }
  }
}

[mcp_servers.memex]
command = "npx"
args = ["-y", "stifler-memex-mcp", "serve", "--repo", "."]

memex memory-tool serve --repo .                     # in-process
memex memory-tool serve --repo . --transport http    # FastAPI on :7464

from memex.memory_tool import MemexAsyncMemoryTool
memory_tool = MemexAsyncMemoryTool(repo_root=".")
client.beta.messages.run_tools(..., tools=[memory_tool])

运作原则

何时使用 memex

项目结构

memex/
├── memex/
│   ├── extractor/        tree-sitter + lockfile parsers
│   ├── graph/            Neo4j writes, confidence, archive, cluster engine
│   ├── synthesizer/      Gemini Flash → Decision nodes
│   ├── mcp_server/       14 MCP tools (read + write + analytic)
│   ├── memory_tool/      Anthropic memory_20250818 adapter
│   ├── watcher/          daemon + git hooks
│   └── cli.py            init / watch / serve / review / graph / cluster
├── tests/                unit, integration, and objective evaluation suites
├── docker/               Neo4j compose
├── npm/                  npx wrapper (publishes as stifler-memex-mcp)
└── Dockerfile            introspection-only image for MCP directory sandboxes

命令

许可证

MIT。请参阅 LICENSE。

作者

Hill Patel (@STiFLeR7)

核心贡献者与维护者

• Hill Patel (@STiFLeR7)，架构师与维护者
• Nirvaan Lagishetty (@Nirvaan05)，主要贡献者与维护者

贡献

请提交 issue 或 PR。uv sync --all-extras 会安装开发工具链。 在提交 PR 前，运行 uv run pytest -m "not integration" 执行离线测试套件，并运行 uv run ruff check .。版本升级时，必须同时更新 pyproject.toml、 npm/package.json、server.json 和团队 Docker 镜像标签。

发布历史见 CHANGELOG.md。v1 设计与评估记录位于 docs/v1/，v0.9 架构位于 docs/architecture/v0.9/。

Vannevar Bush，1945 年：“设想一种供个人使用的未来设备，它有点像机械化的私人档案和图书馆。它需要一个名字；随便造一个，叫 memex 就行。”