内容
# mcp-zip
**用于人工智能代理的压缩记忆。**
[](https://www.python.org/downloads/)
[](LICENSE)
[](https://modelcontextprotocol.io)
> **mcp-zip** 是一个 MCP 服务器，它压缩您的人工智能代理的上下文。 与其读取整个文件（数千个标记），不如只查找相关部分（数十个标记）。 就像 ZIP，但适用于代理内存。
## 问题
您的 AI 代理每次会话结束时都会忘记所有内容。 为了记住，它必须读取整个上下文文件 — 每次对话消耗数千个标记。 到一天结束时，您会达到速率限制。
## 解决方案
**mcp-zip** 将代理内存压缩到紧凑的 `.md` 文件中，针对 LLM 进行了优化。 通过 FTS5 + TF-IDF 搜索，您的代理可以在毫秒内找到相关信息，而无需读取整个文件。
## 架构
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ .md files │────▶│ .json cache │────▶│ SQLite │
│ (store) │ │ (structure)│ │ (index) │
│ git-friendly│ │ fast parsing│ │ FTS5+TF-IDF │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
▼ ▼ ▼
Humans read APIs access Agent searches
and commit programmatically instantly
```
### 工作流程
```
START SESSION:
memoria_iniciar("ferreteria")
→ Auto-archive entries >30 days
→ ✅ Project active
WRITE:
memoria_escribir("ferreteria", "bug", "Color falla", ...)
→ Save to .md (git)
→ Generate .json (cache)
→ Index in SQLite (search)
SEARCH:
memoria_buscar("ferreteria", "color detection")
→ SQLite FTS5 + TF-IDF search (~700 tokens)
→ Return only relevant entries
READ:
memoria_leer("ferreteria", "summary")
→ Read full .md (~500 tokens)
→ Only for general context
```
## 安装
```bash
pip install mcp-zip
```
## 在您的编辑器中配置
### Zed
在 `~/.config/zed/settings.json` 中添加：
```json
{
"context_servers": {
"zip": {
"command": "mcp-zip"
}
}
}
```
### Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
"mcpServers": {
"zip": {
"command": "mcp-zip"
}
}
}
```
### Cursor
在 `.cursor/mcp.json` 中添加：
```json
{
"mcpServers": {
"zip": {
"command": "mcp-zip"
}
}
}
```
### 任意 MCP 客户端
```json
{
"mcpServers": {
"zip": {
"command": "mcp-zip",
"env": {
"MEMORIA_ROOT": "~/.memoria"
}
}
}
}
```
## 工具
| 工具 | 描述 | 标记 |
| --- | --- | --- |
| `memoria_iniciar` | 创建/激活项目 + 自动存档 | ~50 |
| `memoria_escribir` | 记录条目（错误、决定、计划） | ~100 |
| `memoria_buscar` | FTS5 + TF-IDF 语义搜索 | ~700 |
| `memoria_leer` | 读取完整文件 | ~500-5000 |
| `memoria_resumen` | 状态的紧凑摘要 | ~500 |
| `memoria_listar` | 列出所有项目 | ~100 |
| `memoria_archivar` | 存档超过 30 天的条目到保险库 | ~50 |
| `memoria_importar` | 将现有的 `.md` 文件迁移到系统 | ~200 |
| `memoria_exportar` | 导出内存文件 | 可变 |
| `memoria_estadisticas` | 使用和节省标记的指标 | ~300 |
| `memoria_sincronizar` | 同步所有项目的 JSON + SQLite | ~500 |
| `memoria_exportar_zip` | 将项目导出到 `.mcp-zip` 格式 | ~200 |
| `memoria_importar_zip` | 从 `.mcp-zip` 导入项目 | ~300 |
| `memoria_listar_zip` | 列出 `.mcp-zip` 的内容 | ~100 |
## 最佳流程（节省标记）
### ❌ 差（每会话消耗 ~50,000 标记）
```
# 每次都读取所有上下文
memoria_leer("ferreteria", "errores") # 3,716 tokens
memoria_leer("ferreteria", "decisiones") # 5,901 tokens
memoria_leer("ferreteria", "implementacion") # 2,862 tokens
```
### ✅ 好（每会话消耗 ~3,500 标记）
```
# 常规摘要
memoria_resumen("ferreteria") # 500 tokens
# 特定搜索
memoria_buscar("ferreteria", "parser") # 700 tokens
memoria_buscar("ferreteria", "color") # 700 tokens
# 仅在必要时读取
memoria_leer("ferreteria", "resumen") # 500 tokens
```
**节省：每会话标记减少 93%。**
## 紧凑格式
**mcp-zip** 使用针对 AI 模型优化的 `.md` 格式：
```markdown
### bug | 2026-07-14 | 已解决
Color detection 不起作用
ctx: Pinturas Tekbond/Miura 融合
root: 步骤 8 parser FGP，result.attributes 覆盖对象
fix: result.attributes = { ...result.attributes, features }
tags: parser,fgp,colores
files: src/services/normalization/parsers/fgp.parser.ts
```
**vs 传统格式（标记多 2 倍）：**
```markdown
## [2026-07-14] Bug: Color detection 不起作用
- **上下文**：Pinturas Tekbond/Miura 融合在一起，因为无法检测颜色
- **根本原因**：在 FGP 解析器的步骤 8 中，`result.attributes = { features: ... }` 覆盖了对象
- **解决方案**：更改为 `result.attributes = { ...result.attributes, features: ... }`
- **状态**：
```
## 存档保险库
已解决的条目，超过 30 天，将在启动时自动存档：
```
~/.memoria/proyectos/ferreteria/
├── errores.md ← 活动条目
├── errores.json ← 结构化缓存
├── decisiones.md ← 活动条目
├── decisiones.json ← 结构化缓存
├── memoria.db ← FTS5 + TF-IDF 索引
└── boveda/
├── errores-2026-06.md ← 2026 年 6 月的存档
├── errores-2026-06.json ← 存档的缓存
├── decisiones-2026-06.md
└── decisiones-2026-06.json
```
## 存储存储库
| 存储 | 格式 | 用途 | 谁读取 |
| --- | --- | --- | --- |
| `.md` | 紧凑的 Markdown | Git、人类、备份 | 任何人 |
| `.json` | 结构化 JSON | 程序化访问 | Python、API |
| `.db` | SQLite FTS5 + TF-IDF | 即时搜索 | 搜索引擎 |
## 迁移
如果您已经有现有的上下文 `.md` 文件：
```bash
# 代理调用：
memoria_importar("ferreteria", "/home/user/proyectos/ferreteria/context/")
→ 📥 导入完成：5 个文件，23 个条目
→ 📄 JSON 自动同步
```
## 环境变量
| 变量 | 描述 | 默认值 |
| --- | --- | --- |
| `MEMORIA_ROOT` | 存储根目录 | `~/.memoria` |
## .mcp-zip 格式
用于导出/导入完整项目的压缩格式：
```bash
# 导出项目
memoria_exportar_zip("ferreteria")
→ 📦 ferreteria.mcp-zip (24.5 KB → 8.2 KB 压缩)
# 导入项目
memoria_importar_zip("/backup/ferreteria.mcp-zip")
→ 📥 项目 'ferreteria' 已导入（47 个条目）
# 列出内容
memoria_listar_zip("ferreteria.mcp-zip")
→ 📋 内容：
- errores.md (12 KB)
- errores.json (8 KB)
- decisiones.md (18 KB)
- ...
```
## 统计
```bash
memoria_estadisticas("ferreteria")
→ 📊 统计：
- 条目：47（23 个错误，15 个决定，9 个计划）
- 活动：31 | 存档：16
- 💰 节省：93%（46,500 标记/会话）
```
## 同步
```bash
memoria_sincronizar()
→ 🔄 同步所有项目...
- ferreteria：✅ JSON + SQLite 重建
- matucho：✅ JSON + SQLite 重建
```
## 项目统计
```
代码行数： ~2,200
测试： 35/35 ✅
依赖： 2 (fastmcp, pyyaml)
格式： .md + .json + SQLite
搜索： FTS5 + TF-IDF（无 ML）
```
## 许可证
MIT — 查看 [LICENSE](LICENSE)
---
**mcp-zip** — 压缩您的代理内存。节省标记。永不遗忘。
