codemem

codemem

你的编码 Agent 总在重建已有的东西。codemem 会记住它们构建过的内容，跨越每个项目和每台机器，并根据它们是否有效的证据为每一项评分。

它是一个供 Claude Code 和其他 MCP 客户端使用的 MCP 服务。它知道有哪些项目、项目位于何处、其中包含哪些可复用内容、每个会话做了什么和作出了哪些决定、推送到 git 托管平台的每次提交，以及如何完成重复性工作。你可以从任何机器、Agent 或 Web UI 中搜索所有内容。它会在工作进行期间记录，而不是事后补录。

一个 Python 进程、SQLite，无需外部服务。

与众不同之处

清单脚本会为目录拍摄快照，你只会读一次报告。注册表会列出人们发布的内容。codemem 两者都不做。

• 信任来自证据，而非星标。 每个项目和资源都会根据最近的变更时间、投入的工作量、是否实际部署并运行、是否有其他内容导入它，以及是否有人为它背书来计算评分。verify 会记录“我今天运行过，它能正常工作”，并重置新鲜度计时。每次同步都会重新计算评分，因此当你不再使用某项内容时，它的评分会随时间下降。
• 找出你忘记的副本。 它会扫描每个仓库的 HEAD，查找脚本、模块、服务单元、Dockerfile 和 MCP 服务，为它们的函数计算哈希，并关联共享代码的仓库。它会告诉你，你在三个地方写了相同的重试封装器。
• Agent 会自动为它提供信息。 会话钩子会记录每个 Claude Code 会话做了什么，并向下一个会话提供刚打开项目的简介。目录会自动构建。
• 成熟度是一个一等标签。 authoritative、usable、experimental、antiquated、sunset、broken、junk，每个标签都附有原因。搜索会据此排序，你也可以排除不应作为构建基础的评级。
• 你的代码仍留在原处。 codemem 存储元数据：名称、描述、导入项、符号、函数哈希和提交记录。它不会在任何地方复制你的源代码。

端点

端点	说明
http://<host>:8055/mcp	面向 Claude Code 和其他 MCP 客户端的 MCP（可流式传输的 HTTP）
http://<host>:8055/	Web UI：搜索、项目、资源、笔记、活动、文档。深色模式。
http://<host>:8055/api/…	UI 使用的 JSON API（参见 docs/architecture.md）
http://<host>:8055/health	存活状态

通常运行在 git 托管平台所在的机器上，也就是存放裸仓库的机器上，这样它就能直接读取这些仓库。

安全：codemem 没有身份验证。 它面向受信任的网络构建，任何能够访问该端口的人都可以读取和写入所有内容。请勿在前面没有身份验证代理的情况下将其暴露到互联网。参见 docs/architecture.md。

要求

Python 3.11 或更高版本，以及 git。可选：用于提交动态的 git 托管平台及其裸仓库、用于描述和网页链接的 Gitea，以及用于语义搜索、生成描述草稿和审核流程的 Ollama。没有这些可选组件也能正常工作；搜索会退回到仅使用 BM25。

原因

一位开发者在多台机器上有许多项目文件夹，新启动的 Claude Code 会话无法知道某处已经有重试封装器、Gradio 辅助工具、GPU 监视器或数据流水线。因此它们会被重新构建。快照清单脚本（运行、阅读、遗忘）解决不了这个问题。codemem 是一个实时、可写入的层：它会在工作进行期间记录，而不是事后补录。

内容就是现有的内容。codemem 不会筛选或评判。每个项目都有一个 audience：unrestricted（默认值）、professional 或 employer，因此搜索或视图可以根据上下文排除其中一类。除非有人提出要求，否则不会隐藏任何内容，但有一个例外：克隆的第三方仓库会标记为 origin = vendor，在你主动查找之前，不会出现在搜索结果和列表中。参见 docs/USER_GUIDE.md。

从 PyPI 安装

包名为 codemem-mcp；安装后提供的命令是 codemem。

pip install codemem-mcp          # 或：uv tool install codemem-mcp / pipx install codemem-mcp
codemem serve                    # MCP 位于 http://localhost:8055/mcp，Web UI 位于 http://localhost:8055/

uvx codemem-mcp serve            # 或者无需安装即可运行

除非 CODEMEM_DB 或 CODEMEM_DATA 另有指定，否则数据会存放在 ~/.codemem/。通过以下命令在 Claude Code 中注册：

claude mcp add --transport http --scope user codemem http://localhost:8055/mcp

这仅运行服务本身。如需 systemd 单元、提交动态和会话钩子，请从克隆的代码仓库按照下方的 快速入门操作。

使用 Docker 运行

docker build -t codemem .
docker run --rm -p 127.0.0.1:8055:8055 codemem                        # 临时数据库
docker run -d -p 127.0.0.1:8055:8055 -v codemem-data:/data codemem    # 将数据保留在卷中

**没有身份验证。**任何能够访问该端口的人都可以读取和写入所有内容。请在 -p 中保留 127.0.0.1:：单独使用 -p 8055:8055 会将端口发布到所有网络接口，而且 Docker 的 端口规则会绕过大多数主机防火墙。

此映像不需要任何可选组件：嵌入功能已关闭（CODEMEM_EMBED=0），也没有 git 主机。传入 -e OLLAMA_URL=... -e CODEMEM_EMBED=1 即可开启语义搜索。

快速入门

服务端（在 git 主机上执行一次）：

./install.sh                # venv、用户范围的 systemd 单元、初始化数据、回填、gitea、扫描、嵌入

客户端（每台机器执行一次）：

CODEMEM_URL=http://<host>:8055 client/install-client.sh    # Linux/macOS：MCP 服务 + SessionStart/SessionEnd 钩子
client\install-client.ps1                                   # Windows PowerShell（先设置 $env:CODEMEM_URL）

之后，在任何 Claude Code 会话中都可以使用 codemem 工具；每个会话开始时都会显示当前项目的 简报（如果 codemem 了解该项目），结束时则会自动记录会话。

Claude 可以看到什么

工具	用途
search	对所有内容进行 BM25 + 嵌入混合搜索。构建任何内容前先调用
project_brief	按名称或工作目录查看某个项目的所有信息
list_projects	按状态、标签、机器、受众、可见性筛选
update_project	更新描述、用途、状态、标签、受众、来源（自有/供应商）、可见性、成熟度
register_asset	记录可复用的脚本/模块/提示词/技能/服务，并附上一行用法说明
find_assets	按类型/标签/项目搜索或列出资源，也可按导入的库搜索
log_session	记录已完成、已决定、已使用、已放弃的内容，以及下一步计划
add_note	添加决策、操作指南、资源、问题、想法
delete_note	删除误写的笔记及其索引和嵌入记录
link_items	标记项目使用/可复用/取代/衍生自其他项目
rate	成熟度：权威、可用、实验性、过时、已停用、损坏、无用，并说明原因
verify	“我今天运行过，运行正常”：重置计算所得信任分数的新鲜度计时
handoff / list_handoffs	跟踪一种实现替代另一种实现的过程，包括候选、影子、已验证、已推广阶段
howto	查看如何发布、添加机器、使用 codemem，以及已导入的任何文档
activity	查看所有机器上的提交和会话，时间范围为最近 N 天
add_scan_root / scan_path	注册要扫描的目录；立即扫描（在服务端机器上）
stats	查看数量、机器、索引覆盖情况
help	工作流、工具列表、标签词汇表。在 Claude Code 中也可使用 /codemem；/codemem <query> 可进行搜索

数据来源

• Git 主机：GIT_ROOT 中的每个裸仓库都会补录历史数据；post-receive 钩子会将每次推送发送到 /ingest/push，因此新提交会在几秒内显示。参见 docs/git-commit-feed.md。
• Gitea（可选）：通过其 API 和只读令牌获取描述、主题和 Web URL。
• 本地扫描：扫描每台机器上已注册根目录下的项目目录。在服务器上会自动运行；其他机器在注册根目录后运行一次 client/codemem_agent.py。
• 发现：在 HEAD 版本中挖掘每个自有仓库，查找脚本、模块、单元、Dockerfile、提示词和 MCP 服务，并将其记录为 auto-discovered 资产，同时建立仓库之间的共享代码链接。
• 文档：从 CODEMEM_DOC_SOURCES 获取 Markdown（默认为此仓库），每次同步时重新计算哈希。
• Claude Code：来自钩子的会话记录，以及 Claude 使用工具写入的内容。
• 本地模型（可选，通过 Ollama）：用于语义搜索的嵌入、草拟描述，以及对近似重复函数和描述过于简略的代码进行有针对性的审查。

目录结构

codemem/        服务端软件包
  config.py     所有可调参数均可通过环境变量覆盖
  db.py         模式、连接、单个 FTS5 索引
  store.py      所有写入操作（确保索引同步更新）
  search.py     BM25 + Ollama 嵌入、倒数排名融合
  gitsync.py    裸仓库历史补录、推送接收、push.log、Gitea
  scan.py       项目发现 + 位置记录
  discover*.py  资产发现、共享代码链接（核心代码与远程 Agent 共用）
  trust.py      计算信任分数
  review.py     有针对性的模型审查
  describe.py   模型草拟的项目描述
  knowledge.py  文档导入、操作指南/资产种子数据
  server.py     MCP 工具、HTTP 路由、JSON API
  cli.py        serve | backfill | gitea | docs | seed | scan | embed | reindex | backup | sync | discover | review | trust | describe | purge
  web/          单文件 Web 界面（+ 随附的 marked.js）
client/         钩子、远程扫描 Agent、斜杠命令、各操作系统安装程序
systemd/        用户级单元：服务、同步定时器（6h）、备份定时器（02:45）
docs/           用户指南、架构、git-commit-feed、客户端、运维、发布、python-vs-typescript
server.json     MCP Registry 条目（PyPI 软件包 codemem-mcp）
glama.json      Glama 列表维护者
Dockerfile      容器镜像：临时 /data，无可选服务

存储：$CODEMEM_DB（默认 ~/.codemem/codemem.db，SQLite，WAL）。备份：$CODEMEM_BACKUP_DIR （默认 ~/.codemem/backups/）。

状态与贡献

本项目从一个系统中提取而来，该系统一直每天处理三台机器上的 165 个项目、735 个资产和 2,000 多次提交。它在这些场景下运行稳定，但一直只有一位操作者，因此当你的目录布局与其不同时，可能会遇到各种问题。欢迎提交问题和拉取请求；进行较大改动前，请先创建问题，以便我们就方案达成一致。如何在本地运行，以及两条不可妥协的规则，请参见 CONTRIBUTING.md；关于存储内容和漏洞报告方式，请参见 SECURITY.md。

推送前运行 scripts/smoke.sh：该脚本会使用临时数据库启动服务，并检查健康状态、Web 界面、JSON API 和模式是否正常加载。

许可证

Apache License 2.0。参见 LICENSE。

版权所有 © 2026 Jeff Angelcyk。