项目定位与核心能力

memex 是一个面向 AI Agent 的本地化长期记忆系统（Long-term Memory System），通过 Model Context Protocol（MCP）以本地 stdio 服务器的形式暴露给宿主 Agent。其核心职责是把 Agent 在会话中产生的"高价值信号"——包括决策依据、用户偏好、未完成项、复盘结论等——经过提炼（distill）后持久化到本地 Markdown / JSONL 仓库，并在后续会话中按相关性进行检索与回注。

资料来源：README.md:1-30

系统的关键能力可归纳为三类：

• 上下文成本遥测（Context Cost Telemetry）：每次检索/回注都会统计 token 消耗并暴露给宿主，避免记忆系统反噬主上下文窗口。资料来源：README.md:60-80
• 声明式协议暴露：通过 server.json 注册 MCP 工具清单，宿主（如 Claude Desktop、Cursor）可零代码接入。资料来源：server.json:1-40

运行时架构

flowchart LR
    Host[Agent Host<br/>Claude / Cursor] -->|stdio / JSON-RPC| CLI[memex CLI<br/>memex/__main__.py]
    CLI --> Server[Memory Server Core<br/>memex/cli.py]
    Server --> Distill[Distill Pipeline]
    Server --> Store[(Local Store<br/>Markdown / JSONL)]
    Distill --> Server
    Server -->|tool results| Host

进程入口由 memex/__main__.py 承担：模块被作为脚本运行时调用 cli.app()，避免在导入阶段触发任何 I/O，便于在测试与嵌入式场景中复用。资料来源：memex/__main__.py:1-20

实际的命令解析、参数校验、MCP 握手与工具路由集中在 memex/cli.py 中，CLI 既是用户面向的入口，也是 MCP 服务器的进程边界。资料来源：memex/cli.py:1-40

版本与生命周期

资料来源：README.md:15-30、server.json:5-25]()、npm/package.json:3-10]()

server.json 中声明的 version 字段是宿主识别能力兼容性的唯一权威来源；pyproject.toml 与 npm/package.json 中的版本号需与之保持一致，否则在多端分发时会出现"协议声明的版本"与"实际安装的版本"错位的问题。资料来源：server.json:10-30、pyproject.toml:5-15、npm/package.json:3-10

安装、启动与终止

安装路径

项目同时维护两条分发通道：

• Python 通道：pyproject.toml 定义项目元数据、打包配置与可选依赖；通过 pip install 或 uv tool install 取得 memex 可执行入口。资料来源：pyproject.toml:1-40
• Node 通道：npm/package.json 提供薄封装（thin wrapper），方便在 JS 生态（Claude Desktop 等）中直接 npx 调用，避免宿主必须预装 Python 运行时。资料来源：npm/package.json:1-30

启动时序

1. 宿主读取 MCP 配置，定位到 memex 可执行文件。
2. 进程启动后，memex/__main__.py 立即接管 stdio，进入 MCP 握手。资料来源：memex/__main__.py:10-25
3. memex/cli.py 完成工具注册，监听 JSON-RPC 请求。资料来源：memex/cli.py:20-50
4. 首个请求到来时延迟加载向量检索、蒸馏流水线等重型模块，降低冷启动延迟。

终止

由于采用 stdio + JSON-RPC，进程生命周期与宿主会话绑定：宿主断开 stdin，CLI 收到 EOF 后执行清理（关闭文件句柄、flush 待写入的草稿缓冲），随即正常退出，不会留下孤立进程。资料来源：memex/cli.py:30-60

关键设计约束

• 本地优先：所有记忆存储在用户本地文件系统，不向任何远端上报；这是 v0.4.0 引入"写入纪律"的根本动机。资料来源：README.md:20-50
• 协议中立：业务逻辑不耦合 MCP，可被其他 Agent 框架直接 import 调用。资料来源：memex/cli.py:1-30
• 版本强一致：server.json / pyproject.toml / npm/package.json 三处版本号必须同步更新，否则 MCP 客户端会拒绝加载工具清单。资料来源：server.json:5-30、pyproject.toml:5-20、npm/package.json:3-15

概述

memex 是一个面向代码仓库的"外置记忆"系统，核心目标是把分散在源代码、依赖清单、提交记录与开发者注释中的结构化信息抽取出来，统一写入图数据库（Graph Database），从而为大语言模型（LLM）与开发者提供低成本、可追溯的上下文。当前最新发布版本为 v0.5.1；v0.4.0 起引入了 Context Cost Telemetry 与 Confidence-Weighted Write Discipline 两项关键能力（v0.4.0 Release Notes），用以约束上下文开销并抑制低质量写入。

系统在源码组织上呈现清晰的三层职责：

• 抽取层（Extractor）：把仓库原始文件解析为标准化事实
• 合成层（Synthesizer）：对事实进行归一化、合并与摘要
• 持久层（Graph）：以图结构持久化事实，并对上层提供查询

每一层通过显式数据契约解耦，可独立替换与测试。

三层架构

抽取层：Extraction

抽取层负责读取并解析仓库原始文件，向合成层输出统一 Schema 的中间事实。

• treesitter.py：基于 Tree-sitter 的增量解析器，把源码解析为 AST，提取函数、类、模块及导入关系等结构化符号。资料来源：memex/extractor/treesitter.py:1-120
• lockfile.py：解析多种语言生态的锁文件（如 package-lock.json、poetry.lock、Cargo.lock 等），抽取直接依赖与传递依赖的版本关系。资料来源：memex/extractor/lockfile.py:1-80
• todo_scanner.py：扫描 TODO、FIXME、XXX 等开发者注释，抽取未完成意图作为软信号。资料来源：memex/extractor/todo_scanner.py:1-60

抽取层各模块不直接写入图数据库，仅产出"待合成"的事实集合。

合成层：Synthesis

合成层对抽取得到的原始事实做归一化、去重与语义摘要，是 v0.4.0 Confidence-Weighted Write Discipline 的主要落地点。

• commit.py：把代码变更与提交信息对齐，产出"提交级"语义摘要，作为写入图数据库的最小事实单元；每条事实附带置信度分数。资料来源：memex/synthesizer/commit.py:1-100

低于置信度阈值的事实将被丢弃或降级为"软提示"，避免噪声长期污染图谱。

持久层：Graph

持久层封装图数据库的连接、写入与查询语义。

• writer.py：负责节点与边的创建、更新与合并，强制基于内容哈希的幂等写入，避免重复节点。资料来源：memex/graph/writer.py:1-150
• client.py：封装底层图数据库驱动的连接管理与查询构造，向 LLM / 开发者提供统一 API，并在每次访问时记录 Context Cost Telemetry（token 等价成本）。资料来源：memex/graph/client.py:1-120

端到端数据流

下图展示了从仓库文件到图谱消费的完整数据通路：

flowchart LR
    A[源码仓库] --> B[抽取层 Extractor]
    B --> B1[tree-sitter AST]
    B --> B2[锁文件依赖]
    B --> B3[TODO / FIXME]
    B1 --> C[合成层 Synthesizer]
    B2 --> C
    B3 --> C
    C --> D{置信度阈值}
    D -->|通过| E[Graph Writer]
    D -->|不通过| F[丢弃 / 降级]
    E --> G[(Graph Database)]
    G --> H[Context Cost Telemetry]
    H --> I[LLM / 开发者消费]

三个关键控制点决定了系统的稳定性与经济性：

1. 置信度门禁：低置信度事实不会进入持久层，从源头控制噪声。资料来源：memex/synthesizer/commit.py:40-80
2. 幂等写入：相同内容哈希的事实不会产生重复节点，保证图谱整洁。资料来源：memex/graph/writer.py:30-60
3. 成本遥测：每次图谱读取都附带 token 估算，调用方可据此按预算裁剪上下文。资料来源：memex/graph/client.py:40-80

版本演进与社区关注点

社区反馈集中于两类痛点：图谱膨胀带来的 上下文成本失控，以及抽取噪声导致的 长期记忆污染。v0.4.0 的两项特性正是为回应这些诉求而设计：

• Context Cost Telemetry：把"读图"的代价量化成 token，使 LLM 调用方可以按预算主动裁剪；
• Confidence-Weighted Write Discipline：把"写图"的入口交给置信度门禁，防止低质量抽取污染长期记忆。

最新 v0.5.1 在此基线上进一步增强了抽取器的多语言覆盖，并补齐了图谱查询层的轻量缓存策略（v0.5.1 Release）。对希望深入接入或扩展 memex 的开发者而言，理解这三层契约与两个控制点，是把握整个系统行为的关键。

1. 模块划分与职责

memex/mcp_server/ 子包按照"入口 + 能力分文件"的模式组织：

• server.py：MCP 服务器装配点，负责 stdio 传输初始化与工具注册 资料来源：memex/mcp_server/server.py:1-120
• tools_read.py：只读检索类工具，返回符号、文件或上下文片段 资料来源：memex/mcp_server/tools_read.py:1-160
• tools_write.py：写入类工具，受 v0.4.0 引入的置信度加权写纪律约束 资料来源：memex/mcp_server/tools_write.py:1-160
• tools_explain.py：解释类工具，把内部结构翻译为人类可读说明 资料来源：memex/mcp_server/tools_explain.py:1-160
• tools_impact.py：影响分析工具，评估改动对调用方的连锁影响 资料来源：memex/mcp_server/tools_impact.py:1-160
• queries.py：集中存放图查询语句，被多个工具复用 资料来源：memex/mcp_server/queries.py:1-160

这种切分让读路径与写路径解耦，便于在不影响只读工具的前提下，对写入工具单独引入策略约束（如置信度门控与上下文开销遥测）。

2. 工具分类一览

queries.py 作为查询共享层，使各工具不必各自硬编码图查询语句，从而减少重复实现并便于统一优化。

3. 智能体调用流程

flowchart LR
    A[外部智能体] -->|MCP 请求| S[server.py]
    S --> R[tools_read.py]
    S --> E[tools_explain.py]
    S --> I[tools_impact.py]
    S --> W[tools_write.py]
    R --> Q[queries.py]
    E --> Q
    I --> Q
    W --> Q
    Q --> B[(代码图/索引后端)]
    W -->|置信度门控| G{是否通过}
    G -->|通过| Commit[落库]
    G -->|未通过| Reject[拒绝并返回原因]

智能体通常先调用只读工具建立上下文，再借助解释与影响工具评估风险，最后才调用写入工具。tools_write.py 在 v0.4.0 起引入"Confidence-Weighted Write Discipline"，要求只有当置信度满足阈值时才执行实际写入，否则向智能体返回拒绝原因。

4. 与版本演进的关联

v0.4.0 的两条主线特性——"Context Cost Telemetry"与"Confidence-Weighted Write Discipline"——都在 MCP 工具层落地：前者通过读取工具返回上下文开销元数据，后者由写入工具内部强制执行。当前最新版本 v0.5.1 在该基础上继续打磨智能体集成边界，使工具行为对调用方更可预测。

模块组成与职责

知识图谱相关代码按职责划分为若干子模块：

• schema.py：定义图谱节点、关系与属性类型，是整个图层的"契约"文件。
• confidence.py：维护每条知识条目的置信度分数，并提供写入时的校验逻辑。
• decay.py：实现置信度随时间衰减的计算函数，决定何时需要刷新或回收。
• archive.py：处理低置信度节点的归档与回收。
• cluster.py 与 cluster_runner.py：负责对节点进行语义聚类，压缩图规模。

资料来源：memex/graph/schema.py:1-80 memex/graph/confidence.py:1-60

数据模型与 Schema

schema.py 定义了知识图谱中通用的节点与关系形态，使上层写入与查询逻辑可以依赖稳定的结构体而非散落的字符串。下表概括了主要实体：

通过将 Confidence 作为一等字段嵌入节点与边，图谱天然具备"自描述可信度"的特性，避免在外部维护另一套评分表。

资料来源：memex/graph/schema.py:20-120

置信度与写入纪律

confidence.py 实现了"置信度加权写入纪律"（Confidence-Weighted Write Discipline），这是 v0.4.0 版本中重点引入的能力。新写入或更新节点时，系统不会直接覆盖已有记录，而是结合：

1. 现有节点的置信度分数；
2. 新证据的来源类型；
3. 上一次更新时间与当前时间差。

综合决定是否合并、覆盖或忽略。这有效避免了低质量信号反复覆写高质量记忆的情况。

资料来源：memex/graph/confidence.py:40-110

时间衰减与归档

decay.py 提供了置信度衰减函数，典型形式为基于时间差的指数或线性衰减：

$$ score_t = score_0 \cdot f(t - t_0) $$

其中 f 由 decay.py 实现，并暴露参数化的衰减速率，使管理员能够根据业务调整"记忆半衰期"。当分数跌破阈值时，archive.py 将节点从主图中迁移至归档存储，主查询路径不再检索这些节点，但保留可恢复性，便于人工审计或回溯。

资料来源：memex/graph/decay.py:1-90 memex/graph/archive.py:1-70

聚类压缩与执行器

随着节点数量增长，图规模可能成为检索瓶颈。cluster.py 定义了聚类算法（如基于语义嵌入相似度），而 cluster_runner.py 提供调度与执行入口，可在后台或上下文组装前调用，将相似节点归并为簇，从而在写入与查询两端降低上下文成本。这一能力与 v0.4.0 中提到的"Context Cost Telemetry"形成闭环：聚类减少 token 消耗，遥测模块衡量其收益。

资料来源：memex/graph/cluster.py:1-100 memex/graph/cluster_runner.py:1-80

遥测与社区反馈

v0.4.0 的发布说明指出，该版本聚焦于"Context Cost Telemetry（上下文成本遥测）"与"Confidence-Weighted Write Discipline"。前者将每次上下文组装过程中涉及的节点数、置信度分布与 token 成本记录下来，作为评估图谱健康度的依据；后者则依赖本页描述的 confidence.py 与 decay.py 协同工作。社区中关于长期记忆质量与上下文膨胀的讨论通常聚焦于这两条主线。

资料来源：memex/graph/confidence.py:1-30 memex/graph/decay.py:1-30

小结

知识图谱模块通过 Schema 约束、置信度评分、时间衰减、归档回收与聚类压缩五层机制，构成一个自维护的记忆系统。该系统并非简单追加写入，而是持续评估每条知识的可信度与边际成本，使 memex 能够在长期运行中保持图谱的精简与可解释。理解这一闭环，对于后续扩展自定义节点类型或调整衰减策略至关重要。

Pitfall Log / 踩坑日志

项目：STiFLeR7/memex

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/STiFLeR7/memex | host_targets=mcp_host, claude_code, claude, cursor, gemini_cli

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/STiFLeR7/memex | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/STiFLeR7/memex | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/STiFLeR7/memex | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/STiFLeR7/memex | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/STiFLeR7/memex | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/STiFLeR7/memex | release_recency=unknown