内容
# 基础记忆：AI 知识库系统
一个轻量级知识库，适用于 AI 会话之间。行星（planets）保存任务上下文，笔记（notes）持久化决策，链接的边（edges）形成可学习的图，MCP 工具允许任何代理读取和写入相同的数据。**设计为现有聊天接口的插件**（如 Claude Code、Codex、Gemini CLI 等），而非独立的聊天系统。
关键集成规则：
1. 在第一个用户之后，在第一个答案之前，读取知识库。
2. 将检索到的上下文传递给代理提示或将其暴露为工具。
3. 在答案后写入持久更新。
基础记忆提供了一个规范的预答案上下文命令：
```bash
mem agent-context --topic "项目名称" --query "我正在做什么？"
```
## 快速入门
### 安装（单命令）
```bash
chmod +x setup.sh && ./setup.sh
```
这将全局安装 `mem` CLI，并为 Claude Code、Cursor、Windsurf、Gemini 和 Codex 配置 MCP。
### 基本用法
```bash
# 创建一个行星（一个具有目标和状态的主题/工作区）
mem planet create "我的项目" --goal "构建功能 X" --state "研究阶段"
# 更新其状态和下一步
mem planet set "我的项目" --status active --next "阅读文档"
# 添加决策或事实
mem note add "我的项目" --type decision -m "使用 SQLite 进行持久化"
# 在回答之前获取代理就绪的上下文
mem agent-context --topic "我的项目" --query "我们决定了什么？"
# 读取完整行星详细信息
mem planet read "我的项目"
# 记录一个回合（轻量级活动记录）
mem session turn --topic "我的项目" --message "审查了 PR" --agent-id "codex"
```
### 搜索
```bash
mem search "什么是机器学习"
```
### 查看您的行星
```bash
mem session context
```
### 导入 AI 聊天历史
```bash
mem session sync "主题名称" --agent-id "您的唯一后缀"
```
所有 CLI 命令都写入与 MCP 工具相同的 `planets` 和 `notes` 表 - 无需同步。
## 通用代理集成
代理不会自动知道您的知识库。您的启动器和主机指令必须使代理在第一个用户之后和第一个答案之前检查内存。
### 已安装 CLI
运行 `./setup.sh` 安装 `mem` 并为 Claude Code、Cursor、Windsurf、Gemini 和 Codex 配置 MCP，以及用于自动内存检索的钩子和插件。
### MCP 工具
如果您的主机支持 MCP，位于 `mcp_server/server.py` 的服务器会暴露这些工具：
**上下文和发现**
- `get_agent_context(topic, query)` — 紧凑的预答案内存块
- `read_planet(topic)` — 具有所有笔记的完整行星详细信息
- `list_planets()` — 发现存在哪些主题
- `search_nodes(query)` — 跨所有内容的全文搜索
- `search_notes(topic, kind, query)` — 筛选的笔记搜索
- `get_node(node_id)` — 按 ID 读取任何节点
**写入**
- `update_planet(topic, current_state, next_step, status, goal, ...)` — 更新或创建行星
- `add_note(topic, kind, content)` — 持久化决策、事实或问题
- `log_turn(topic, content)` — 轻量级活动记录
- `link_notes(from_id, to_id, link_type)` — 连接两个笔记
- `link_planets(from_planet, to_planet, relation)` — 连接两个行星
- `set_memory_state(topic, state)` — 设置热/暖/压缩
**图导航**
- `get_note_neighbors(note_id)` — 查找链接到笔记的所有笔记
- `get_planet_links(planet)` — 查找链接到行星的所有行星
- `get_neighbors_weighted(note_id, depth, min_weight)` — 递归加权遍历
- `get_subgraph(note_id, depth, min_weight)` — 提取结构化子图
- `rank_neighbors(note_id, by)` — 按权重或置信度排序邻居
**代理驱动智能**
- `compute_similarity(note_id_a, note_id_b)` — 返回两个笔记供代理判断相似性
- `rerank(query, note_ids)` — 返回查询 + 笔记供代理重新排序
**代码智能** （tree-sitter 支持，每个项目 `.basemem.code.db`）
- `code_init(project_root)` — 索引项目；在项目根目录中存储 `.basemem.code.db`
- `code_find(query, root, dead, file_path, limit)` — 按名称、详细信息、死代码或文件筛选查找符号
- `code_explore(query, root)` — 一次性：搜索 + 源代码 + 调用路径
- `code_files(prefix, root)` — 具有符号计数的项目文件树
- `code_impact(symbol, root, depth)` — 传递逆向依赖图
- `code_trace(symbol, root, direction, depth)` — 递归入站/出站调用链
- `code_list_projects(search_root)` — 扫描文件系统以获取所有索引项目
**图生命周期**
- `edge_decay(factor, planet)` — 将所有自动链接权重乘以因子
- `edge_prune(threshold, planet)` — 删除低于权重阈值的自动链接
**生命周期**
- `summarize_planet(topic)` — 返回所有笔记供代理总结
- `compact_planet(topic)` — 保留总结 + 30 个最近的笔记
推荐的主机策略：
1. 在第一个用户之后和第一个模型答案之前调用 `get_agent_context`。
2. 在工作上下文中包含该输出。
3. 在答案后调用 `log_turn` 和可选的 `update_planet` 或 `add_note`。
## 架构
基础记忆是一个 **零 RAM “ dumb storage” 层**。没有 Torch、Transformers 或 FAISS。所有智能（摘要、相似性、重新排序）都由连接的 AI 代理提供。内存使用约 35MB RAM。
### 统一数据层
所有接口（CLI、MCP、Flask）都读取和写入相同的 SQLite 表：
- **`planets`** — 主题工作区，包含状态、目标、状态、文件、命令、下一个步骤、内存层（热/暖/压缩）、别名
- **`notes`** — 类型记录（决策、事实、问题、概念、示例、回合、摘要），包含标题、agent_id、状态
- **`note_links`** — 带置信度、来源（自动/显式）、link_type（相关、依赖、实现）的有权重的边
- **`planet_links`** — 带权重的边
#### 自动链接
调用 `add_note` 时，新笔记会自动与同一行星上的现有笔记使用 Jaccard 相似性（阈值 0.2）链接。显式链接覆盖自动链接。边缘强化通过共同访问将自动链接权重增加 0.05。
#### 内存层
- **热** — 活动工作笔记（默认）
- **暖** — 稳定知识，最近未访问
- **压缩** — 由代理总结，仅保留总结 + 30 个最近笔记
### 核心组件
1. **存储层** (`storage/`)
- SQLite + FTS5 用于全文搜索
- `SessionManager` — 所有行星/笔记/链接操作，导出/导入，边缘生命周期
- 架构：planets, notes, note_links, planet_links
2. **MCP 服务器** (`mcp_server/server.py`)
- 28 个 MCP 工具（19 个内存 + 9 个代码）
- 与 CLI 和 Flask 共享相同的 DB 路径
3. **Web Hub** (`server.py`)
- 所有操作的 Flask REST API
- `/` 处的 D3.js 图形可视化
- `/inject` 处的书签注入
- `/log-chat` 处的聊天记录器
4. **CLI 接口** (`cli/main.py`)
- `mem planet create/read/set/delete/compact/summarize/link/set-state`
- `mem note add/link/neighbors`
- `mem search` — 跨行星、笔记和节点的全文搜索
- `mem agent-context` — 紧凑的预答案内存块
- `mem list-planets` — 列出所有行星
- `mem session turn/context/read/sync`
- `mem recompute-links` — 重新计算所有笔记对的 Jaccard 相似性
- `mem edge decay/prune` — 图生命周期管理
- `mem export` / `mem import` — 多设备同步
5. **代码智能** (`indexer/`) — 每个项目 `.basemem.code.db` 在项目根目录
- `mem code init [--watch]` / `mem code sync` — 索引或增量重新索引项目
- `mem code find <query> [--dead] [--file-path]` — 按名称、详细信息、死代码或文件查找符号
- `mem code explore <query>` — 一次性：搜索 + 源代码 + 调用路径
- `mem code files` — 具有符号计数的项目文件树
- `mem code impact <symbol> [--depth]` — 传递逆向依赖图
- `mem code trace <symbol> [--direction both] [--depth]` — 递归入站/出站调用链
- `mem code query <query> [--kind] [--json]` — 原始符号搜索，可选过滤
- `mem code callers / callees / node / list / status / list-projects / search`
- 在搜索之前，每个项目运行 `mem code init`；`list-projects` 会发现它们
## 项目结构
```
BaseMem/
├── cli/
│ ├── __init__.py
│ └── main.py # CLI 命令
├── graph/
│ ├── __init__.py
│ └── engine.py # 图引擎
├── indexer/ # 代码智能模块（tree-sitter）
│ ├── __init__.py
│ ├── parser.py # 代码解析器，tree-sitter
│ ├── indexer.py # 目录遍历器，符号/边持久化，FTS5
│ ├── schema.py # 代码表
│ └── watcher.py # 监视器自动同步
├── mcp_server/
│ ├── __init__.py
│ └── server.py # 模型上下文协议服务器（28 个工具）
├── processing/
│ └── __init__.py
├── storage/
│ ├── __init__.py
│ ├── db.py # SQLite 存储管理器
│ └── sessions.py # 会话管理器
├── models.py # 数据模型
├── server.py # Flask REST API + D3 可视化
├── mem.py # CLI 入口点
├── mem-mcp.py # MCP 入口点
├── pyproject.toml
├── setup.sh
├── setup.ps1
├── uninstall.sh
├── uninstall.ps1
├── extensions/gemini/
├── tests/
├── README.md
└── LICENSE
```
### 已移除模块
- **处理管道** — `LocalSummarizer`、`IngestWorker`、`ProcessingPipeline`。所有总结都是通过 `summarize_planet` + `add_note(topic, 'summary', ...)` 由代理驱动的。
- **检索模块** (`retrieval/`) — `BM25Retriever`、`VectorRetriever`、`RetrievalEngine`。代理驱动的检索取代了本地机器学习。
- **编排模块** (`orchestrator/`) — 带有 `orchestrate()` 的 `ContextOrchestrator`。所有上下文构建现在都是代理驱动的。
- **可视化模块** (`visualization/`) — 带有 ASCII 图形输出的 `TerminalVisualizer`。未在生产中使用。
- **旧 `nodes`/`edges` 表** — 保留以确保向后兼容，但不再是主要模型。所有新数据都转到 `planets`/`notes`/`note_links`。
## 数据模型
### 行星
带有元数据和生命周期状态的主题工作区。
```python
{
"topic": "str", # 唯一标识符
"display_topic": "str", # 人类可读名称
"status": "str", # 活动、暂停、完成、存档
"goal": "str", # 高级目标
"current_state": "str", # 当前情况
"next_step": "str", # 直接下一步
"next_steps": "list", # 即将采取的步骤的 JSON 数组
"files": "list", # 相关文件路径的 JSON 数组
"commands": "list", # 有用的命令的 JSON 数组
"handoff": "str", # 移交给下一个会话的说明
"aliases": "list", # 替代名称的 JSON 数组
"memory_state": "str", # 热、暖或压缩
}
```
### 笔记
链接到行星的 typed 记录。
```python
{
"id": "int",
"topic": "str", # 行星标识符
"kind": "str", # 决策、事实、问题、概念、示例、回合、摘要
"content": "str",
"title": "str",
"agent_id": "str",
"status": "str", # 打开、已解决、已关闭
"turn_index": "int",
}
```
### 笔记链接
两个笔记之间的有权重的边。
```python
{
"from_note_id": "int",
"to_note_id": "int",
"link_type": "str", # 相关、依赖、实现、自动
"weight": "float", # 0-1
"confidence": "float", # 0-1（自动链接上限为相似性 * 1.5）
"source": "str", # 自动或显式
"created_at": "str",
"updated_at": "str",
}
```
### 行星链接
两个行星之间的有权重的边。
```python
{
"from_planet_id": "int",
"to_planet_id": "int",
"relation": "str", # 相关、依赖
"weight": "float", # 0-1
}
```
## 配置
```bash
export BASEMEM_DB_PATH="./data/basemem.db"
```
默认位置：`~/.basemem/basemem.db`
## 开发
### 从源代码安装
```bash
python -m venv venv
source venv/bin/activate
pip install -e .
```
### 运行测试
```bash
pytest tests/ -v
```
## 许可证
MIT
