内容
# 增强内存
[](https://github.com/BjornMelin/enhanced-mem-vector-rag/actions/workflows/ci.yml)
[](https://www.python.org/)
[](https://github.com/BjornMelin/enhanced-mem-vector-rag/blob/main/LICENSE)
增强内存为代理提供本地、持久的内存。它将 LangGraph 的原生 SQLite `BaseStore` 与来源、严格的生存时间（TTL）读取、确定性导出和标准输入/输出模型上下文协议（MCP）服务器相结合。
它不实现文档摄取、通用检索增强生成（RAG）、爬取、代理编排、托管应用程序接口（API）或另一个向量数据库。LangGraph 拥有存储语义，FastMCP 拥有协议行为，SQLite 拥有持久性。
## 安装
将 Python 库添加到项目中：
```bash
uv add "enhanced-mem-vector-rag @ git+https://github.com/BjornMelin/enhanced-mem-vector-rag.git@v1.0.0"
```
在隔离环境中安装 `emvr-mcp` 命令：
```bash
uv tool install "enhanced-mem-vector-rag @ git+https://github.com/BjornMelin/enhanced-mem-vector-rag.git@v1.0.0"
```
PyPI 受信任的发布正在 [问题 #11](https://github.com/BjornMelin/enhanced-mem-vector-rag/issues/11) 中跟踪。在验证该发布者之前，Git 标签仍然是规范的安装源。
对于源代码开发：
```bash
git clone https://github.com/BjornMelin/enhanced-mem-vector-rag.git
cd enhanced-mem-vector-rag
uv sync --frozen
uv run pytest
```
## Python API
使用 `MemoryService` 作为本地数据库连接的单一所有者：
```python
from pathlib import Path
from emvr import MemoryRecord, MemoryService
with MemoryService(Path("memory.sqlite3")) as memory:
record = MemoryRecord.create(
kind="preference",
content={"theme": "dark", "font_size": 15},
source="settings-import",
evidence=("user-confirmed",),
)
memory.upsert(
("users", "bjorn", "preferences"),
"editor",
record,
)
saved = memory.get(("users", "bjorn", "preferences"), "editor")
assert saved is not None
print(saved.content)
```
`memory.native` 是一个生命周期受控的 LangGraph `BaseStore`，因此可以直接将其传递给 `graph.compile(store=...)`。命名空间使用非空元组和非空标签，不包含句点或空字节。`langgraph` 根目录是保留的。命名空间列表接受 `*` 作为单段前缀或后缀通配符。
原生接口支持过滤、批量操作、TTL 和可选的 sqlite-vec 索引。精确过滤保留 JSON 类型，因此布尔值、数字、数组和对象彼此不别名。
默认情况下，语义搜索是禁用的。通过构造具有 LangGraph SQLite 索引配置和嵌入函数的服务，可以启用余弦排名。其他距离模式因固定的 SQLite 适配器无法一致地排名它们而失败。MCP 服务器保持无提供者，并支持精确查找以及命名空间和过滤搜索。
语义排名支持每个查询的前 1,000 个结果。缩小命名空间或过滤器，而不是请求更深的语义偏移。
## MCP 服务器
服务器仅使用标准输入和输出。这保持默认部署本地，并避免远程身份验证边界。
```json
{
"mcpServers": {
"enhanced-memory": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/BjornMelin/enhanced-mem-vector-rag.git@v1.0.0",
"emvr-mcp"
],
"env": {
"EMVR_DB_PATH": "/absolute/path/to/memory.sqlite3"
}
}
}
}
```
服务器暴露九种工具：
- `memory_put`、`memory_get`、`memory_search` 和 `memory_delete`
- `memory_purge_namespace` 和 `memory_list_namespaces`
- `memory_export`、`memory_sweep_expired` 和 `memory_health`
`memory_put` 是一个更新操作。每条记录都存储其来源、观察时间、可选证据和 SHA-256 内容摘要。`memory_export` 返回按命名空间和键排序的稳定 JavaScript 对象表示法行（JSON Lines）。
## 持久性契约
增强内存保留这些存储保证：
- SQLite 使用写-ahead 日志（WAL），`synchronous=NORMAL`，启用外键，忙碌超时为 5 秒。
- 过期记录在读取、搜索、命名空间列表和导出之前被清除，因此调用者不会收到过时记录。
- 托管内容必须是具有字符串键和有限数字的 JSON 对象。整数必须适合 LangGraph 的原生 64 位存储范围，从 `-2^63` 到 `2^64 - 1`。
- TTL 使用 LangGraph 的基于分钟的滑动过期语义。值必须有限、正数且不超过 5,270,400 分钟（3,660 天）。
- 向量索引是可选的。LangGraph 的 SQLite 包提供 `sqlite-vec`，但增强内存不选择嵌入提供者或模型。
- 磁盘上的模式由 `langgraph-checkpoint-sqlite` 拥有和管理。
参见 [架构](https://github.com/BjornMelin/enhanced-mem-vector-rag/blob/main/docs/architecture.md)、[支持](https://github.com/BjornMelin/enhanced-mem-vector-rag/blob/main/SUPPORT.md) 和 [安全](https://github.com/BjornMelin/enhanced-mem-vector-rag/blob/main/SECURITY.md)，了解操作边界。
## 开发
在打开拉取请求之前，运行每个本地质量门：
```bash
uv sync --frozen
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
uv build
```
## 许可证
MIT。参见 [许可证](https://github.com/BjornMelin/enhanced-mem-vector-rag/blob/main/LICENSE)。
