使用说明
召回
无RAG的持久AI内存 --四层检索，仅将LLM代理作为最后手段，由SQLite FTS5、嵌入式图形数据库和本地markdown库支持。
提供AI助手的MCP（模型上下文协议）服务器——Claude Desktop、LM Studio、ChatGPT-- 持久结构化存储器 由SQLite+可选图形数据库支持。LLM代理是第4层，而不是默认路径——大多数查询通过全文搜索在毫秒内解析。
快速入门（个人，无GPU）
pip install recall
# Point Recall at a directory of markdown files
export RECALL_VAULT_PATH=~/notes
export RECALL_LLM_PROVIDER=openrouter
export OPENROUTER_API_KEY=your_key_here
# Start the MCP server (add to Claude Desktop's mcp.json)
recall serve
添加到克劳德桌面 mcp.json:
{
"mcpServers": {
"recall": {
"command": "recall",
"args": ["serve"]
}
}
}
快速入门（使用Docker生产）
# Clone and configure
git clone https://github.com/firstbatchxyz/mem-agent-mcp
cp .env.example .env
# Edit .env: set RECALL_VAULT_PATH, RECALL_LLM_PROVIDER, API keys
# MCP server only (stdio, for Claude Desktop)
docker compose up recall-mcp
# MCP server + HTTP dashboard
docker compose --profile worker up
# Dashboard at http://localhost:37777
架构：四层检索
每个查询都会按顺序遍历层，当找到足够的结果时会短路。第1-3级从不叫LLM。
Query
│
├─ Tier 1: SQLite FTS5 full-text search ~1ms always available
│ porter tokenizer, WAL mode
│
├─ Tier 2: Kuzu embedded graph expansion ~5ms optional (install kuzu)
│ BFS traversal via [[wikilink]] edges
│
├─ Tier 3: ChromaDB vector similarity ~50ms optional (RECALL_VECTOR=true)
│ sentence-transformer embeddings
│
└─ Tier 4: LLM agent fallback ~5-30s always available
navigates vault via Python sandbox
短路规则：如果1级返回≥ min_results （默认值3），完全跳过第2-4层。不可用的层将被跳过，并显示警告日志——没有出现错误。
MCP工具参考
| 工具 | 参数 | 返回 | 注释 |
|---|---|---|---|
use_memory_agent |
query: str |
格式化答案 | 向后兼容。通过所有4层的路线；只有当第1-3级不足时，才会退回到完全代理 |
recall_hybrid |
query: str, tier_limit: int = 4 |
JSON格式 obs_ids, source_tier, latency_ms |
首选程序化使用。令牌高效——首先返回ID |
get_observations |
ids: list[int] |
JSON观察字典数组 | 获取特定ID的完整内容 |
get_timeline |
obs_id: int, window: int = 5 |
按时间顺序排列的JSON观察数组 | 特定观察的上下文 |
渐进式披露模式
# 1. Search — cheap, returns IDs only
result = await recall_hybrid("Alice's project status", tier_limit=2)
# {"obs_ids": [42, 17, 88], "source_tier": 1, "latency_ms": 2.1}
# 2. Fetch — only for IDs you actually need
obs = await get_observations([42, 17])
# [{"id": 42, "content": "...", "tier_used": 1}, ...]
# 3. Timeline — context around interesting observations
ctx = await get_timeline(42, window=3)
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
RECALL_LLM_PROVIDER |
openrouter |
openrouter |
RECALL_LLM_MODEL |
提供程序默认值 | 模型字符串（例如。 openai/gpt-4o-mini, llama3) |
RECALL_DB_PATH |
~/.recall/recall.db |
SQLite数据库路径 |
RECALL_VAULT_PATH |
.memory_path file |
Markdown vault目录 |
RECALL_VECTOR |
false |
设置 true 启用ChromaDB层 |
RECALL_API_KEY |
（无） | HTTP API身份验证的承载令牌（如果未设置，则禁用） |
RECALL_RATE_LIMIT |
60 |
请求/分钟限制 |
RECALL_WORKER_PORT |
37777 |
HTTP仪表板端口 |
RECALL_COMPRESS_EVERY |
50 |
LLM压缩前的观察结果 |
OPENROUTER_API_KEY |
（openrouter需要） | OpenRouter API密钥 |
ANTHROPIC_API_KEY |
（克劳德需要） | 无烟煤API键 |
OLLAMA_HOST |
http://localhost:11434 |
Ollama服务器URL |
VLLM_HOST / VLLM_PORT |
localhost / 8000 |
vLLM服务器地址 |
LMSTUDIO_HOST |
http://localhost:1234 |
LM Studio服务器URL |
连接器指南
使用一个命令将外部数据导入vault：
# ChatGPT export (Settings → Data controls → Export data → .zip)
recall connect chatgpt ~/Downloads/chatgpt_export.zip
# Notion workspace export (.zip)
recall connect notion ~/Downloads/notion_export.zip
# Nuclino workspace export (.zip)
recall connect nuclino ~/Downloads/nuclino_export.zip
# GitHub repositories (live via API)
recall connect github owner/repo1,owner/repo2 --token ghp_xxx
# Google Docs (OAuth, opens browser)
recall connect google_docs "My Doc Name"
所有连接器都会将标记写入vault，然后自动将文件索引到SQLite+图形中。私人内容已打包 <private>...</private> 在索引之前，标签会被剥离。
CLI 参考
recall serve # Start MCP server (stdio transport, for Claude Desktop)
recall serve --worker # Start MCP server + HTTP dashboard on :37777
recall chat # Interactive terminal REPL (no client required)
recall backup # Create timestamped .tar.gz (vault + SQLite)
recall backup --output /path/to/archive.tar.gz
recall restore <archive.tar.gz>
recall connect <type> <source> [--token TOKEN] [--max-items N]
HTTP仪表板（可选）
从...开始 recall serve --worker 或 docker compose --profile worker up.
| 端点 | 方法 | 描述 |
|---|---|---|
/health |
得到 | {"status":"ok","db":true,"graph":false,"vector":false} |
/sessions |
GET | 带摘要的分页会话列表 |
/observations |
GET | 按会话/日期/类型筛选 |
/search |
职位 | {"query": "...", "tier_limit": 4} |
/index/rebuild |
POST | 重新索引整个保险库 |
/backup |
GET | 将vault+DB作为流传输 .tar.gz |
/stats |
得到 | {obs_count, entity_count, session_count, db_size_mb} |
认证： Authorization: Bearer <RECALL_API_KEY>。未设置env var时禁用。
隐私
将敏感内容包裹起来 <private>...</private> 标签。在写入任何存储层（SQLite、Kuzu、ChromaDB）之前，它都会被剥离。内容只会传递到代理沙盒——它永远不会持久。
# Meeting Notes
Alice discussed the roadmap.
<private>Budget: $2.4M approved for Q3</private>
Next steps: ship v2 by June.
运行测试
uv run pytest tests/ -v # all tests
uv run pytest tests/unit/ -v # unit only (fast, no network)
uv run pytest tests/integration/ -v # integration (real storage)
uv run pytest tests/ --cov=recall --cov-report=term-missing # with coverage
覆盖门：60%（CI强制）。如果未安装软件包，则会自动跳过Kuzu和Anthropic测试。
许可证
Apache 2.0——请参阅 许可证.
