asuramaya/osiris

Osiris 👁️

MCP Server
DeepSeek Harness
Cordis Plugin
Claude Code
PostgreSQL
Redis
Python
License

面向 AI 智能体的持久化记忆与协调图。
Palantir 的 Object Set 本体论 × Notion 的结构化数据库 × 面向通用智能体记忆的 MCP。

Osiris 是一个自托管、与 harness 无关、以溯源为先的实体图引擎。它将转瞬即逝的智能体推理、架构裁决、未了结事项、智能体间的邮政通信以及公共实体记录，转化为持久、可查询、事件溯源的图记忆，跨越上下文窗口、压缩（compaction）以及 harness 边界。

+--------------------------------------------------+
|                 AGENT HARNESSES                  |
|   Claude Code  *  DeepSeek (DSH)  *  Cursor/AI   |
+-------------------------+------------------------+
| MCP (:8790) / HTTP
+-------------------------v------------------------+
|               OSIRIS MEMORY LAYER                |
|  Granular Retrieval  *  Palantir x Notion Algebra|
|  Evidence Taxonomy   *  Graphed Fleet Mailbox    |
|  Soul Store (Bytea)  *  Multi-Seat Coordination  |
+-------------------------+------------------------+
| Actions Waist
+-------------------------v------------------------+
|               EVENT-SOURCED KERNEL               |
|   PostgreSQL 16 (Append-Only)  *  Redis 7 (Bus)  |
+--------------------------------------------------+

🏷️ 标签与生态系统
memory · cordis · dsh · dsh-plugin · deepseek-harness · deepseek · claude-code · cursor · mcp · model-context-protocol · agentic-ai · ai · llm · knowledge-graph · provenance · palantir-ontology · notion-databases · event-sourcing · autonomous-agents · fleet-coordination

⚡ 为什么选择 Osiris？

| 维度 | 标准 LLM 智能体上下文 | Osiris 记忆图谱 |
| :--- | :--- | :--- |
| 持久性 | 会话结束、重启或上下文压缩后即丢失 | 基于 PostgreSQL 16 + Redis 的仅追加、事件溯源图谱 |
| 框架可移植性 | 被困在某个专有框架格式中 | 运行于 :8790 的通用 MCP 服务器（DSH、Claude Code、Cursor、Crush） |
| 检索成本 | 50K–100K token 的提示词倾泻，推高账单 | 细粒度 getter（get_status 约 360 字符、分页列表、限定范围搜索） |
| 真相与溯源 | 启发式字符串与幻觉式共识 | 严格的 6 层证据分类法，支持来源内取代 |
| 多智能体团队 | 孤立的会话，没有消息路由 | 图谱化邮政层（Message 对象 + 类型化的 sent_by/in_thread 链接） |
| 转录归档 | 易失的本地临时文件 | 字节级精确的 Soul Store，带确定性 SHA-256 哈希链 |

🧬 核心原语

1. 窄动作腰部
每一次写入 Osiris 都必须经过 Actions Waist（src/actions/core.py）。禁止直接写数据库。每一次变更都会产生一条不可变的 object_events 日志条目、一个供异步消费者使用的 outbox 事件，以及一条 audit_log 条目。

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

2. 证据分类法
置信度绝不是自由形式的数字。每一个事实都带有明确的溯源类别：

- SELF_DECLARED（1.00）—— 直接的第一方陈述（例如某个智能体声明自己的架构选择）。
- AUTHORITATIVE_API（0.95）—— 来自权威 API 的已验证响应（EDGAR、CourtListener、OpenSanctions）。
- DIRECT_OBSERVATION（0.90）—— 观察到的运行时遥测或执行转录事实。
- CORROBORATED（0.85）—— 来自独立观察者的多来源一致。
- CO_OCCURRENCE（0.50）—— 统计共现或启发式邻近。
- DERIVED（0.40）—— 推断出的后台回填（例如自动转录挖掘）。

3. Palantir × Notion 组合引擎
组合是可复用、可复刻的查询，表达为一个 8 操作符的封闭代数 AST（src/orchestrator/compositions.py）：
- select、traverse、collect、subtract、union、intersect、aggregate、order、take
- 函数变换：search（融合 BM25 + trigram + 语义向量）、discrepancy、who_is_this。

🚀 多框架集成

Osiris 通过 Streamable-HTTP 在 http://127.0.0.1:8790/mcp 上提供通用的 模型上下文协议（MCP） 接口。

DeepSeek Harness（DSH）
通过 dsh-plugin/ 中的 Cordis 生命周期插件实现原生零摩擦集成：
- 进程内 turn/start 自动挂载与席位绑定。
- 零子进程后台心跳状态轮询。
- 上下文压缩前的进行中 session/end-seed 图结算。

Add to ~/.dsh/profiles/web/cordis.patch.yml
plugins:
"@deepseek-ai/dsh-mcp-client":
servers:
osiris:
type: streamable-http
url: http://127.0.0.1:8790/mcp

Claude Code
统一、轻量的标准库钩子运行器（scripts/osiris_hook.py），取代 13 个旧脚本：
// Add to ~/.claude/settings.json or .mcp.json
{
"mcpServers": {
"osiris": {
"type": "streamable-http",
"url": "http://127.0.0.1:8790/mcp"
}
}
}

Cursor / Windsurf / 自定义智能体
将任何兼容 MCP 的智能体直接连接到 http://127.0.0.1:8790/mcp。

📬 图化智能体间邮政层

智能体通过类型化、异步的邮政通道进行通信，具有至少一次投递保证：
- 广播通道：send(to="") — 群组邮件投递到挂载在某个仓库上的所有智能体。
- 直接消息：send(to_agent="") — 私密的智能体对智能体私信。
- 图原生拓扑：每次派发都会在 PostgreSQL 中铸造一个一等 Message 节点，并带有类型化链接：
- sent_by -> Agent
- addressed_to -> Agent / Seat
- broadcast_to -> SoftwareProject
- replies_to -> Message
- in_thread -> Thread
- 现有技术检查：派发时自动查询知识图谱，若已存在相同的决策或实践，则提醒智能体。

🔎 高效细粒度检索

不要再把 90% 的上下文窗口花在简报上。Osiris 提供分层检索：

+-----------------------------------------------------------------------------+
|  Tier 1: Glance (~360 chars)                                                |
|  get_status() -> {you: "agent:dsh00001", project: "osiris", mail: "0 unread"}|
+-----------------------------------------------------------------------------+
|  Tier 2: Paginated Lists (~1-2KB)                                           |
|  get_thread_list(project="osiris", kind="obligation", limit=5)              |
|  get_decision_list(project="osiris", limit=5)                               |
|  get_mail()                                                                 |
+-----------------------------------------------------------------------------+
|  Tier 3: Scoped Graph Search (~2-5KB)                                       |
|  graph_search(query="advisory lock xact", project="osiris", max_depth=1)    |
|  consult_canon(query="actions waist")                                       |
+-----------------------------------------------------------------------------+
|  第 4 层：完整简报与召回（按需）                                            |
|  orient() * recall(ref="c396b0a2") * dossier(object_ref="repo:osiris")      |
+-----------------------------------------------------------------------------+

🛠️ 快速开始

1. 前置条件
- Python 3.12+（uv 包管理器）
- PostgreSQL 16+，并启用 pg_trgm 和 vector 扩展
- Redis 7+

2. 安装与数据库设置
克隆仓库
git clone https://github.com/asuramaya/osiris.git
cd osiris

安装 Python 依赖
uv sync

运行数据库迁移
DATABASE_URL=postgresql://osiris:osiris@127.0.0.1:5432/osiris uv run alembic upgrade head

初始化核心本体类型与设计规范
uv run python -m src.init

3. 启动服务
1. 启动 Osiris MCP 服务器（HTTP / JSON-RPC，端口 8790）
DATABASE_URL=postgresql://osiris:osiris@127.0.0.1:5432/osiris \
REDIS_URL=redis://127.0.0.1:6379/0 \
uv run python -m src.mcp_server

2.（可选）在端口 8011 上启动 Osiris UI 与控制台
DATABASE_URL=postgresql://osiris:osiris@127.0.0.1:5432/osiris \
uv run uvicorn src.api.app:app --port 8011

3.（可选）启动后台工作进程
DATABASE_URL=postgresql://osiris:osiris@127.0.0.1:5432/osiris \
uv run arq src.workers.arq_worker.WorkerSettings

🔄 智能体生命周期仪式

当智能体进入 Osiris 工作区时，它会遵循一个结构化的 5 步仪式：

1. mount(cwd) — 将会话接入集群；绑定到指定的 Seat 并恢复持久的谱系身份。
2. get_status() — 在 400 个字符以内快速查看身份、未读邮件和集群脉搏。
3. graph_search(query) / consult_canon(query) — 在重新推导解决方案之前，检查现有裁决和设计规范。
4. record_decision(...) / open_thread(...) — 在架构裁决、选择和未决义务出现时，将其持久化。
5. settle() — 回合结束时的机械式封存，验证所有决策、线程和 git 状态在压缩前都已持久化到图中。

📚 文档索引

- 📖 跨 Harness 规范 — 多 Harness 架构、DSH Cordis 插件和适配器协议。
- 🏗️ 系统架构 — 深入探讨 Actions Waist、事件溯源内核和模式目录。
- ⚙️ 安装与运维 — Systemd 单元、Docker Compose、Redis 配置和环境设置。
- 🚢 部署指南 — 生产运维、守护进程管理、池上限和信封限制。
- 📜 智能体仪式与记忆法则 — 宪法性记忆不变量、证据规则和上下文交接机制。
- 🗺️ 项目路线图 — 里程碑、已完成的篇章，以及正在进行的开发路线图。

⚖️ 章程与不变量

1. 绝不自动合并 Person — 身份合并始终需要经过审查把关。
2. Osiris 拥有 HANDS，且经过准入与治理 — 生命周期守护进程掌管操作性事实，绝不掌管思想。
3. 事件溯源、仅追加的内核 — 对象、断言和链接绝不进行破坏性删除；通过补偿事件进行修复。
4. Actions Waist 不变量 — 所有图变更都流经 src/actions/core.py。
5. 证据分级的摄取 — SELF_DECLARED > AUTHORITATIVE_API > DIRECT_OBSERVATION > DERIVED。
6. 膜 — 自主循环可以闭合，但绝不静默、绝不不可逆。
7. 无密钥公开采集 — 面向企业/公共数据的开放实体公地，不泄露私有凭证。
8. 公开构建 — 干净的里程碑、可验证的测试套件，以及发布前严格的密钥/PII 扫描。

📄 许可证与道德行为准则

Osiris 是自由软件，依据 GNU Affero 通用公共许可证 v3.0 授权。
AGPL-3.0 是一种网络著佐权许可证：如果你将修改后的 Osiris 作为服务运行，供他人
通过网络与之交互，你必须向这些用户提供相应的源代码。

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

以 vendor 形式置于 src/ui/static/vendor/ 和 src/api/inbox/static/ 下的第三方资源
保留其各自的上游许可证（MIT，依据每个文件中保留的头部声明）。