时序上下文图 melandlabs/opencontext

OpenContext

你的智能体忘了自己为什么做决定。OpenContext 解决这个问题。

_面向 AI 智能体的上下文层 —— 时序上下文图、记忆 API、自演化循环，全在一个依赖里。_

上下文是缺失的那一层。 检索回答的是_发生了什么_。OpenContext 回答的是_发生过的事如何变成现在这样_。

不同于只做检索的记忆库， OpenContext 保留_为什么_ —— 时序时间线、信念修正、来源追溯。

English · 简体中文

⭐ 如果你觉得 opencontext 有用，欢迎在 GitHub 上给我们点个 star！ 这能让更多人发现这个项目，也是我们继续做下去的动力。🙏

OpenContext 是什么？

OpenContext 是智能体上下文运行时，位于智能体应用的下层 —— 也是你在上面搭建自己智能体的底座。
它不是 UI，不是聊天界面，也不是模型服务商 ——它是把让智能体真正有用的那些东西粘起来的胶水：持久记忆、检索、上下文修正、多平台连接、定时感知，以及确定性的循环引擎，全都藏在一个依赖后面。

→ 阅读 docs/architecture.md，了解完整的数据模型、一条事实的生命周期，以及传输层接口地图。

适合谁用？

OpenContext 适合需要把上下文当作工程来做的团队 —— 也就是说，这些团队的日常工作正好撞上 OpenContext 当初要解决的问题。下面每一条都点出痛点，以及 OpenContext 怎么应对：

- 软件工程团队。 决策散落在 GitHub PR、Linear 工单、Slack 讨论串和 Notion 文档里 —— 跨人、跨工具、跨季度。新同事问「我们当初为什么选 X？」，没人答得上来。OpenContext 的时序图给每条事实都存了 valid_from / valid_until，所以「上个季度我们相信的是什么？」是一个真实可查、可引用的查询 —— 不是靠猜。
- 效率 / 生产力工程团队。 这些人给公司其他部门做内部自动化。他们不想要又一个 SaaS —— 他们想要一个能直接塞进命令行、MCP 服务器或守护进程的运行时。OpenContext 以库为先，确定性的 Loop 引擎只在真有活干的时候才调用 LLM，所以它不会变成一个烧 token 的常开循环。
- 办公助手类产品。 助手跑在 Telegram、iMessage、WhatsApp、飞书等平台里。同一套智能体代码，跨渠道共享同一份上下文。IntegrationRecord 把凭据、限流和重连逻辑藏起来，而 platform + messageId 天然就是个人数据与工作数据的审计线索。
- 金融交易团队。 每一笔订单、每一次调仓、每一个风控决策都要可追溯、可审计。时序图加上只追加的更正，意味着「4 月的策略是什么？」是一个可查询的事实，而不是埋在角落里的猜测——这条线索也符合 MiFID II / SEC 的留存规则。
- 法律、医疗等受审计领域。 律所、医院以及类似团队，每一个判断都需要逐事实的来源追溯、只追加的更正，以及可导出的合规证据。
- 多智能体与自主工作流的作者。 需要按计划、确定性地唤醒，而不是一路 LLM 循环到底。packages/loop 提供的正是这种分离。

功能

| | 能力 | 作用 |
| 🧠 | 时序上下文图 | 一张有向无环图，每个事实都带 valid_from / valid_until。取代、矛盾、合并都是一等边——更正是只追加的，不破坏原有数据。 |
| 🔌 | 平台集成网格 | 在 Gmail、Slack、Telegram、Linear、Jira、iMessage、飞书、微信等平台之间，统一成一种 IntegrationRecord 结构——凭据轮换、限流处理、重连逻辑都藏在适配器后面。 |
| ⏰ | 确定性循环引擎 | 调度器先醒来，判断有没有真正的工作，确认之后才调用智能体运行时。LLM 调用不是基础，而是最后一步。 |
| 🔍 | 检索原语 | 分块、嵌入、解析器（PDF/ZIP/文本）、sqlite-vec + pgvector + Chroma 适配器。混用后端，不用重写召回流水线。 |
| 🤖 | 智能体运行时 | AI SDK 封装、沙箱服务商（native / Claude / Vercel）、MCP 服务器、记忆整合任务、图像 + 音频生成。 |
| 🪶 | 库优先 API | 用 pnpm add @melandlabs/opencontext 安装一次，就能拿到契约、记忆存储、检索原语、循环引擎和智能体运行时。 |
| 🛡️ | 审计 + 加密存储 | 结构化审计日志写入 ~/.opencontext/logs/audit.jsonl，密钥用 Fernet 对称加密，对外调用有 URL 允许列表/阻止列表。 |

基准测试

第三方记忆与长上下文召回基准（数据截至 2026-08）：

| 基准 | 得分 | 衡量内容 |
| LongMemEval-S | 97.6% | 跨长会话的长期记忆召回 |
| LoCoMo-V2 | 97.4% | 长多模态对话上的问答 |
| BEAM @ 10M | 67.0% | 10M token 上下文窗口下的事实召回 |
上方分数是 opencontext 自评，跑在公开数据集上，由我们自己的 harness 在 benchmark/ 下生成。它们不是 Agent Memory Leaderboard（AML）的结果 —— AML 在自己的平台上，用私有精调数据集评测。等我们的托管提交跑完，官方 AML 分数会出现在排行榜卡片上；提交内容见 benchmark/aml-local/。

快速开始

把 opencontext 接入项目有好几种方式。挑一种适合你正在做的东西。

1. 把运行时嵌入你自己的应用

pnpm add @melandlabs/opencontext

30 秒上手 memory API：

import { createMemoryStore, getRawMessageManager } from "@melandlabs/opencontext";

// The store defaults to SQLite at MEMORY_STORE_DB_PATH (./memory.db by
// default). Each call returns an awaitable handle.
const store = await createMemoryStore();
const messages = await getRawMessageManager();

// A message is one fact: a single piece of content attributed to a user.
// messageId makes the call idempotent across re-ingest.
const now = Date.now();
await messages.storeMessages([
{
messageId: "msg-1",
userId: "u-42",
content: "User prefers dark mode in all tools",
platform: "test",
botId: "bot-1",
timestamp: now,
createdAt: now,
},
]);

// Unified search fans out to memory + insights + knowledge. Sources you
// haven't wired up just emit a warning — fine for a single-backend deploy. const hits = await store.search({ userId: "u-42", query: "What does the user prefer?", limit: 5, }); // hits.count — number of results // hits.sources — which sub-indexes were actually consulted // hits.warnings — per-source degradation (e.g. missing embedder)

2. 用命令行管理记忆

直接在命令行里写入和查询记忆。add 把单条原始消息写进当前 manager，不走 LLM 往返；search 在 memory、insights、knowledge 上做统一读取。

pnpm add -g @melandlabs/opencontext # puts the opencontext bin on PATH

Write a fact (auto-fills messageId, platform="cli", timestamp=now)
opencontext add --text "Rust achieves memory safety without GC"

Write with full provenance for later consolidation
opencontext add \
--text "Discussed Q4 roadmap with the team" \
--source "meeting://2026-08-20" --kind experience \
--tag topic=roadmap --tag team=eng

Plain hybrid search (RRF across memory + insights + knowledge)
opencontext search --query "memory safety" --k 5

Inspect what would have been sent to the LLM, no synthesis call
opencontext search --query "what did we chat about last weekend" --context-only

Script-friendly JSON
opencontext search --query "x" --json | jq '.results[].id'

add 接受 --user（默认 "default"）、--bot（默认 "default"）、--platform、--channel、--person、--source、--kind、--at、可重复的 --tag key=value。search 接受 --mode {auto|lex|sem}、--k、--threshold，可重复的 --bot / --kind、--since / --until，以及 --explain，用来在命中结果旁展示推理过程和警告。

运行 opencontext <command> --help 查看完整参数列表。完整参数参考和示例见入门教程。

3. 从 npm 运行 HTTP 守护进程

pnpm add -g @melandlabs/opencontext # puts the opencontext bin on PATH
opencontext http \
--embedding-provider local \
--memory-backend sqlite-vec \
--host 127.0.0.1 --port 7421
Or, without a global install, via npx:
npx -y @melandlabs/opencontext http \
--embedding-provider local --memory-backend sqlite-vec
curl http://127.0.0.1:7421/health

4. 把 MCP 服务器接入 Claude Desktop / Cursor

opencontext mcp \
--embedding-provider local \
--memory-backend sqlite-vec

5. 配合 DeepSeek Harness（DSH）使用

OpenContext 提供 DSH 插件，让任何 DSH 智能体都能拥有持久记忆和检索增强上下文：

Install the plugin from npm
dsh plugin --profile web add dsh-opencontext

Confirm it's mounted
dsh --profile web --dump-config | grep dsh-opencontext
... should contain id: dsh-opencontext

Start DSH web and verify
dsh web
Visit http://127.0.0.1:3080/plugins and confirm dsh-opencontext shows "Enabled"

插件暴露 16 个 oc_* 工具（例如 oc_search、oc_remember、oc_memory_list），并自动完成以下操作：
- 每轮运行召回瀑布，注入相关的历史上下文
- 把用户消息捕获进持久记忆
- 在自然断点处总结会话（需主动开启）

配置选项和完整工具参考见 plugins/dsh-opencontext/README.md。

6. 诊断安装

opencontext doctor # human-readable health checks
opencontext doctor --json # CI-friendly { ok, exit, results } envelope
opencontext doctor --section memory-store

doctor 只读，安装健康时退出码为 0。它扫描九个部分（runtime、filesystem、loop、memory-store、embedding、policies、audit、security、integrations），并逐项报告 pass / warn / fail。v1 不提供自动修复。

下一步：教程 —— 入门、用户指南、开发者指南、高级模式与最佳实践

示例

examples/ 工作区为每个能力领域都提供了一个可运行的示例。克隆、安装并运行：

git clone https://github.com/melandlabs/opencontext.git
cd opencontext/examples
pnpm install
pnpm test

完整演练见 examples/README.md。

它有何不同

OpenContext 不是记忆库，也不是向量数据库。它是运行时底座 —— @melandlabs/opencontext 包打包了契约、记忆存储、检索原语、循环引擎，以及智能体运行时，全都收进一个依赖里。

| 对比对象 | opencontext 多出来的东西 |
| 扁平向量数据库（Pinecone、Weaviate、Qdrant） | 时序图——事实带 valid_from / valid_until，会被取代，而不只是做相似度匹配 |
| 上下文 / 记忆库 | 运行时，不是库——HTTP 守护进程、MCP 服务器、命令行，外加集成网格和循环引擎 |
| 自己接智能体循环 | 可拆分的 Loop 引擎，负责调度何时唤醒智能体，而不是一路往下都是 LLM 循环 |
| 为了拿集成才嵌入 opencontext | 单包安装——一次 pnpm add 拿到全部能力，用不着 React / Next / Tauri |

架构

┌────────────────────────────┐
│ Host application │ ← your UI, CLI, or daemon
│ (a reference app, │
│ or your own embedder) │
└─────────────┬──────────────┘
│
┌────────────────────────┴────────────────────────┐
│ @melandlabs/opencontext │
│ contracts · memory · rag · loop · agent │ └────────────────────────┬────────────────────────┘ │ ┌─────────────────────────────┴─────────────────────────────┐ │ Storage backends │ │ sqlite-vec · postgres · indexeddb · chroma · pgvector │ └─────────────────────────────┬─────────────────────────────┘ │ ┌─────────────────────────────┴─────────────────────────────┐ │ Integrations mesh (gmail, slack, …) │ └───────────────────────────────────────────────────────────┘

完整的数据流图、传输层接口和存储后端都在 docs/architecture.md。

文档

教程（从这里开始）

- docs/tutorials/README.md — 教程索引与学习路径
- docs/tutorials/00-getting-started.md — 5 分钟跑起来
- docs/tutorials/01-user-guide.md — 搞懂四个动词和时序记忆
- docs/tutorials/02-developer-guide.md — 把 OpenContext 集成进你的应用
- docs/tutorials/03-advanced-usage.md — 生产环境模式与高级功能
- docs/tutorials/04-best-practices.md — 技巧与常见坑
- docs/tutorials/use-cases/README.md — 真实用例：个人助理、客服智能体、研究追踪

架构与设计

- docs/architecture.md — 数据模型、生命周期、数据面与控制面
- docs/philosophy.md — 为什么是这个形态
- 每个包的 README.md — API 接口、示例、迁移说明

贡献

见 CONTRIBUTING.md。

许可

Apache-2.0。© 2026 Meland Labs。