engrava

# Engrava > 人工智能代理的记忆数据库。 > > 图形记忆、混合搜索和篡改审计轨迹 — 只需一次 `pip install`，无需服务器，无需大语言模型。 [](https://github.com/sovantica/engrava/actions/workflows/ci.yml) [](https://pypi.org/project/engrava/) [](https://pypi.org/project/engrava/) [](https://opensource.org/licenses/MIT) **Engrava** 是一个独立的嵌入式数据库，用于人工智能代理的记忆。基于 SQLite，它提供思维 CRUD、基于边的知识图、基于嵌入的相似性搜索、全文本搜索（FTS5/BM25）和声明式扩展系统 — 所有这些都可以在一个软件包中，无需外部服务依赖。 ## 用例 - 人工智能代理的持久记忆 - 个人知识库 - 具有语义搜索的对话存储 - 具有关联链接的研究笔记 - 任何需要思维图和嵌入的应用程序 ## 快速开始 ### 安装 ```bash pip install engrava ``` 可选额外功能： ```bash pip install "engrava[vec]" # sqlite-vec 矢量搜索后端 pip install "engrava[mcp]" # MCP 服务器（engrava-mcp）适用于 Claude Desktop/Code, Cursor, … pip install "engrava[embeddings-local]" # 句子转换器嵌入（本地模型） pip install "engrava[embeddings-openai]" # OpenAI 兼容的嵌入 API pip install "engrava[embeddings-ollama]" # Ollama 本地嵌入服务器 pip install "engrava[embeddings-hf]" # HuggingFace 推理 API 嵌入 ``` 梦境/巩固和知识图谱 **无需额外** — 它们是基本安装的一部分。 ### 基本用法 存储记忆并搜索，两个调用 — 无需生成 ID，无需组装记录： ```python import asyncio import aiosqlite from engrava import SqliteEngravaCore async def main() -> None: # SqliteEngravaCore 包装了一个打开的 aiosqlite 连接。 async with aiosqlite.connect(":memory:") as conn: conn.row_factory = aiosqlite.Row store = SqliteEngravaCore(conn) await store.ensure_schema() await store.remember("Python 对人工智能代理来说非常好") await store.remember("SQLite 无需服务器") result = await store.recall("什么语言适合代理?") for thought_id, score in result.results: thought = await store.get_thought(thought_id) if thought is not None: print(f"{thought.essence} （分数：{score:.3f}）") asyncio.run(main()) ``` `remember()` 将文本存储为思维（为您生成其 ID）并返回存储的 `ThoughtRecord`；`recall()` 运行与 `search_hybrid()` 相同的混合搜索并返回排名结果。为了完全控制 — 设置优先级、思维类型、元数据或写入的认知周期 — 自己构建一个 `ThoughtRecord` 并调用 `create_thought()`。 从这里，链接思维与 [类型边](#基于边的知识图)、使用 [MindQL](#MindQL 查询语言) 查询它们，或在 [快速入门指南](docs/quickstart.md) 中运行完整的摄入 → 梦境 → 搜索之旅。 ### 配置驱动设置 ```python from engrava import SqliteEngravaCore # from_config 打开并拥有连接 — 将其用作异步上下文管理器。 async with await SqliteEngravaCore.from_config("engrava.yaml") as store: # 架构已由 from_config 应用。 thought = await store.get_thought("some-id") ``` 参见 [docs/configuration.md](docs/configuration.md) 以获取完整的 YAML 架构。 ## 升级 自动架构迁移在首次连接时运行。参见 [升级指南](docs/upgrade.md) 以获取兼容性说明、备份指南和故障排除步骤。 ## 功能 ### 思维 CRUD 创建、读取、更新和存档思维，具有完整的生命周期管理。所有模型都是冻结的 Pydantic 对象 — 变异发生在 `evolve()` 处。 ### 基于边的知识图 用类型化、加权边链接思维。边类型包括 `ASSOCIATED`、`DEPENDS_ON`、`DERIVED_FROM`、`CONSOLIDATED_FROM` （由梦境创建）和 `CONTESTED_BY`。 ### 嵌入搜索 存储思维的嵌入并执行强力余弦相似性搜索。可插拔的嵌入提供程序： | 提供程序 | 额外 | 后端 | | --- | --- | --- | | `SentenceTransformerProvider` | `embeddings-local` | 通过句子转换器的本地模型 | | `OpenAICompatibleProvider` | `embeddings-openai` | 任何 OpenAI 兼容的 API | | `OllamaProvider` | `embeddings-ollama` | 本地 Ollama 服务器 | | `HuggingFaceProvider` | `embeddings-hf` | HuggingFace 推理 API | | `CallbackProvider` | *(内置)* | 自定义可调用 | ### 全文搜索（FTS5） 带有 BM25 排名的 SQLite FTS5 虚拟表。混合搜索结合向量相似性、文本相关性和时间评分。 ### MindQL 查询语言 思维图的声明式查询语言： ``` FIND thoughts WHERE thought_type = 'OBSERVATION' AND priority = 'P1' LIMIT 10 COUNT thoughts WHERE lifecycle_status = 'ACTIVE' SELECT thought_id, essence FROM thought WHERE thought_type = 'BELIEF' ``` 可通过钩子系统扩展自定义命令。 ### 扩展系统 通过 `EngravaHooksProtocol` 插入思维生命周期： ```python from engrava import EngravaHooksProtocol, ThoughtRecord, ScoringContext class MyHooks(EngravaHooksProtocol): async def on_store(self, thought: ThoughtRecord) -> ThoughtRecord: # 在持久化前转换思维 return thought async def score_function( self, thought: ThoughtRecord, context: ScoringContext ) -> float: # 自定义相关性评分 return thought.confidence or 0.5 ``` ### 梦境 / 记忆巩固 内置的 `DreamingExtension` 用于周期性记忆巩固 — 通过可配置的信号评分、提升高价值条目并通过聚类语义相关的思维并计算质心嵌入来创建 **反射思维** （无需大语言模型）。自 0.3.0 起可用。 → 参见 [`docs/benchmarks.md`](docs/benchmarks.md) 以获取可复制的证据（综合基准套件可在 ~5 分钟内运行）。 ### 防篡改审计轨迹 可选的哈希链 **日志** 记录每次思维/边突变为 SHA-256 链接的前/后条目 — 默认关闭，通过一个配置标志启用。通过 `store.journal.get_entries(...)` 查询历史并通过 `store.journal.verify_integrity()` 验证链。 → 参见 [`docs/audit-trail.md`](docs/audit-trail.md) 以获取启用、查询、验证和安全模型（防篡改审计轨迹能提供和不能提供的保证）。 ### 多服务隔离 在单个 `EngravaManager` 下运行多个独立数据库： ```python from engrava import EngravaManager async with EngravaManager(data_dir=Path("./data")) as mgr: agent_a = await mgr.get_store("agent-a") agent_b = await mgr.get_store("agent-b") # 完全隔离的数据库 ``` ### MCP 服务器 通过 `engrava[mcp]` 附加功能将存储暴露给任何 MCP 客户端 — Claude Desktop、Claude Code、Cursor、Windsurf、VS Code 等。本地 stdio 服务器（无需 HTTP 适配器）带有读取工具、可选写入工具、可附加的 `engrava://` 资源和引导提示： ```bash pip install "engrava[mcp]" engrava-mcp # 由您的 MCP 客户端通过 stdio 启动 ``` → 参见 [`docs/guides/mcp.md`](docs/guides/mcp.md) 以获取安装、客户端配置、完整的工具/资源/提示参考和只读模式。 ## 命令行界面 ```bash engrava --db mydata.db info # 数据库统计 engrava --db mydata.db query "FIND type=OBSERVATION LIMIT 5" engrava --db mydata.db snapshot -o backup.jsonl engrava --db mydata.db restore -i backup.jsonl engrava --db mydata.db gc # 垃圾回收存档思维 engrava --db mydata.db migrate # 确保架构是最新的 engrava --db mydata.db export -o portable.json ``` `engrava info` 现在呈现与 `await store.metrics()` 相同的指标快照合约。 参见 [CLI 参考](docs/cli.md) 以获取每个命令和选项。 ## 架构 - **SQLite**，带有并发读取的 WAL 模式 - **冻结的 Pydantic 模型** — 不变域对象 - **异步优先** — 所有 I/O 操作通过 `aiosqlite` - **基于钩子的扩展** — 零猴子补丁 - **模板方法模式** — 子类 `SqliteEngravaCore` 以扩展架构 - **零外部服务** — 所有内容都在本地进程中运行 ## 文档 - [核心概念](docs/concepts.md) — 精神模型（思维、边、反射、周期等）— 从这里开始 - [双时间模型](docs/bitemporal.md) — 可选的有效时间轴：查询任意时刻的事实、`invalidate` 而不删除 - [定位](docs/positioning.md) — Engrava 适用的场景（和不适用的场景），以及比较 - [快速入门](docs/quickstart.md) — 5 分钟设置指南 - [教程](docs/tutorial.md) — 从头到尾构建一个小型笔记记忆 - [配方](docs/recipes/index.md) — 常见任务的复制粘贴片段（存储一个回合、检索上下文、TTL、重复数据删除等） - [构建记忆支持的代理](docs/guides/agent-memory.md) — 端到端的代理回合循环（摄入 → 检索 → 生成 → 巩固） - [从另一个记忆系统迁移](docs/guides/migrating-from-other-memory.md) — 概念映射、移植调用、批量导入和作用域/多租户 - [嵌入](docs/guides/embeddings.md) — 连接真正的嵌入提供程序（本地/OpenAI/Ollama/HuggingFace/自定义） - [MCP 服务器](docs/guides/mcp.md) — 将存储暴露给 MCP 客户端（Claude Desktop、Claude Code、Cursor、Windsurf、VS Code）：安装、运行、客户端配置、工具/资源/提示 - [配置](docs/configuration.md) — YAML 配置格式和选项 - [升级指南](docs/upgrade.md) — 兼容性矩阵、备份和故障排除 - [扩展](docs/extensions.md) — 编写自定义扩展和钩子 - [可观察性](docs/observability.md) — 指标快照 API - [审计轨迹](docs/audit-trail.md) — 防篡改哈希链日志（启用、查询、验证、安全模型） - [API 参考](docs/api-reference.md) — 完整的协议和类参考 - [CLI 参考](docs/cli.md) — 每个 `engrava` 命令和选项 - [词汇表](docs/glossary.md) — 每个 Engrava 术语的快速定义 - [MindQL](docs/mindql.md) — 查询语言语法和示例 - [故障排除](docs/troubleshooting.md) — 症状 → 原因 → 修复常见错误 - [FAQ](docs/faq.md) — 快速答案（LLM/密钥、嵌入可选、规模、并发性、备份等） - [性能和扩展](docs/performance.md) — 矢量后端切换、批量摄入和梦境成本（在规模上） - [数据生命周期和保留](docs/data-lifecycle.md) — 生命周期状态、TTL、存档与删除、GDPR 擦除、磁盘回收 - [部署](docs/deployment.md) — 进程模型、磁盘上的数据库文件、容器、正常关闭 - [并发性](docs/concurrency.md) — WAL 单写入者模型、忙碌超时和每服务隔离 - [备份和恢复](docs/backup-and-recovery.md) — WAL 安全备份、快照与文件复制、恢复验证 - [已知限制](docs/known-limitations.md) — 平台说明和约束 ## 开发 ```bash pip install -e ".[dev]" ruff check src/ tests/ # 校验 ruff format --check src/ tests/ # 格式校验 mypy --strict src/ # 类型校验 pytest --cov # 测试覆盖率 ``` ## 许可证 MIT — 参见 [LICENSE](LICENSE) 以获取详细信息。