奥西里斯记忆图 asuramaya/osiris

Osiris

MCP Server
Claude Code
PostgreSQL
Redis
Python
License

Osiris 是一个面向 AI 智能体的自托管记忆与协调图。它将推理、决策、未了结事项、智能体间消息以及公共实体记录转化为持久、可查询的图记忆，使其能够跨越上下文窗口、压缩和重启而存续。它作为一个由 Postgres 支撑的服务运行，可通过模型上下文协议从任何执行框架访问。

为什么需要它

智能体自身的上下文窗口并不是记忆：它在每次压缩、每个新会话、每次执行框架重启时都会重置。Osiris 为智能体提供了一个地方来记录事实和决策，并附上是谁说的以及他们的置信度，同时提供一种低成本的方式，只读回当下所需的内容，而不是完整的历史转储。它是一个 Postgres 数据库加上一层薄薄的写入层，而不是一个新的智能体框架：任何 MCP 客户端，或终端前的人类，都读写同一张图。

核心理念

Actions Waist。 每一次写入 Osiris 都经过同一层（src/actions/core.py）。不允许直接写数据库。每一次变更都会追加一个事件，绝不覆盖或删除：

async with actions.atomic():
oid = await actions.create_or_find_object("SoftwareProject", "repo:osiris", actor="agent:example")
await actions.assert_property(oid, "status", "active", source_id="agent:example", observed_at=now, confidence=1.0)
await actions.create_link(from_id=decision_id, to_id=oid, type_="in_repo", source_id="agent:example", observed_at=now, confidence=1.0)

分级证据。 一个事实的置信度绝不是凭空取来的数字；它来自该事实是如何获得的（src/parsers/evidence.py），从最强到最弱依次为：

- Corroborated（已确证）：两个或更多独立来源一致（计算得出，绝不直接指定）
- Self-declared（自我声明）：第一方陈述，例如智能体记录自己的决策
- Authoritative API（权威 API）：来自规范外部来源的经过验证的响应
- Direct observation（直接观察）：从真实运行时记录或执行轨迹中读取
- Derived（派生）：由自动化回填过程推断得出
- Co-occurrence（共现）：一种弱的统计邻近信号，属于最低层级组合。 组合是图上一种已保存、可派生的查询，由一小组算子（select、traverse、collect、aggregate 等）构建而成，而非使用原始 SQL。完整的词汇表及其所依据的设计，请参见 docs/COMPOSER.md。

安装

前置条件：Python 3.12+（使用 uv 管理）、带 pg_trgm 的 PostgreSQL 16+，以及 Redis 7+。

git clone https://github.com/asuramaya/osiris.git
cd osiris
uv sync

Point at your database and apply migrations
export DATABASE_URL="postgresql://osiris:osiris@127.0.0.1:5432/osiris"
uv run alembic upgrade head
uv run python -m src.init # seed catalog types and design canon

Start the three services
OSIRIS_MCP_TRANSPORT=streamable-http uv run python -m src.mcp_server # MCP, :8790
uv run arq src.workers.arq_worker.WorkerSettings # background worker
uv run uvicorn --factory src.api.app:create_app --port 8011 # console (optional)

关于 systemd 单元、Docker Compose 以及所有选项的完整说明，请参见 docs/INSTALL.md。

首次运行

加密密钥会自行设置。 存储的会话记录在静态时是加密的。
osiris deploy 会在密钥和备份密码缺失时创建它们，然后重启服务，并且有一个后台任务会加密任何较旧的明文行。唯一需要你参与的一步是注册一个安全密钥作为你的恢复路径（一次触摸）：

osiris soul-key enroll-recovery # enroll a FIDO2 security key as your recovery path
osiris soul-key verify-recovery # optional: prove it works, changes nothing

设置异地备份。 一个单独的凭据保护备份仓库：

osiris restic-key init
osiris backup-settings write --offload-add nas --offload-kind restic \
--offload-target "sftp:nas.local:/backups/osiris" --offload-schedule "*:0/15" \
--because "first-run offload target"
osiris offload-runner tick # run one offload by hand to confirm it reaches the target
osiris soul-key restore-drill # prove the backup actually restores, not just that it accepted one

控制台的“设置”面板（可从标题栏的齿轮图标或命令面板打开）是这两者的持续仪表盘。完整细节：docs/KEYS.md 和 docs/BACKUP.md。

启动你的第一个项目。 两个值得记住的命令：

osiris new # a self-managed seat: its own workspace, its own project
osiris launch # give it a live process

osiris new 不向任何人负责，也不需要现有仓库。若要将现有项目自己的 markdown 笔记引入图中，请改用 osiris bootstrap 。运行 osiris --help 可查看按你要做的事情分组的完整命令列表。

控制台与 CLI

控制台是位于 http://127.0.0.1:8011/ui/ 的浏览器 UI：浏览图、阅读和从一个地方发送邮件、运行已保存的组合、管理设置、密钥和备份。

CLI（osiris）和 MCP 工具接口是操作 Osiris 的两种受支持方式：CLI 供终端前的人类使用，MCP 工具供智能体使用。每个读取命令都接受 --json 以便脚本化使用。完整参考见 docs/CLI.md。

文档

- docs/INSTALL.md：完整安装与 systemd 设置
- docs/CLI.md：osiris 命令参考
- docs/KEYS.md：加密密钥与备份凭据
- docs/BACKUP.md：备份计划与异地卸载目标
- docs/DEPLOY.md：生产部署与守护进程管理
- docs/CROSS_HARNESS.md：连接其他智能体框架
- docs/COMPOSER.md：组合查询语言
- docs/RITUAL.md：智能体读写约定
- ARCHITECTURE.md：系统设计
- docs/REFERENCE.md：数据模型，由代码生成
- ROADMAP.md：已构建的内容与下一步计划

章程

本系统所坚守的一组简短不变式：

1. 绝不自动合并 Person。 身份合并始终由人类审核。
2. 每次写入都经过 Actions Waist。 不允许直接写数据库。
3. 仅追加。 事实和链接永不删除；更正是新事件。
4. 证据是分级的，绝不假设。 见上文核心思想。
5. 膜。 自动化流程可以闭环，但绝不静默，也绝不可逆。
6. 无密钥公开采集。 公开实体数据的采集不会泄露私有凭据。
7. 公开构建。 干净的里程碑、真实的测试，以及在任何内容发布前进行密钥/PII 扫描。

许可证

Osiris 是自由软件，采用 GNU Affero General Public License v3.0 许可。AGPL-3.0 是一种网络著佐权许可证：如果你将修改后的 Osiris 作为服务运行，供其他人通过网络使用，你必须向他们提供相应的源代码。

关于负责任使用和无密钥公开实体采集的指南，请参见 RESPONSIBLE_USE.md。

src/ui/static/vendor/ 和 src/api/inbox/static/ 下引入的第三方资源保留其各自的上游许可证（MIT，依据每个文件中保留的头部信息）。