内容
<div align="center">
<p align="center">
<img src="assets/banner.png" alt="ctxmem banner" width="100%">
</p>
# ctxmem
**Git 原生、可共享的项目记忆，适用于 AI 编程代理 — 完全本地，无需云服务。**
[](LICENSE)
[](https://www.python.org/)
[](pyproject.toml)
[](https://modelcontextprotocol.io)
[](#)
</div>
---
`ctxmem` 为您的项目提供一个永久、可搜索的记忆，存储在 **代码仓库内**。AI 代理（和您）可以存储决策并按需回忆相关上下文，这样当聊天超过模型的上下文窗口时，什么都不会被遗忘。
- 🧠 **记住** — 决策、笔记、会话 + 您的代码，存储在可搜索的索引中。
- 🤝 **可共享** — 记忆是一个文本文件，提交到 git。您提交，您的同事拉取，他们拥有 *您确切的上下文*。免费的分支感知。
- 📦 **作为 git 包工作** — `pip install git+https://…`，零依赖项。
- 🔒 **完全本地** — 存储库中的 SQLite 文件。无需云服务，无需 API 密钥，无需服务器。
- 🔍 **搜索模式** — `keyword`（内置）+ `semantic` / `hybrid`（🧪 **测试版**，本地嵌入）。
---
## 📑 目录
- [ctxmem](#ctxmem)
- [📑 目录](#-目录)
- [🎯 1. 它解决的问题](#-1-它解决的问题)
- [💡 2. 核心思想](#-2-核心思想)
- [🔄 3. 工作原理（数据流）](#-3-工作原理数据流)
- [🗂️ 4. 项目结构](#️-4-项目结构)
- [模块的通俗解释](#模块的通俗解释)
- [📥 5. 安装](#-5-安装)
- [开发检查](#开发检查)
- [🚀 6. 快速开始（5 分钟）](#-6-快速开始5-分钟)
- [🧭 7. 完整演练（安装、代理、协作）](#-7-完整演练安装代理协作)
- [步骤 1 — 将 ctxmem 添加到您的代码库（一次）](#步骤-1--将-ctxmem-添加到您的代码库一次)
- [步骤 2 — 种子一些决策（您，每行一个）](#步骤-2--种子一些决策您每行一个)
- [步骤 3 — 提交记忆以便共享](#步骤-3--提交记忆以便共享)
- [步骤 4 — 让 AI 代理自动记住（可选但强大）](#步骤-4--让-ai-代理自动记住可选但强大)
- [步骤 5 — 您的同事获得完全相同的上下文](#步骤-5--您的同事获得完全相同的上下文)
- [回顾：手动 vs 自动](#回顾手动-vs-自动)
- [📖 8. 命令参考](#-8-命令参考)
- [衡量令牌节省（`bench`）](#衡量令牌节省bench)
- [📊 9. 基准测试 — 如何测试](#-9-基准测试--如何测试)
- [🔍 10. 搜索模式：keyword vs semantic vs hybrid](#-10-搜索模式-keyword-vs-semantic-vs-hybrid)
- [🤝 11. 与团队共享](#-11-与团队共享)
- [🪝 12. 使用 git 钩子自动同步](#-12-使用-git-钩子自动同步)
- [🤖 13. 从 AI 代理使用](#-13-从-ai-代理使用)
- [选项 A — 指令 + CLI（推荐，无需 MCP）](#选项-a--指令-cli推荐无需-mcp)
- [选项 B — MCP 服务器](#选项-b--mcp-服务器)
- [🧪 14. 使用 Ollama 的语义后端（测试版）](#-14-使用-ollama-的语义后端测试版)
- [选项 A — 在主机上安装 Ollama](#选项-a--在主机上安装-ollama)
- [选项 B — 在隔离的 Lima VM 中运行 Ollama](#选项-b--在隔离的-lima-vm-中运行-ollama)
- [❓ 15. 常见问题](#-15-常见问题)
- [🤝 16. 贡献](#-16-贡献)
- [📄 17. 许可证](#-17-许可证)
---
## 🎯 1. 它解决的问题
大型语言模型具有 **有限的上下文窗口**（例如 200K 令牌）。当会话超出此限制时，模型会“忘记”决策、已读取的文件和项目的约定。更糟糕的是，该上下文被困在一个聊天中：它不会 **共享** 给队友，也无法理解分支之间的变化。
解决方法不是使窗口变大。而是 **将记忆保存在模型外部**，并在需要时仅反馈几个相关的部分。
> **原则：** 上下文窗口是缓存，而不是存储。真相存储在外部的可搜索索引中。
## 💡 2. 核心思想
存储库中 `.ctxmem/` 下的两个文件：
```
.ctxmem/
├── memory.jsonl # 真相来源 — 提交到 git。
│ # 追加只读，人类可读，每行一个 JSON 对象。
│ # 存储决策/笔记/会话。
│
└── index.db # 导出的索引 — gitignored，按需重建。
# SQLite全文索引（FTS5）+ 可选向量表。
# 存储 `memory.jsonl` 和代码符号的可搜索副本。
```
为什么这种分割是关键：
- **`memory.jsonl` 是代码库中的文本** → 它版本控制、差异和合并像任何文件一样。切换分支 → 记忆随之改变。推送 → 队友获得它。
- **`index.db` 是可丢弃的** → 任何人都可以从 `memory.jsonl` + 磁盘上的代码重建它。因此，我们从不提交二进制文件；我们提交可读的历史。
## 🔄 3. 工作原理（数据流）
```mermaid
flowchart TD
A[您 / AI 代理] -->|ctxmem remember| B[memory.jsonl<br/>真相来源，git 提交]
C[您的源代码] -->|ctxmem sync| D[索引器：符号树]
B -->|ctxmem sync| E[index.db<br/>SQLite FTS5 + 向量]
D --> E
A -->|ctxmem recall query| F{搜索模式}
F -->|keyword| G[FTS5 全文索引]
F -->|semantic 🧪| H[Ollama 嵌入 + sqlite-vec KNN]
F -->|hybrid 🧪| I[合并两者]
G --> E
H --> E
I --> E
E -->|最佳结果| A
```
- **写入：** `remember` 在 `memory.jsonl` 中追加一行 JSON（并更新索引）。
- **索引：** `sync` 重建 `index.db` = 重放 `memory.jsonl` + 扫描代码中的符号（函数/类）+ 可选计算嵌入。
- **读取：** `recall` 在配置的模式下搜索索引并返回最佳匹配 — 您（或代理）实际需要的少量相关切片。
## 🗂️ 4. 项目结构
```
ctxmem/
├── pyproject.toml # 包元数据，CLI 入口点，可选额外功能。
├── README.md # 本文件。
├── LICENSE # MIT。
├── .gitignore # 忽略本地包维护状态和构建工件。
│
├── src/ctxmem/ # Python 包。
│ ├── __init__.py # 包版本标记。
│ ├── gitinfo.py # 读取当前 git 分支 + 提交（以便记忆被标记为创建它的上下文）。
│ ├── store.py # 存储层：路径，配置，SQLite/FTS5 模式，插入/追加/搜索/读取助手。
│ ├── indexer.py # 扫描源文件并提取代码“符号”（函数/类）到可搜索的块中。
│ ├── embeddings.py # 🧪 测试版：与 Ollama 通信以获取嵌入，并与 sqlite-vec 通信以进行向量 KNN 搜索。
│ ├── retrieval.py # 大脑：重建索引并调度查询到 keyword / semantic / hybrid（带有自动回退）。
│ ├── bench.py # 令牌节省基准 + SVG 图表生成。
│ ├── cli.py # `ctxmem` 命令行（init，remember，recall，...）。
│ └── mcp_server.py # 通过 MCP 协议将 ctxmem 暴露给 AI 代理。
│
├── example/
│ ├── sample_app.py # 一个小模块，以便有真正的代码可索引/回忆。
│ └── bench/ # 示例生成的基准测试报告 + 图表。
│
├── ollama/ # 🧪 测试版：在隔离的 VM 中运行语义后端。
│ ├── lima.yaml # Lima VM：Ubuntu + Ollama + 嵌入模型。
│ └── Taskfile.yaml # `task start/stop/status/demo` 助手用于 VM。
│
└── .ctxmem/ # 由 `ctxmem init` 在您使用的任何代码库中创建。
├── memory.jsonl # 提交的真相来源。
├── config.json # 已提交：使用哪种搜索模式 + 模型。
├── .gitignore # 将 index.db 排除在 git 之外。
└── index.db # 导出的本地搜索索引。
```
> 注意：此 `ctxmem` 包存储库是一个例外：其自己的 `.ctxmem/` 是维护者本地的，并被 gitignored。在使用 `ctxmem` 的项目中，提交 `.ctxmem/memory.jsonl` 和 `.ctxmem/config.json`；仅忽略 `.ctxmem/index.db`。
### 模块的通俗解释
| 文件 | 责任 | 关键功能 |
|------|----------------|---------------|
| `gitinfo.py` | 知道我们处于哪个分支/提交。 | `branch()`，`commit()` |
| `store.py` | 读取/写入文件 + SQLite。定义 FTS5 表。 | `memory_paths`，`load_config`，`init_schema`，`insert_row`，`append_jsonl`，`search` |
| `indexer.py` | 将代码文件转换为可搜索的符号块。 | `extract_symbols`，`index_code` |
| `embeddings.py` 🧪 | 测试版：本地嵌入（Ollama）+ 向量 KNN（sqlite-vec）。 | `available`，`embed`，`build`，`search` |
| `retrieval.py` | 重建索引；选择 keyword/semantic/hybrid；回退。 | `rebuild`，`get_conn`，`search` |
| `bench.py` | 衡量令牌/请求节省；渲染 SVG 图表。 | `count_tokens`，`baseline_text`，`svg_grouped_bars` |
| `cli.py` | 面向用户的命令。 | 每个子命令一个 `cmd_*` |
| `mcp_server.py` | 面向代理的工具，基于 MCP。 | `recall`，`remember`，`memory_status` |
`cli.py` 和 `mcp_server.py` 都很薄：它们调用 `retrieval.py`，而 `retrieval.py` 调用 `store.py`、`indexer.py` 和（可选）`embeddings.py`。一个大脑，两个前端。
## 📥 5. 安装
```bash
# 从克隆
pip install -e .
# 作为 git 包（这是“作为 git 包工作”的部分）
pip install "git+https://github.com/DoppiaG93/ctxmem.git"
# 带有可选额外功能的
pip install "ctxmem[mcp]" # AI 代理服务器（MCP）
pip install "ctxmem[semantic]" # 🧪 测试版语义搜索（sqlite-vec；还需要 Ollama）
pip install "ctxmem[all]" # 所有功能
```
需要 **Python 3.8+**，并带有 FTS5（几乎所有 `sqlite3` 构建版本都包含）。基本安装 **零第三方依赖**。
### 开发检查
对于本地开发，安装开发额外功能并运行 GitHub Actions 使用的相同检查：
```bash
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
python -m pytest
python -m pylint src/ctxmem tests
ctxmem --help
```
`python -m pytest` 运行自动化测试套件。`python -m pylint src/ctxmem tests` 在本地验证 lint 工作流。在 GitHub 上，`.github/workflows/test.yml` 和 `.github/workflows/lint.yml` 中的工作流在每次推送和拉取请求时自动运行。
## 🚀 6. 快速开始（5 分钟）
```bash
cd your-project
ctxmem init # 创建 .ctxmem/
ctxmem remember --type decision \
--title "Auth via JWT" --tags auth,security \
"We chose stateless JWT over server sessions for horizontal scaling."
ctxmem sync # 还索引您的代码
ctxmem recall "how do we handle authentication" # 用自然语言提问
ctxmem recall "cart" --type symbol # 仅搜索代码符号
ctxmem log # 最近的记忆
ctxmem status # 已索引的内容
```
然后提交记忆以便共享：
```bash
git add .ctxmem/memory.jsonl .ctxmem/config.json
git commit -m "chore: seed project memory"
```
## 🧭 7. 完整演练（安装、代理、协作）
一个完整的现实故事：**您有自己的包/代码库，您添加 ctxmem，AI 代理开始记住，您将记忆交给同事。**
首先，提出关键问题：
> **我是否手动输入命令，还是自动执行？**
> 两者都有 — 有三个级别，您可以选择自动化程度：
>
> | 什么 | 谁执行 | 如何 |
> |------|-------------|-----|
> | 索引 **代码** | 自动 | git 钩子在每次提交时运行 `ctxmem sync` |
> | 记录 **决策** | 您 *或* 代理 | 您运行 `ctxmem remember`，**或** AI 调用 `remember` MCP 工具为您 |
> | **回忆** 上下文 | 您 *或* 代理 | 您运行 `ctxmem recall`，**或** AI 调用 `recall` MCP 工具 |
>
> 代码索引自行维护。决策由您（一条命令）或代理自动写入，一旦您配置指令文件和（可选）MCP 工具（步骤 4 以下）。
### 步骤 1 — 将 ctxmem 添加到您的代码库（一次）
```bash
cd ~/code/my-awesome-package # 您现有的代码库
pip install "git+https://github.com/DoppiaG93/ctxmem.git" # 或：pip install -e ../ctxmem
ctxmem init # 创建 .ctxmem/（默认关键字模式）
ctxmem hook install # 自动在每次提交后重建索引
ctxmem sync # 您现有代码的第一次索引
```
发生了什么：
- `.ctxmem/memory.jsonl`（空）+ `.ctxmem/config.json` 被创建。
- 一个 `post-commit` 钩子现在通过自动运行 `ctxmem sync` 来保持代码索引更新。
- 您的代码已经可搜索：试试 `ctxmem recall "database connection"`。
### 步骤 2 — 种子一些决策（您，每行一个）
写下您希望新队友（或新的 AI 会话）知道的事情：
```bash
ctxmem remember --type decision --title "HTTP client" \
"We use httpx (async) everywhere; do not add requests."
ctxmem remember --type decision --title "DB" --tags db \
"Postgres via SQLAlchemy 2.0; migrations with Alembic."
ctxmem remember --type note --title "Gotcha" \
"The worker must run with TZ=UTC or scheduling breaks."
```
检查它们：`ctxmem log`.
### 步骤 3 — 提交记忆以便共享
```bash
git add .ctxmem/memory.jsonl .ctxmem/config.json
git commit -m "chore: seed project memory"
git push
```
只有 **真相来源** (`memory.jsonl`) 和 **配置** 才会被提交。`index.db` 保留本地（被 gitignore），并在需要时重建。
### 步骤 4 — 让 AI 代理自动记住（可选但强大）
到目前为止，您输入了命令。要使 **代理** 自动执行，请为您的工具创建正确的文件：
```bash
ctxmem agent-init --agent codex # writes/updates local AGENTS.md
ctxmem agent-init --agent copilot # writes/updates .github/copilot-instructions.md
ctxmem agent-init --agent all # writes both
ctxmem agent-init --agent all --mcp # also writes .vscode/mcp.json
```
Codex 读取 `AGENTS.md`（通常本地保存并被 gitignored）。GitHub Copilot 读取 `.github/copilot-instructions.md`。生成的部分被包裹在 ctxmem 标记中，因此重新运行 `agent-init` 只会更新该部分。
如果您更喜欢手动配置，请在 `AGENTS.md` 中为 Codex 或 `.github/copilot-instructions.md` 为 Copilot 插入此块：
````markdown
# 项目记忆
此代码库具有 `ctxmem` 记忆。在开始任务之前，在终端中运行 `ctxmem recall` 命令以加载相关的决策和代码：
```bash
ctxmem recall "<任务或问题的简要描述或问题>"
```
当您做出或确认重要决策时，运行 `ctxmem remember` 以便将其保存以供未来会话和队友使用：
```bash
ctxmem remember --type decision --title "简短标题" "详细决策文本"
```
更改代码后，运行 `ctxmem sync` 以重建索引。
```bash
ctxmem sync
```
如果您的代理支持 MCP 协议，而不是运行 shell 命令，它可以调用 MCP 工具 `recall(...)` 和 `remember(...)` 作为替代。
````
对于支持 MCP 的客户端，请安装额外的功能：
```bash
pip install "ctxmem[mcp]"
```
然后注册本地服务器。`agent-init --mcp` 创建此 VS Code 文件：
```json
{
"servers": {
"ctxmem": {
"command": "ctxmem-mcp",
"env": { "CTXMEM_ROOT": "${workspaceFolder}" }
}
}
}
```
现在，在正常聊天中，代理将：
- 在开始时运行 `ctxmem recall` → 它在不粘贴的情况下“记住”过去的决策；
- 在做出决策时运行 `ctxmem remember` → 记忆会自动增长。
您仍然可以随时使用 CLI；代理和您写入同一个记忆。
### 步骤 5 — 您的同事获得完全相同的上下文
```bash
git clone https://github.com/DoppiaG93/my-awesome-package && cd my-awesome-package
pip install "git+https://github.com/DoppiaG93/ctxmem.git" # 或您的正常环境设置
ctxmem hook install # 一次性：git 不会共享钩子，因此每个开发人员都安装它
ctxmem recall "which HTTP client do we use"
# [decision] HTTP client
# We use httpx (async) everywhere; do not add requests.
```
他们从未运行 `remember` — 他们只是拉取了您的 `memory.jsonl`。第一次 `recall` 自动重建了他们的本地 `index.db`。如果他们使用 Codex，他们可以运行 `ctxmem agent-init --agent codex` 来创建他们的本地 `AGENTS.md`；如果存储库包含 `.github/copilot-instructions.md` 或 `.vscode/mcp.json`，这些代理集成会随存储库一起旅行。
> **两次，一次在每个机器上，需要 git 无法为您做的事情：** `pip install` ctxmem 和 `ctxmem hook install`（git 钩子位于 `.git/`，不会被推送）。其他一切都存储在代码库中。
### 回顾：手动 vs 自动
- **自动：** 代码索引（git 钩子）、调用时的索引重建以及 — 一旦设置了 **步骤 4** — 代理回忆和记录决策。
- **手动（可选）：** 使用 `ctxmem remember` 编写决策，以及两个每个机器的设置命令。
## 📖 8. 命令参考
### 衡量令牌节省（`bench`）
## 📊 9. 基准测试 — 如何测试
## 🔍 10. 搜索模式：keyword vs semantic vs hybrid
## 🤝 11. 与团队共享
## 🪝 12. 使用 git 钩子自动同步
## 🤖 13. 从 AI 代理使用
### 选项 A — 指令 + CLI（推荐，无需 MCP）
### 选项 B — MCP 服务器
## 🧪 14. 使用 Ollama 的语义后端（测试版）
### 选项 A — 在主机上安装 Ollama
### 选项 B — 在隔离的 Lima VM 中运行 Ollama
## ❓ 15. 常见问题
## 🤝 16. 贡献
## 📄 17. 许可证
## 📖 8. 命令参考
| 命令 | 功能 |
|---------|--------------|
| `ctxmem init [--mode M]` | 创建 `.ctxmem/` 目录并选择搜索模式。 |
| `ctxmem remember "text" [--type --title --tags --path]` | 存储记忆（写入 `memory.jsonl`）。类型：`note`、`decision`、`session`、`todo`。 |
| `ctxmem recall "query" [--limit --type --mode]` | 搜索记忆 + 代码。 |
| `ctxmem sync` | 从 `memory.jsonl` 和代码重建 `index.db`（如果启用了嵌入）。 |
| `ctxmem mode [M]` | 显示或切换到 `keyword` / `semantic` 🧪 / `hybrid` 🧪 模式。 |
| `ctxmem log [--limit]` | 列出最近的记忆。 |
| `ctxmem status` | 显示分支/提交、模式和索引项计数。 |
| `ctxmem hook install`/`uninstall` | 添加/移除 git 提交后自动同步钩子。 |
| `ctxmem agent-init [--agent copilot\|codex\|all] [--mcp] [--force]` | 配置代理：写入记忆协议到 `.github/copilot-instructions.md` 以适应 Copilot，或写入本地 `AGENTS.md` 以适应 Codex，或两者皆可。如果使用 `--mcp`，还会写入 `.vscode/mcp.json`。 |
| `ctxmem bench "query" [--baseline files\|memory\|repo]` | 衡量 **token 节省** 和 **premium 请求节省**：`recall` 代码片段与提供整个文件/记忆/仓库的比较。添加 `--suite FILE --report DIR` 以生成完整的报告，包含 SVG 图表。 |
| `ctxmem --root PATH …` | 在其他仓库中运行，而不是当前目录。 |
### 衡量 token 节省（`bench`）
`ctxmem bench` 量化了该工具的全部意义：不是将整个文件（或整个仓库）粘贴到模型中，而是注入相关的 `recall` 代码片段。它报告 **两个** 指标 - 您提供给模型的上下文 **tokens**，以及答案所需的 **premium 请求**（代理往返）数量。
```bash
ctxmem bench "how is a marker structured" # 代码片段 vs 引用文件的全文
ctxmem bench "how is a marker structured" --baseline repo # 代码片段 vs 整个代码库
ctxmem bench "versioning" --baseline memory --type note # 代码片段 vs 整个 memory.jsonl
```
```
没有 ctxmem ： 21306 tokens
使用 ctxmem ： 1526 tokens
节省 ： 19780 tokens (92.8%)
缩减 ： 14.0x 更小
premium 请求（估计的代理往返次数）
没有 ctxmem ： 6 （1 次定位 + 5 次文件读取）
使用 ctxmem ： 1 （单次召回）
节省 ： 5 （6.0x 更少）
```
基准：`files`（默认 - 结果文件后的全文），`memory`（整个 `memory.jsonl`），`repo`（所有索引代码 + 记忆）。测试文件默认 **排除**（使用 `--include-tests` 可包含），因为实际代理不会粘贴整个测试套件来回答问题。token 计数在安装 `tiktoken` 时使用（`pip install "ctxmem[bench]"`），否则使用可移植的 ~chars/4 估计（标签显示使用哪种）。
运行整个问题套件并生成可分享的报告，包含图表：
```bash
ctxmem bench --suite questions.txt --baseline files --report bench-out
# 生成 bench-out/report.md, bench-out/bench_tokens.svg, bench-out/bench_requests.svg
```
## 📊 9. 基准测试 - 它是如何测试的
声明“ctxmem 节省 tokens 和 premium 请求”并非空口无凭 - 它在真正的第三方代码库上进行了测量，并且完全可复制。
**设置**
- **测试仓库：** [Django](https://github.com/django/django) 源代码树（~2,900 Python 文件，~45k 索引符号）- 一个大型、独立的代码库，以避免任何主场优势。
- **问题：** 15 个真实的“ onboarding” 问题，开发者会问（QuerySet、URL 路由、模型字段、表单验证、中间件、身份验证、迁移、信号、ORM 管理器、管理员、会话、WSGI、模型表单）。参见 [`example/bench_questions_django.txt`](example/bench_questions_django.txt)。
- **“没有 ctxmem” 基线：** 相关的 **源代码文件** 的全文，代理通常会打开 - **排除测试文件**，因为转储整个测试套件会高估成本。
- **“使用 ctxmem”：** 单个 `ctxmem recall` 返回的代码片段。
- **tokenizer：** `tiktoken` / `cl100k_base`（GPT-4 / Copilot 家族）。
**结果**
| 指标 | 没有 ctxmem | 使用 ctxmem | 改进 |
|---|--:|--:|--:|
| 上下文 tokens（13 个可回答问题） | 272,354 | 14,028 | **19.4× 更小**（94.8%） |
| 高级请求（代理往返次数） | 49 | 13 | **3.8× 更少** |
每问题上下文 tokens：
每问题高级请求（按 **模型往返次数** 计费，而不是按 token - 没有存储记忆，代理定位自身然后打开相关文件；ctxmem 在一次 `recall` 中返回所有代码片段）：
**自己复制**
```bash
git clone https://github.com/django/django ~/bench-django
cd ~/bench-django
pip install "ctxmem[bench]"
ctxmem init && ctxmem sync # 索引仓库（~秒）
ctxmem bench --suite /path/to/bench_questions_django.txt \
--baseline files --report bench-out
```
**诚实阅读这些数字**
- token 数字是你 **提供给模型** 的上下文，而不是 Copilot 账单。token 节省直接转化为 **token 计费 API**（OpenAI/Anthropic）的费用节省和上下文窗口限制的更多余地。
- 对于 **GitHub Copilot 订阅**（按 **高级请求** 计费），杠杆是右侧图表：每个问题的高级请求次数更少。
- 并非每个查询都赢得很多 - 小文件或广泛的问题节省较少，套件也包括这些。报告按原样生成，没有挑选。
## 🔍 10. 搜索模式：关键字 vs 语义 vs 混合
| 模式 | 查找结果方式 | 需要 | 速度 | 默认 |
|------|------------------|-------|-------|---------|
| `keyword` | 匹配 **单词**（SQLite FTS5） | 无 | 即时 | ✅ |
| `semantic` 🧪 | 匹配 **含义**（嵌入） | sqlite-vec + Ollama | 稍慢 | — |
| `hybrid` 🧪 | 两者皆有，结果合并 | sqlite-vec + Ollama | 稍慢 | — |
> 🧪 **`semantic` 和 `hybrid` 为测试版** - 本地嵌入后端为实验性且正在积极测试。`keyword` 模式稳定且无需设置。如果语义后端不可用，ctxmem **自动回落到关键字** 并通知您（`[keyword (fallback)]`）。
- **关键字**：优秀，零设置基准。搜索 `"login"` 不会找到仅包含 `"authentication"` 的笔记。
- **语义** 🧪：理解含义，因此 `"login"` 找到 `"authentication"`。使用本地嵌入模型 - 无云。
- **混合** 🧪：运行两者并合并 - 最佳召回。
模式存储在 `.ctxmem/config.json` 中（因此它是共享的）。
```bash
ctxmem init --mode hybrid
ctxmem mode # 显示当前模式 + 后端可用性
ctxmem mode semantic # 切换（测试版）
ctxmem recall "auth" --mode keyword # 为单个查询覆盖
```
## 🤝 11. 与团队共享
记忆通过 git 像代码一样传递：
```bash
# 你
ctxmem remember --type decision "Payments go through Stripe, not PayPal."
git add .ctxmem/memory.jsonl && git commit -m "memory: payments" && git push
# 你的同事
git pull
ctxmem recall "payments" # 索引从 memory.jsonl 重建 → 相同的上下文
```
因为 `memory.jsonl` 是一个普通文件：
- **分支感知：** 每个分支都有自己的决策；切换分支，`recall` 反映它。
- **合并友好：** 附加行合并干净；冲突很少且可读。
- **无服务器：** 无需托管，无需同步 - git *是* 传输工具。
## 🪝 12. 使用 git 钩子自动同步
保持索引自动刷新：
```bash
ctxmem hook install # 写入 .git/hooks/post-commit
ctxmem hook uninstall
```
每次 `git commit` 后，索引重建，因此 `recall` 始终反映最新的代码和决策。钩子使用您确切的 Python 解释器，因此它适用于虚拟环境。
## 🤖 13. 从 AI 代理使用
有两种方法将代理（如 Codex 或 GitHub Copilot）连接到记忆。它们是独立的 - 使用允许您的设置使用哪种。
### 选项 A - 指令 + CLI（推荐，无需 MCP）
代理已经运行终端命令，因此它可以直接驱动 `ctxmem` CLI。你只需通过指令文件告诉它何时 `recall` 和 `remember`。即使 MCP 不可用或因策略禁用，此方法也有效。
在单个命令中设置：
```bash
ctxmem agent-init --agent codex # 写入/更新本地 AGENTS.md
ctxmem agent-init --agent copilot # 写入/更新 .github/copilot-instructions.md
ctxmem agent-init --agent all # 写入两个指令文件
ctxmem agent-init --agent all --mcp # 还会生成 .vscode/mcp.json（适用于选项 B）
```
这在托管标记之间插入 **项目内存协议**（`<!-- ctxmem:begin -->` ... `<!-- ctxmem:end -->`）。它是 **幂等** 的：如果文件已经存在，它会追加该部分；重新运行会在不重复或触及您其他指令的情况下更新该部分。
Codex 使用 `AGENTS.md`（通常本地且被 gitignore）。GitHub Copilot 使用 `.github/copilot-instructions.md`。默认情况下， `--agent copilot` 保持不变以保持向后兼容。
协议告诉代理：
1. 在任务开始前运行 `ctxmem recall "<the request>"` 以加载相关上下文；
2. 在做出或确认重要决定时运行 `ctxmem remember …`；
3. 在更改代码后运行 `ctxmem sync`。
要求和提示：
- **`ctxmem` 必须在代理使用的终端中 **位于 PATH**。如果您在虚拟环境中安装了它，请全局公开它，例如 `ln -s "$(command -v ctxmem)" ~/.local/bin/`。
- 在可以使用终端命令的模式下使用代理（Codex 或 VS Code Copilot **Agent** 模式）。在客户端提供命令允许列表时，选择 **“始终允许”** 以使用 `ctxmem`。
- 在 `agent-init` 后启动 **新聊天** 以加载更新后的指令。
- **现实检查：** 大型语言模型（LLM）是概率性的 - 强大的指令协议使得主动保存 **可靠**，但不是 **保证** 的。为了 100% 的确定性，请显式保存（询问代理，或运行 `ctxmem remember` 您自己），或通过 git 钩子。
### B 选项 - MCP 服务器
`ctxmem` 还附带了一个 [MCP](https://modelcontextprotocol.io) 服务器，以便代理可以像调用原生工具一样调用记忆。MCP 是 **开放标准**（MIT 许可的 SDK）；服务器 **本地运行** 并且只读取您的仓库。
```bash
pip install "ctxmem[mcp]"
```
注册它（VS Code `.vscode/mcp.json`，由 `agent-init --mcp` 也是创建的）：
```json
{
"servers": {
"ctxmem": {
"command": "ctxmem-mcp",
"env": { "CTXMEM_ROOT": "${workspaceFolder}" }
}
}
}
```
> 如果 `ctxmem-mcp` 不在全局 PATH 上（例如，它位于虚拟环境中），请使用二进制文件的绝对路径作为 `command`。
向代理公开的工具：
- `recall(query, limit, type, mode)` - 在任务开始前拉取相关上下文。
- `remember(content, type, title, tags)` - 在完成后记录决策。
- `memory_status()` - 模式、分支/提交、索引计数。
**模式（两种选项）：** 代理在任务开始时调用 `recall`（注入相关代码片段，远低于 token 限制），在结束时调用 `remember` - 因此项目的记忆增长并在会话间持续。
## 🧪 14. 使用 Ollama 的语义后端（测试版）
> ⚠️ **测试版 / 实验性。** 语义搜索有效，但正在积极测试。关键字模式仍然是稳定的默认模式。预计未来版本中语义设置和默认值会发生变化。
语义搜索需要两个开源、完全本地的组件：
- **[Ollama](https://ollama.com)** 在您的机器上运行嵌入模型（离线，无 API 密钥）。我们使用小型 `nomic-embed-text` 模型。
- **[sqlite-vec](https://github.com/asg017/sqlite-vec)** 在 SQLite 中存储向量并执行最近邻搜索（单个可加载扩展，无服务器）。
### 选项 A - 在主机上安装 Ollama
```bash
pip install "ctxmem[semantic]"
# 从 https://ollama.com 安装 Ollama，然后：
ollama pull nomic-embed-text
ctxmem mode semantic
```
### B 选项 - 在隔离的 Lima VM 中运行 Ollama
将 Ollama 移出主机。访客端口 `11434` 转发到主机，因此 ctxmem（默认 `ollama_url = http://localhost:11434`）无需额外配置。
```bash
cd ollama
task start # 创建 VM、安装 Ollama、拉取 nomic-embed-text
task status # 验证端点响应
task demo # ctxmem 语义模式 + 真实查询
task stop # 或：task delete （完全可逆）
```
`ollama/lima.yaml` 准备 Ubuntu 24.04，安装 Ollama 作为 systemd 服务，拉取模型，并包含就绪探测。`ollama/Taskfile.yaml` 包装生命周期为 `task` 命令。
## ❓ 15. 常见问题
**您的数据会发送到哪里吗？** 不会。所有操作都是本地的：仓库中的 SQLite 文件和（如果您启用语义模式）本地 Ollama。MCP 服务器也 **本地运行**。
**我必须使用嵌入吗？** 不会。`keyword` 模式不需要任何设置，是默认模式。语义模式是可选的，仍处于测试阶段。
**我应该提交 `index.db` 吗？** 不会 - 它是派生的并且被 gitignore。提交 `memory.jsonl` 和 `config.json`。
**如果队友没有 Ollama 怎么办？** ctxmem 自动回落到关键字模式；共享内存仍然有效。
**它能扩展到大型仓库吗？** 关键字索引适用于大型仓库。嵌入成本为 `sync` 每个块一次 Ollama 调用；对于非常大的代码库，增量（基于 diff）的索引是一个自然的下一步。
**MCP 是专有的吗？** 不会。MCP 是具有 MIT 许可的 SDK 的开放协议。您的代理背后的底层 LLM 可能是专有的，但这里的内存和协议是完全开放和自托管的。
## 🤝 16. 贡献
欢迎贡献！此项目遵循 **Git Flow** 分支模型（`feature/*`、`bugfix/*`、`hotfix/*` → `develop` → `main`）。在打开拉取请求之前，请阅读 **[贡献指南](CONTRIBUTING.md)** - 它涵盖了分支命名、提交约定、标签、里程碑和发布过程。
## 📄 17. 许可证
在 [MIT 许可证](LICENSE) 下发布。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器