内容
# 🧠 Engram MCP
**一个零依赖、自动衰减、纯SQLite的MCP服务器，用于持久化AI智能体记忆。**
*在下午构建。测试比构建更严格。因为代码不足以说明一切。*
> *engram（名词）：一种假设的物理记忆痕迹，存储在大脑中——记忆持续的生物学基础。*
[](LICENSE)
[](https://python.org)
[](#)
[](https://modelcontextprotocol.io)
Engram是一个完全本地、极速的记忆层，适用于通过[模型上下文协议（MCP）](https://modelcontextprotocol.io)连接的AI智能体（Claude Code、Cursor、Windsurf等）。它完全基于Python 3标准库构建。无需云API密钥，无需向量数据库，无需Docker，也无需臃肿。
---
## 🛑 问题：智能体健忘症
如果你使用过AI编码智能体，你会知道它的沮丧：**每次会话都完全从头开始**。
智能体不会记得你更喜欢`pnpm`而不是`npm`，它会忘记你昨天同意的架构边界，并且它会不断要求你提供相同的上下文。
现有的解决方案试图通过附加巨大的向量数据库（PostgreSQL/pgvector、Chroma、Pinecone）来解决这个问题，这些数据库需要沉重的依赖、Docker容器和昂贵的OpenAI API调用来生成嵌入。
## 💡 解决方案：什么是Engram MCP？
**Engram MCP**是一个无依赖、优化至极致的替代方案。它使用标准的**SQLite FTS5（全文搜索）**来实现闪电般快速的关键词检索，完全本地运行。你只需将`server.py`脚本放入MCP配置中，你的智能体就会立即获得在会话之间记住、回忆和管理自己长期记忆的能力。
### 关键优势
* **停止重复自己：** 仅需一次教导你的智能体你的偏好、技术栈和架构决策。它将自动在下次启动时回忆它们。
* **零基础设施：** 无需启动数据库。Engram会自动在你的主目录中创建一个本地SQLite文件（`~/engram-mcp/memory.db`）。
* **零API成本：** 因为它使用本地BM25/FTS5关键词索引而不是语义嵌入，所以你支付的API积分用于内存检索为$0。
* **完全的数据隐私：** 你的代码库上下文和架构秘密永远不会离开你的本地机器。
---
## 🚀 核心功能与特性
1. **🐍 零依赖**
完全运行在Python标准库（`sqlite3`、`json`、`sys`、`hashlib`）上。无需`pip install`。
2. **⏳ 智能自动衰减（遗忘机制）**
与其他服务器不同，其他服务器会永久保留数据，Engram通过后台自动衰减算法防止陈旧上下文污染：
* 每当智能体搜索或检索记忆时，它会自动增加`access_count`并更新`updated_at`时间戳。
* 每当MCP服务器启动时，它都会运行后台衰减查询：任何未在30天内访问过的记忆都会自动失去1个`importance`点。
你的智能体的上下文窗口保持清洁、相关性强，并且无需手动干预即可自我维护。
3. **🛡️ 企业级并发性（WAL模式）**
设计用于多智能体工作流。Engram实现了SQLite的写前日志记录（`PRAGMA journal_mode=WAL`）和严格的连接超时。你可以同时运行Cursor和Claude Code，而不会触发`database is locked`崩溃。
4. **🔒 有效载荷限制和弹性**
Engram严格限制内存输出（最多8个结果），以防止LLM上下文窗口爆炸，并将传入的记忆截断为8,000个字符，以防止有效载荷膨胀。
5. **⌨️ 独立CLI管理器**
配备内置的终端工具（`engram.py`），允许人类开发者手动查看、编辑、搜索或删除智能体的记忆。
---
## ⚙️ 工作原理（架构）
```text
┌──────────────────────────────────────────────┐
│ AI 智能体 / LLM │
│ (Claude, Gemini, GPT, 等) │
└──────────────┬───────────────────────────────┘
│ JSON-RPC 2.0 over STDIO
▼
┌──────────────────────────────────────────────┐
│ Engram MCP 服务器 (server.py) │
│ ┌────────────┐ ┌─────────────────────────┐ │
│ │ 工具路由 │ │ SQLite3 + FTS5 引擎 │ │
│ │ 自动衰减 │ │ WAL 模式并发性 │ │
│ └────────────┘ └─────────────────────────┘ │
└──────────────┬───────────────────────────────┘
│
▼
┌──────────────────────────────────────────────┐
│ memory.db (本地文件) │
│ ┌────────┐ ┌───────────┐ ┌────────────┐ │
│ │ 记忆 │ │ 记忆_fts │ │ 索引 │ │
│ └────────┘ └───────────┘ └────────────┘ │
└──────────────────────────────────────────────┘
```
当智能体请求记忆时，Engram执行多轮FTS5关键词搜索。如果语法格式不正确，它会优雅地回退到标准的`LIKE` SQL查询。它会删除重复的结果，增加访问时间戳，并直接向LLM返回一个受限的数组。
---
## ⚡ 快速开始
### 1. 克隆仓库
```bash
git clone https://github.com/lalithbuilds/engram-mcp.git
cd engram-mcp
```
### 2. 配置你的MCP客户端
将Engram添加到你的MCP配置文件中（例如`claude_desktop_config.json`或Cursor的MCP设置）：
```json
{
"mcpServers": {
"engram": {
"command": "python3",
"args": ["server.py"],
"cwd": "/absolute/path/to/engram-mcp"
}
}
}
```
### 3. 完成。
无需虚拟环境，无需`requirements.txt`。当你开始新的聊天时，你的智能体将自动使用`memory_auto_context`工具。
---
## 🛠️ `engram` CLI工具
你始终可以控制智能体记住的内容。你可以使用捆绑的`engram.py` CLI工具与数据库进行交互。
```bash
# 手动为智能体保存新的记忆
python3 engram.py save "我们使用Tailwind CSS进行所有样式设计，而不是原始CSS。" --category frontend --importance 10
# 搜索智能体对某个主题的了解
python3 engram.py search "Tailwind"
# 列出数据库中的所有记忆
python3 engram.py list
# 通过ID删除特定的记忆
python3 engram.py delete abc123def456
# 查看数据库大小和类别分布
python3 engram.py stats
```
---
## 🤝 贡献
我们欢迎贡献！特别是，我们正在寻找帮助为CLI添加`--json`导出标志。
查看我们标记为`good first issue`的问题以开始。有关指南，请参见[CONTRIBUTING.md](CONTRIBUTING.md)。
## 📄 许可证
MIT — 有关详细信息，请参见[LICENSE](LICENSE)。由[Lalith Chandra](https://github.com/lalithbuilds)构建。
---
*如果Engram能帮助你避免向AI重复自己，请考虑给它一个⭐！*
