melandlabs/opencontext

OpenContext

你的智能体会忘记它为何做出决策。OpenContext 解决了这个问题。

_AI 智能体的上下文层——一个依赖项中集成了时序上下文图、记忆 API 和自我演化循环。_

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

不同于只做检索的记忆库， OpenContext 保留了_原因_——时序时间线、信念修正和溯源。

English · 简体中文

License
npm version
Discord

⭐ 如果你觉得 opencontext 有用，请考虑在 GitHub 上给我们点个星！ 这能帮助更多人发现这个项目，也激励我们持续构建。🙏

GitHub Repo stars

什么是 OpenContext？

OpenContext 是位于智能体应用之下的智能体上下文运行时——也是你在其上构建自己智能体的基础。
它不是一个 UI、一个聊天界面或一个模型提供商——
它是让智能体变得有用的各个部分之间的粘合剂：持久化
记忆、检索、上下文修正、多平台连接、
定时感知，以及一个确定性的循环引擎，全部集成在一个依赖项之后。

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

它适合谁？

OpenContext 适合需要工程化其上下文的团队——也就是说，那些日常工作直接撞上 OpenContext 旨在解决的问题的团队。每一条都阐明了痛点以及 OpenContext 如何应对：

- 软件工程团队。 决策散落在 GitHub PR、Linear 工单、Slack 讨论串和 Notion 文档中——跨越人员、工具和季度。新员工问“我们为什么选了 X？”却没人能回答。OpenContext 的时序图将每个事实与 valid_from / valid_until 一起存储，因此“上个季度我们相信什么？”是一个真实的、可引用的查询——而不是猜测。
- 效率 / 生产力工程团队。 那些为公司其他部门构建内部自动化的人。他们不想要又一个 SaaS——他们想要一个可以放进 CLI、MCP 服务器或守护进程的运行时。OpenContext 以库为先，确定性的 Loop 引擎只在有实际工作时才调用 LLM，因此它不会变成一个烧 token 的常开循环。
- 办公助理产品。 驻留在 Telegram、iMessage、WhatsApp、Lark/飞书等平台内的助理。相同的 agent 代码，跨渠道共享相同的上下文。IntegrationRecord 隐藏了凭据、速率限制和重连逻辑，而 platform + messageId 则是个人和工作数据的天然审计线索。
- 金融交易团队。 每一笔订单、再平衡和风险决策都需要可追踪、可审计。时序图加上仅追加的更正意味着“四月份的策略是什么？”是一个可查询的事实，而不是被埋没的猜测——而且这条线索符合 MiFID II / SEC 的留存规则。
- 法律、医疗及其他受审计领域。 律师事务所、医院及类似团队，其中每一项判断都需要逐事实的来源追溯、仅追加的更正以及可导出的合规证据。
- 多 agent 和自主工作流作者。 需要的是按计划、确定性的唤醒，而不是一路到底的 LLM 循环。packages/loop 正是提供了这种分离。

功能特性

|     | 能力                                                                      | 作用                                                                                                                                                                                                                                                                                                                                                                                              |
| --- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 🧠  | 时序上下文图 | 一个有向无环图，其中每个事实都有 valid_from / valid_until。取代、矛盾和合并都是一等边——更正是仅追加的，而非破坏性的。                                                                                                                                                                                                                |
| 🔌  | 平台集成网格                        | 在 Gmail、Slack、Telegram、Linear、Jira、iMessage、飞书、微信等平台之间统一的 IntegrationRecord 形态——凭据轮换、速率限制处理和重连逻辑都位于适配器之后。                                                                                                                                                                                                  |
| ⏰  | 确定性循环引擎                                | 一个调度器，它会唤醒、判断是否存在真正的工作，然后才调用智能体运行时。LLM 调用不是基础——它们是最后一步。                                                                                                                                                                                                                                  |
| 🔍  | 检索原语                                      | 分块、嵌入、解析器（PDF/ZIP/文本）、sqlite-vec + pgvector + Chroma 适配器。无需重写召回管道即可混合后端。                                                                                                                                                                                                                                                              |
| 🤖  | 智能体运行时                                              | AI SDK 封装、沙箱提供程序（原生 / 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% | 在 1000 万 token 上下文窗口下的事实召回                      |
上方的分数是opencontext 在公开数据集上的自我评估，
由我们自己的测试框架在 benchmark/ 下生成。它们
不是 Agent Memory Leaderboard (AML) 的结果——AML 在其自有平台上
针对私有精炼数据集进行评估。官方 AML 分数，一旦我们的托管提交
完成，将显示在排行榜卡片上；提交内容见
benchmark/aml-local/。

快速开始

有几种方式可以将 opencontext 集成到你的项目中。选择一种
与你正在构建的内容相匹配的方式。

1. 将运行时嵌入到你自己的应用中

pnpm add @melandlabs/opencontext

一个 30 秒的内存 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. 从 CLI 管理内存

直接从命令行写入和查询内存。add 将单条原始消息写入
活动管理器，无需 LLM 往返，而 search 则在内存、洞察和知识
上运行统一读取。

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  --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），并报告每项的
通过 / 警告 / 失败。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 服务器、CLI，外加集成网格和循环引擎                                 |
| 自己搭建智能体循环                                | 一个可分离的循环引擎，它调度何时唤醒智能体，而不是一路到底的 LLM 循环                                       |
| 仅仅为了获得集成而嵌入 opencontext                | 单包安装——一次 pnpm add 即可获得所有能力，使用时不要求 React/Next/Tauri                                  |

架构

┌────────────────────────────┐
│     宿主应用程序            │   ← 你的 UI、CLI 或守护进程
│   （一个参考应用，           │
│    或你自己的嵌入器）        │
└─────────────┬──────────────┘
│
┌────────────────────────┴────────────────────────┐
│   @melandlabs/opencontext                       │
│   contracts · memory · rag · loop · agent       │
└────────────────────────┬────────────────────────┘
│
┌─────────────────────────────┴─────────────────────────────┐
│   存储后端                                                 │
│   sqlite-vec · postgres · indexeddb · chroma · pgvector   │
└─────────────────────────────┬─────────────────────────────┘
│
┌─────────────────────────────┴─────────────────────────────┐
│   集成网格  (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。