Oort

面向 AI Agent 的开源记忆。
旧事实会被标记为失效，而不是覆盖。旧历史会转移到低成本存储。
每次回忆都能说明为何选中这些信息。

---

为什么选择 Oort

Agent 会在会话之间遗忘信息，而常见的解决办法是使用只会不断增长的向量存储。这会带来两个问题：过时事实仍会胜出（“住在柏林”会压过“搬到了里斯本”），而且你存储过的每条消息都会让账单增长。

Oort 像太阳系保存物质一样管理记忆：

层级	名称	存放内容	回忆
热	光球层	刚刚发生的事，以及任何已固定的内容	即时，无需搜索
温	柯伊伯带	从过往会话中提炼的简短事实，已完整索引	几毫秒
冷	奥尔特云	更早的历史记录，使用 zstd 压缩。文本保留，庞大的向量则移除。	需要时会重新取回

事实发生变化时，旧事实会被标记为已取代并保留在历史记录中；发现事实错误时，则会标记为已更正。回忆会返回当前为真的内容，除非你要求查看某个日期的 --as-of、某项事实的 --history，或某个时间点 --known-at 的已知信息（也可以直接问“我们在 3 月用的是什么”）。

快速开始

安装 CLI（Node 22.15 或更高版本），然后连接你的 Agent。oort setup 会检测你的 Agent，询问你希望如何提供密钥，连接它们并运行快速检查。每一步都可以跳过。

npm install -g oortmem

oort setup 还会在 ~/.oort/cli 安装受管理的副本（npm i -g --prefix ~/.oort/cli oortmem），你的 Agent 会运行这个副本，这样你使用 nvm、fnm、Volta 或 asdf 切换 Node 版本时，它们的钩子和 MCP 配置仍能正常工作。了解更多。

之后要更新时，运行 oort update：它会更新这里的所有副本（包括 Claude Code 钩子运行的受管理副本），迁移存储，并重启 oort serve。

oort setup
oort recall "where does the user live"
oort explain "where does the user live"   # each stage's rank and score

所有命令和标志都列在 docs/cli.md 中。要在自己的代码中使用 Oort（import { createOort } from 'oortmem'）：SDK：docs/sdk.md · 参考：docs/sdk-reference.md · examples/。若要从源代码构建：git clone https://github.com/oortmem/oort && cd oort && pnpm install && pnpm build && cd packages/cli && pnpm add -g .（pnpm 12）。

兼容

Claude Code（钩子和 MCP 服务）、Claude Desktop、Codex、Cursor、Gemini CLI、VS Code，以及任何使用 stdio 的 MCP 客户端。oort connect <host> 会写入配置、备份旧文件并打印差异。Claude Code 指南。

使用你的编码 Agent 借助 Oort 构建应用

oort-sdk 技能会指导你的编码 Agent 将 Oort 集成到你自己的应用和 Agent 框架中：TypeScript SDK（来自 oortmem 的 createOort）、多用户应用、Vercel AI SDK、LangGraph.js 和 OpenAI Agents JS、无服务器架构、原生 Python 客户端（from oortmem import Oort），以及供其他语言使用的 CLI JSON。技能中的每个代码块都是经过测试的示例。它是一个独立插件 oort-dev，因此“帮我用 Oort 构建应用”可以在不安装“为我自己的会话提供记忆”（oort 插件）的情况下完成，反之亦然。

Claude Code：

claude plugin marketplace add oortmem/oort
claude plugin install oort-dev@oortmem

（或者在会话中运行 /plugin marketplace add oortmem/oort 和 /plugin install oort-dev@oortmem）

Codex：

codex plugin marketplace add oortmem/oort
codex plugin add oort-dev@oortmem

（或者在 Codex 中运行 /plugins）

对于任何其他能读取 SKILL.md 的 Agent（Cursor、Gemini CLI、GitHub Copilot、OpenCode 等）：将 skills/oort-sdk 复制到其技能文件夹中，例如复制到仓库中的 .agents/skills/oort-sdk，或运行 npx skills add oortmem/oort --skill oort-sdk。各工具的详情请见：skills/README.md。

工作原理

flowchart LR
  T[Agent turn] --> S[Scrub secrets]
  S --> W[Writer: distil short facts]
  W --> G{Decide: add, update,<br/>supersede or skip}
  G --> H[(Photosphere<br/>hot)]
  H -- consolidate --> K[(Kuiper Belt<br/>warm)]
  K -- age out --> C[(Oort Cloud<br/>cold, zstd)]
  Q[Recall query] --> F[Lexical + vector<br/>validity filter]
  F --> R[Fuse and rerank,<br/>freshness breaks ties]
  K --> F
  C -- stub and entities --> F
  C -. hydrated when returned .-> A
  R --> A[Memory block<br/>for the prompt]

• 写入路径。 首先会清除每轮对话中的机密信息。一个小型写入模型会将内容提炼为简短事实，决策模型则会将每条事实与已存储的内容进行比较：新增、更新、取代旧内容，或跳过。
• 读取路径。 关键词搜索（SQLite FTS5）和向量搜索（sqlite-vec）会同时运行。排名前会过滤掉不再有效的事实。系统会融合搜索结果，并在有帮助时重新排序；新鲜度只用于打破平局，因此较新的事实不会胜过匹配度更高的事实。
• 本地优先。 所有数据都存放在你设备上的 ~/.oort 中，使用一个 SQLite 文件和压缩的冷数据块。除非你选择 Oort Cloud，否则不会托管任何内容。如果没有 API 密钥且未登录 Oort Pro，本地命令完全不会发起网络请求（回忆功能会回退到关键词搜索），并且测试会在阻止所有套接字的情况下运行这些命令。唯一的例外是每天一次检查是否有新版本：只向 npm 注册表发送一个请求，不会发送任何与你有关的信息；设置 OORT_NO_UPDATE_CHECK=1 可关闭此功能（详情）。

包

包	功能
oortmem	oort 命令行工具（设置、连接器、本地 MCP 服务、回忆、导入和导出），以及 TypeScript SDK（docs/sdk.md）
@oortmem/core	引擎：机密信息清理、写入门控、混合回忆、融合、分层和项目范围
@oortmem/store-sqlite	使用 FTS5 和 sqlite-vec 的 SQLite 存储，以及 zstd 冷数据块
@oortmem/writer	将对话轮次转化为简短、独立的事实
@oortmem/decide-jev	使用 TypeSafe Jev 执行添加、更新、替代或跳过决策
@oortmem/embed-voyage	通过 Voyage AI 生成嵌入
@oortmem/rerank-voyage	通过 Voyage AI 进行重排
@oortmem/local-models	在 CPU 上运行嵌入和重排（ONNX Runtime）：无需密钥或账户
@oortmem/claude-code	Claude Code 钩子和对话记录导入
@oortmem/mcp	MCP 工具、架构、说明和技能，可通过任意记忆后端提供服务
oortmem on PyPI	原生 Python 客户端（Oort、AsyncOort；docs/python.md）以及 oort 命令的启动器

Claude Desktop、Claude Code、Codex、Cursor 和 Gemini CLI 的安装包位于 distribution/。

本仓库仅包含开源引擎和命令行工具。托管服务（oortcloud.dev、Oort Cloud 和 Oort Pro 中继）是独立服务；只有在使用 Oort Pro 时，引擎和命令行工具才会通过 HTTPS 与其通信。

密钥或 Oort Pro

Oort 会调用三种模型服务：Voyage AI（嵌入和重排）、TypeSafe（决策）和 Anthropic（撰写）。使用 oort keys set 添加你自己的密钥。密钥会保存在 macOS 钥匙串中，或保存在 Linux 和 Windows 上权限为 0600 的凭据文件中。

也可以不使用密钥和账户运行：npm i -g @oortmem/local-models && oort models pull 会下载小型嵌入和重排模型（58 MB，采用 MIT 和 Apache-2.0 许可），并在 CPU 上离线运行。保存新记忆仍需要决策和撰写模型。本地模型。

也可以使用 Oort Pro：每月 $19，适用地区含增值税。无需 API 密钥。运行 oort login，然后运行 oort cloud use，即可将记忆保存在欧盟境内的 Oort Cloud，并使用仪表板、星图以及连接 claude.ai 和 ChatGPT 的连接器。你可以随时导出或删除记忆，也可以将记忆保存在自己的设备上，只使用不存储内容的中继。价格。

项目与信任

记忆按项目划分范围。默认情况下，项目 ID 来自主仓库根目录，因此 Git worktree 会与主检出共享记忆。仓库中 oort.config.json 的 project.id 会被忽略，直到你运行 oort project link，因为克隆的仓库否则可能会利用它读取其他项目的记忆。详情请参阅 docs/cli.md。

开发

pnpm install
pnpm verify   # public-repo and copy checks, format, lint, build, typecheck and every test

导出格式请参阅 docs/export-format.md。

安全

请将漏洞报告发送至 [email protected]，不要在公开问题中报告。

许可证

Apache 2.0。由瑞典哥德堡制作。