内容
# 代码索引 — 面向 AI 智能体的结构化代码索引
[GitHub: TAskMAster339/memos-engine](https://github.com/TAskMAster339/memos-engine.git)
<div align="center">
[](https://codecov.io/gh/TAskMAster339/memos-engine)
</div>
`memos` 通过 tree-sitter 构建了 **结构化索引**（符号、调用边、导入）以支持 TypeScript / TSX / Go / Python / JavaScript 代码库，并将其存储在 SQLite 中。它是为 AI 编程智能体设计的更大 *Memory OS* 的第一层 —— 智能体通过查询 **结构**（定义、调用者、被调用者）而不是 grep 文本。
## 将 memos 集成到您的项目中
为您的 AI 编程智能体提供结构化的代码理解和持久内存，请按照以下三个步骤将 memos 添加到您的项目中：
**1. 安装 memos**
```bash
pip install memos-engine
# 或使用 uv：
uv tool install memos-engine
```
或克隆并从源代码安装：
```bash
git clone https://github.com/TAskMAster339/memos-engine.git
cd memos-engine
uv tool install -e .
```
**2. 索引您的项目**
```bash
cd /path/to/your/project
memos index --path .
```
这会在 `{project}/.memos/memory.db` 中创建所有符号、调用边和导入的索引。后续运行会跳过未更改的文件。
**3. 将 AGENTS_EXAMPLE.md 添加到您的项目中**
将 `AGENTS_EXAMPLE.md` 文件从 memos 仓库复制到您的项目的根目录中，作为 `AGENTS.md`（或 `CLAUDE.md`，或 `.opencode/instructions`，具体取决于您的智能体）。它告诉智能体：
- 在每次会话开始时调用 `open_project`
- 使用 `find_symbol_tool` / `find_calls_tool` 代替 grep
- 在编辑函数之前调用 `get_context_tool`
- 通过 `memory_add_note` 保存决策，以便在会话之间存活
在 `AGENTS_EXAMPLE.md` 中，您只需要更改存储库路径（如果您的智能体无法自动解析相对路径）。其他内容都已准备就绪。
**可选：为您的 AI 客户端配置 MCP** — 请参见下面的 [MCP 服务器](#mcp-服务器)。
## 快速入门
```bash
# 克隆并全局安装
git clone https://github.com/TAskMAster339/memos-engine.git
cd memos-engine
uv tool install -e .
# 检查版本
memos --version
# 索引项目
memos index --path /path/to/your/project
# 列出所有可用的 MCP 工具
memos tools
# 为 AI 智能体启动 MCP 服务器
memos serve-mcp
# 运行项目诊断
memos doctor --path /path/to/your/project
# 监视文件并自动重新索引
memos watch --path /path/to/your/project
```
或使用 `uv run` 而不进行全局安装：
```bash
uv sync # 安装依赖
uv run memos index --path . # 索引当前项目
uv run memos index --path . --full # 强制重新索引（忽略哈希）
uv run memos index --path . --no-embed # 跳过嵌入（更快）
uv run memos index --path . --profile # 打印阶段计时
```
## 查询
```bash
# 按名称查找符号
uv run memos query symbol greet
# 按类型过滤
uv run memos query symbol greet --kind function
# 查找调用符号（调用者）
uv run memos query calls greet --direction callers
# 查找符号调用的内容（被调用者）
uv run memos query calls main --direction callees
# 显示文件的全部信息（符号 + 调用 + 导入）
uv run memos query module src/index.ts
```
所有查询命令都输出 JSON，并接受 `--path <project_root>` 以指向索引项目（默认为当前目录）。
## HTTP API
在索引项目上启动 FastAPI 服务器：
```bash
# 通过 CLI
uv run memos serve --path /project --port 8000
# 或直接通过 uvicorn
MEMOS_PROJECT_PATH=/project uv run uvicorn memos.api.main:app
```
端点：
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/symbols?name=greet&kind=function` | 按名称查找符号 |
| GET | `/symbols/{id}/calls?direction=callers\|callees` | 查找调用者/被调用者 |
| GET | `/symbols/{id}/context` | 完整上下文（符号 + 调用者 + 被调用者 + 内存 + 摘要） |
| GET | `/symbols/{id}/rename-impact` | 分析重命名影响范围 |
| GET | `/modules/{path}` | 显示文件的所有信息 |
| GET | `/modules/{path}/diff-impact` | 分析导出符号的差异影响范围 |
| GET | `/unused-symbols` | 查找从未调用的私有函数 |
| GET | `/dead-imports` | 查找未解析的导入 |
| GET | `/dependency-graph` | 文件级依赖图 |
| GET | `/import-cycles` | 查找导入循环 |
| POST | `/search/semantic` | 基于自然语言的语义搜索 |
| POST | `/memories` | 添加内存条目 |
| GET | `/memories` | 列出内存条目 |
| GET | `/memories/search?query=...` | 内存条目的全文搜索 |
| POST | `/memories/prune` | 删除过时的内存条目（默认为干运行） |
所有端点都返回 JSON。设置 `MEMOS_PROJECT_PATH`（默认为 `.`）。
## 语义搜索
```bash
# 通过 HTTP API
curl -X POST http://localhost:8000/search/semantic \
-H "Content-Type: application/json" \
-d '{"query": "用户身份验证", "top_k": 5}'
```
使用 fastembed（ONNX，无需 GPU）通过 `all-MiniLM-L6-v2` 嵌入。
## MCP 服务器
MCP 服务器向 AI 智能体公开索引代码库。全局安装：
```bash
pip install memos-engine
memos serve-mcp
```
或使用 uv：
```bash
uv tool install memos-engine
memos serve-mcp
```
或无需全局安装（从源代码检出）：
```bash
uv run memos serve-mcp
```
服务器启动时没有项目。使用 `open_project` 工具选择项目：
```json
{
"tool": "open_project",
"arguments": {
"path": "/path/to/your/project"
}
}
```
服务器在项目未索引时自动索引项目。可以在同一会话中打开和查询多个项目，无需重启服务器。
可用工具：
| 工具 | 描述 |
|------|-------------|
| `open_project` | 按路径打开项目（如果需要，自动索引） |
| `find_symbol_tool` | 按名称搜索符号（+ 类型，文件过滤器） |
| `find_calls_tool` | 查找调用者或被调用者 |
| `get_module_tool` | 完整的文件信息（符号，调用，导入） |
| `get_context_tool` | 编辑前的完整上下文（符号 + 调用者 + 被调用者 + 内存 + 摘要） |
| `semantic_search_tool` | 代码的自然语言搜索 |
| `list_files_tool` | 列出所有索引文件 |
| `list_symbols_tool` | 列出所有索引符号 |
| `list_projects_tool` | 当前项目信息，带统计数据 |
| `memory_add_note` | 添加到情景记忆 |
| `get_memories` | 检索记忆条目 |
| `rename_impact_tool` | 分析符号重命名的影响 |
| `diff_impact_tool` | 分析文件的导出符号的影响范围 |
| `find_unused_symbols_tool` | 查找从未调用的私有函数 |
| `find_dead_imports_tool` | 查找未解析的导入 |
| `get_dependency_graph_tool` | 文件级依赖图 |
| `find_import_cycles_tool` | 查找导入循环 |
| `memory_search_tool` | 内存条目的全文搜索 |
| `memory_prune_tool` | 删除过时的内存条目（默认为干运行） |
| `reindex_file_tool` | 在编辑后重新索引单个文件 |
| `usage_stats_tool` | 显示每会话的工具调用计数器（在服务器重启时重置） |
每个查询工具都接受一个可选的 `project` 参数，以针对特定的打开项目（默认为最近打开的项目）。
### 与 OpenCode 集成
将以下内容添加到您的 OpenCode MCP 配置中：
```json
{
"mcpServers": {
"memos": {
"command": [
"memos",
"serve-mcp"
]
}
}
}
```
然后在 OpenCode 中使用 `open_project` 选择您的项目。
### 与 Claude Desktop 集成
在 `claude_desktop_config.json` 中配置：
```json
{
"mcpServers": {
"memos": {
"command": "memos",
"args": ["serve-mcp"]
}
}
}
```
## 测试
```bash
uv run pytest -v
# 覆盖率（排除慢测试）
uv run pytest --cov=memos --cov-report=term-missing -m "not slow"
```
## 架构说明
- **两种内存类型**：*派生*（AST，摘要 — 可重现，按内容哈希键控）和 *情景*（智能体笔记 — 追加，仅在重构后存活）。
- **索引器** 生成纯数据类（`ParseResult`）；CLI 将它们转换为用于数据库插入的 pydantic 模型。
- **调用边** 和 **导入** 在第一次传递时存储为未解析（FK = NULL）；第二次传递解析是一个单独的任务。
- CLI（`memos index`）是 `indexer/` + `core/db.py` 的薄适配器 — 无业务逻辑。
- 语义搜索：sqlite-vec vec0 表，延迟加载的 fastembed 模型，在重新索引时进行级联清理（`--no-embed` 标志跳过）。嵌入以 256 的批次计算，带有丰富的进度条（`--profile` 用于阶段计时）。
- MCP 服务器（`memos serve-mcp`）是 `query/core.py` 的薄 FastMCP 适配器 — 与 FastAPI 适配器相同的模式。
