Loci
/ˈloʊ.saɪ/ — Cognitive memory for AI agents
Persistent, structured, cross-session memory via MCP.
Single binary. Local-first. Zero cloud dependencies.
Install · Quickstart · Architecture · Cheatsheet · Why Loci?
______________________________________________________________________
问题
AI代理在会话之间会忘记一切。常见的解决方法——不断增长的markdown文件、平面矢量存储、对话日志——将记忆视为统一的文本块。它们失去了对检索、老化和相关性至关重要的结构。
解决方案
Loci实现了 四种记忆分类法 受认知科学启发：
| 类型 | 商店 | 示例 |
|---|---|---|
| 情节性的 | 活动、决定、会议 | *“我们周五部署了v2.3”* |
| 语义 | 事实、偏好、知识 | *“用户更喜欢Rust而不是Go”* |
| 程序性 | 工作流程、模式、序列 | *“如何运行部署管道”* |
| 实体 | 人员、项目、系统 | *“约翰·史密斯是谁”* |
每种类型都有不同的范围、衰减率和生命周期行为——情景记忆逐渐消失并压缩为摘要，语义知识随着使用而持续存在并增强，程序记忆通过替代进行版本转换，实体形成关系图。
如需更深入地了解设计理念，请参阅 为什么是Loci？
______________________________________________________________________
特性
- 混合搜索 --向量相似度（KNN）+关键字（BM25），与互易秩融合合并
- 本地嵌入 -通过ONNX运行时的全MiniLM-L6-v2，每次查询约5ms，无需API密钥
- 重复数据删除门 --几乎重复的存储器（余弦>0.92）被合并，而不是累积
- 信心衰退 --未使用的记忆会褪色；访问的内存得到了增强
- 自动压实 --旧的情景记忆总结成每周摘要
- 渐进式披露 --摘要首次检索尊重令牌预算
- 实体图 --用于实体间关系的轻量级三重存储
- 单文件存储 --SQLite+FTS5+SQLite-vec，全部在
~/.loci/memory.db - 双重运输 --stdio用于本地客户端，Streamable HTTP（SSE）用于远程部署
- MCP协议 --可与Claude Code、Cowork、Agent SDK和任何兼容MCP的客户端配合使用
______________________________________________________________________
安装
cargo install loci-mcp或来源：
cargo install --path .下载嵌入模型（~30MB，一次性）：
loci model download______________________________________________________________________
快速入门
1.连接到克劳德代码
claude mcp add loci -- loci serve或者手动添加到您的 .mcp.json （项目或全球 ~/.claude/.mcp.json):
{
"mcpServers": {
"loci": {
"command": "loci",
"args": ["serve"],
"env": {
"LOCI_GROUP": "${workspaceFolder}"
}
}
}
}2.教你的代理人使用记忆
添加到您的 CLAUDE.md:
## Memory
You have access to persistent memory via `loci` MCP tools. Use it proactively.
### When to store:
- User states a preference → store_memory type: semantic
- You learn about a person/project/system → store_memory type: entity
- You learn a multi-step workflow → store_memory type: procedural
- A significant event occurs → store_memory type: episodic
### When to recall:
- At session start: recall_memory(query: "", summary_only: true)
- Before making assumptions about user preferences
- When the user references something from a past session
### Updating facts (conflict resolution):
When a fact changes (e.g., preference, status, version), supersede the old memory:
1. recall_memory(query: "user theme preference", summary_only: true)
2. store_memory(content: "User prefers light mode", type: "semantic", supersedes: "
")
Do NOT store contradictory facts side-by-side. Always supersede the outdated one.
### Progressive disclosure:
1. recall_memory(query: "...", summary_only: true, max_results: 10)
2. Scan summaries, identify relevant IDs
3. recall_memory(ids: ["relevant_id_1", "relevant_id_2"])3.验证
loci stats
loci search "deployment workflow"有关完整的设置指南，请参阅 入门指南.
______________________________________________________________________
MCP工具
| 工具 | 说明 |
|---|---|
store_memory | 存储新内存（具有自动重复数据删除功能） |
recall_memory | 按查询混合搜索或按ID水合 |
forget_memory | 软删除或硬删除内存 |
memory_stats | 按类型、范围、数据库大小、时间戳计数 |
memory_inspect | 完整细节：内容、元数据、关系、审计日志 |
store_relation | 用谓词链接两个实体记忆 |
有关完整的参数参考，请参阅 备忘单.
______________________________________________________________________
命令行界面
loci serve [--transport stdio|sse] Start MCP server
loci model download Pre-download embedding model
loci model status Check model download & config status
loci search Hybrid search from terminal
loci stats [--group GROUP] Memory statistics
loci inspect Full memory details
loci export > backup.json Export all memories (JSON)
loci import backup.json Import memories (re-embeds)
loci compact Run maintenance (decay + compact + promote)
loci cleanup [--dry-run] Preview or delete stale memories
loci doctor Database health check + diagnostics
loci re-embed Re-embed all memories (after model change)
loci reset Delete all memories______________________________________________________________________
运作原理
MCP Client (Claude Code, etc.)
↕ stdio or SSE (JSON-RPC)
Loci MCP Server
├─ 6 MCP Tools
├─ Memory Engine
│ ├─ Write: embed → dedup → store → FTS sync → vec insert → audit
│ └─ Read: embed → KNN + BM25 → RRF merge → filter → token budget
├─ Maintenance: decay → compact → promote → cleanup
├─ Storage: SQLite + FTS5 + sqlite-vec (single file)
└─ Embeddings: ONNX Runtime + all-MiniLM-L6-v2 (local, 384-dim)有关带图表的完整架构，请参阅 建筑.
______________________________________________________________________
配置
可选。创建 ~/.loci/config.toml --所有值都有合理的默认值：
[retrieval]
default_max_results = 5
recall_token_budget = 4000
rrf_k = 60
dedup_threshold = 0.92
[maintenance]
episodic_decay_factor = 0.95
semantic_decay_factor = 0.99
compaction_age_days = 30
cleanup_confidence_floor = 0.05
cleanup_no_access_days = 90环境变量覆盖：
| 变量 | 覆盖 |
|---|---|
LOCI_DB | 数据库路径 |
LOCI_GROUP | 默认内存组 |
LOCI_LOG_LEVEL | 日志级别 |
______________________________________________________________________
文档
______________________________________________________________________
名字
命名为 *位置记忆法* --一种古老的记忆技术，通过将信息与精神宫殿中的特定位置相关联来存储信息。Loci为你的人工智能代理构建了一个结构化的宫殿：发生了什么的情景室，已知的语义大厅，事情如何运作的程序走廊，以及重要的人和事的实体室。
______________________________________________________________________
许可证
麻省理工学院