Provides tiered, self-correcting memory for AI agents that manages fact updates and long-term history through a multi-layer storage system.
Also known as oortmem/oort, oortmem
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.10.0
- Last commit
- Nov 16, 2026
- License
- Apache-2.0
What is Oort MCP?
Oort provides tiered, self-correcting memory for AI agents that manages fact updates and long-term history through a multi-layer storage system.
Summary generated from the project's README
About Oort MCP server
Oort provides a tiered, self-correcting memory system designed for AI agents to manage long-term history and evolving facts. It uses a multi-layer storage architecture consisting of the Photosphere for instant access to recent events, the Kuiper Belt for indexed short facts, and the Oort Cloud for compressed older history. This structure ensures that as facts change, old information is marked as superseded rather than simply overwritten, allowing agents to maintain an accurate timeline.
Developers can implement this locally using the oortmem CLI and SDK, which stores data in a local SQLite file. The system works with various MCP clients including Claude Desktop, Claude Code, Cursor, and Gemini CLI. Users can choose to provide their own API keys for Voyage AI, TypeSafe, and Anthropic, or opt for a local setup using ONNX Runtime models that run on the CPU without requiring any accounts or network calls. For those needing managed storage, Oort Pro offers a hosted service with a dashboard and cloud-based memory synchronization.
What you can do with it
- 1Manage evolving user factsAsk the agent to retrieve the most current information about a user while preserving the history of how that information changed.
- 2Audit memory retrieval logicRequest an explanation of why a specific piece of memory was selected during a recall operation.
- 3Perform temporal memory queriesQuery the memory system to find out what the agent believed to be true at a specific point in the past.
Written from the project's README. Every use case is checked against a quote from it.
How to install Oort MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Oort MCP in Claude Code
$ claude mcp add --env 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' --env 'OORT_API_KEY=<YOUR_OORT_API_KEY>' --env 'TYPESAFE_API_KEY=<YOUR_TYPESAFE_API_KEY>' --env 'VOYAGE_API_KEY=<YOUR_VOYAGE_API_KEY>' oort -- npx -y oortmemInstall Oort MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"oort": {
"command": "npx",
"args": [
"-y",
"oortmem"
],
"env": {
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OORT_API_KEY": "<YOUR_OORT_API_KEY>",
"TYPESAFE_API_KEY": "<YOUR_TYPESAFE_API_KEY>",
"VOYAGE_API_KEY": "<YOUR_VOYAGE_API_KEY>"
}
}
}
}Install Oort MCP in VS Code
.vscode/mcp.json
{
"servers": {
"oort": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"oortmem"
],
"env": {
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OORT_API_KEY": "<YOUR_OORT_API_KEY>",
"TYPESAFE_API_KEY": "<YOUR_TYPESAFE_API_KEY>",
"VOYAGE_API_KEY": "<YOUR_VOYAGE_API_KEY>"
}
}
}
}Install Oort MCP in VS Code CLI
$ code --add-mcp '{"name":"oort","type":"stdio","command":"npx","args":["-y","oortmem"],"env":{"ANTHROPIC_API_KEY":"<YOUR_ANTHROPIC_API_KEY>","OORT_API_KEY":"<YOUR_OORT_API_KEY>","TYPESAFE_API_KEY":"<YOUR_TYPESAFE_API_KEY>","VOYAGE_API_KEY":"<YOUR_VOYAGE_API_KEY>"}}'Install Oort MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"oort": {
"command": "npx",
"args": [
"-y",
"oortmem"
],
"env": {
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OORT_API_KEY": "<YOUR_OORT_API_KEY>",
"TYPESAFE_API_KEY": "<YOUR_TYPESAFE_API_KEY>",
"VOYAGE_API_KEY": "<YOUR_VOYAGE_API_KEY>"
}
}
}
}Install Oort MCP in Codex
$ codex mcp add oort --env 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' --env 'OORT_API_KEY=<YOUR_OORT_API_KEY>' --env 'TYPESAFE_API_KEY=<YOUR_TYPESAFE_API_KEY>' --env 'VOYAGE_API_KEY=<YOUR_VOYAGE_API_KEY>' -- npx -y oortmemInstall Oort MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.oort] command = "npx" args = ["-y", "oortmem"] [mcp_servers.oort.env] ANTHROPIC_API_KEY = "<YOUR_ANTHROPIC_API_KEY>" OORT_API_KEY = "<YOUR_OORT_API_KEY>" TYPESAFE_API_KEY = "<YOUR_TYPESAFE_API_KEY>" VOYAGE_API_KEY = "<YOUR_VOYAGE_API_KEY>"
Install Oort MCP in Gemini CLI
$ gemini mcp add -s user -e 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' -e 'OORT_API_KEY=<YOUR_OORT_API_KEY>' -e 'TYPESAFE_API_KEY=<YOUR_TYPESAFE_API_KEY>' -e 'VOYAGE_API_KEY=<YOUR_VOYAGE_API_KEY>' oort npx -- -y oortmemInstall Oort MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"oort": {
"command": "npx",
"args": [
"-y",
"oortmem"
],
"env": {
"ANTHROPIC_API_KEY": "<YOUR_ANTHROPIC_API_KEY>",
"OORT_API_KEY": "<YOUR_OORT_API_KEY>",
"TYPESAFE_API_KEY": "<YOUR_TYPESAFE_API_KEY>",
"VOYAGE_API_KEY": "<YOUR_VOYAGE_API_KEY>"
}
}
}
}Configuration
ANTHROPIC_API_KEYSecretAnthropic key, for writing saved facts. Leave empty to use Oort Pro.
OORT_API_KEYSecretOort Pro key. With it you need no other keys.
TYPESAFE_API_KEYSecretTypeSafe key, for deciding what to keep when saving. Leave empty to use Oort Pro.
VOYAGE_API_KEYSecretVoyage AI key, for search by meaning. Leave empty to use Oort Pro, or keyword search only.
OORT_HOMEWhere Oort keeps your memories. Defaults to ~/.oort, shared with the oort command line.
| Name | Description | |
|---|---|---|
| ANTHROPIC_API_KEY | Anthropic key, for writing saved facts. Leave empty to use Oort Pro. | Secret |
| OORT_API_KEY | Oort Pro key. With it you need no other keys. | Secret |
| TYPESAFE_API_KEY | TypeSafe key, for deciding what to keep when saving. Leave empty to use Oort Pro. | Secret |
| VOYAGE_API_KEY | Voyage AI key, for search by meaning. Leave empty to use Oort Pro, or keyword search only. | Secret |
| OORT_HOME | Where Oort keeps your memories. Defaults to ~/.oort, shared with the oort command line. |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSPass
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHubWhy Oort
Agents forget between sessions, and the usual fix is a vector store that only grows. That has two problems. Stale facts keep winning ("lives in Berlin" outranks "moved to Lisbon"), and the bill grows with every message you ever stored.
Oort keeps memory the way a solar system keeps matter:
| Tier | Name | What lives there | Recall |
|---|---|---|---|
| Hot | Photosphere | What just happened, and anything pinned | Instant, never searched for |
| Warm | Kuiper Belt | Short distilled facts from past sessions, fully indexed | A few milliseconds |
| Cold | Oort Cloud | Older history, zstd-compressed. The text stays, the heavy vector goes. | Comes back when it matters again |
When a fact changes, the old one is marked superseded and kept for history; a fact found wrong is marked corrected. Recall returns what is true now, unless you ask for --as-of a date, the --history of a fact, or what was --known-at a time (or just ask "what did we use in March").
Quickstart
Install the CLI (Node 22.15 or newer), then connect your agent. oort setup detects your agents, asks how you want to provide keys, connects them and runs a quick check. Every step can be skipped.
npm install -g oortmem
oort setup also installs the managed copy in ~/.oort/cli (npm i -g --prefix ~/.oort/cli oortmem), the one your agents run, so their hooks and MCP entries keep working when you switch Node versions with nvm, fnm, Volta or asdf. More.
To update later, run oort update: it updates every copy here (the managed copy the Claude Code hooks run included), migrates the store and restarts oort serve.
oort setup
oort recall "where does the user live"
oort explain "where does the user live" # each stage's rank and score
Every command and flag is in docs/cli.md. To use Oort from your own code (import { createOort } from 'oortmem'): SDK: docs/sdk.md · reference: docs/sdk-reference.md · examples/. To build from source instead: git clone https://github.com/oortmem/oort && cd oort && pnpm install && pnpm build && cd packages/cli && pnpm add -g . (pnpm 12).
Works with
Claude Code (hooks, plus the MCP server), Claude Desktop, Codex, Cursor, Gemini CLI, VS Code, and any MCP client over stdio. oort connect <host> writes the config, backs up the old file and prints the diff. Claude Code guide.
Build with Oort using your coding agent
The oort-sdk skill teaches your coding agent to build Oort into your own apps and agent frameworks: the TypeScript SDK (createOort from oortmem), multi-user apps, the Vercel AI SDK, LangGraph.js and OpenAI Agents JS, serverless, the native Python client (from oortmem import Oort), and the CLI's JSON for other languages. Every code block in it is a tested example. It is a separate plugin, oort-dev, so "help me build with Oort" installs without "memory for my own sessions" (the oort plugin), and the other way round.
Claude Code:
claude plugin marketplace add oortmem/oort
claude plugin install oort-dev@oortmem
(or, in a session, /plugin marketplace add oortmem/oort and /plugin install oort-dev@oortmem)
Codex:
codex plugin marketplace add oortmem/oort
codex plugin add oort-dev@oortmem
(or /plugins in Codex)
Any other agent that reads SKILL.md (Cursor, Gemini CLI, GitHub Copilot, OpenCode and more): copy skills/oort-sdk into its skills folder, for example .agents/skills/oort-sdk in your repository, or run npx skills add oortmem/oort --skill oort-sdk. Details for each tool: skills/README.md.
How it works
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]
- Write path. Every turn is scrubbed of secrets first. A small writer model distils it into short facts, and a decision model compares each fact with what is already stored: add it, update it, supersede the old one, or skip it.
- Read path. Keyword (SQLite FTS5) and vector (sqlite-vec) search run together. Facts that are no longer valid are filtered out before ranking. Results are fused, reranked when it helps, and freshness only breaks ties, so a newer fact never beats a better match.
- Local first. Everything lives in
~/.oorton your machine, in one SQLite file plus compressed cold blobs. Nothing is hosted unless you choose Oort Cloud. With no API keys and no Oort Pro login, the local commands make no network call at all (recall falls back to keyword search), and a test runs them with every socket blocked. The one exception is a once-a-day check for a new release, a single request to npm's registry that sends nothing about you;OORT_NO_UPDATE_CHECK=1turns it off (details).
Packages
| Package | What it does |
|---|---|
oortmem |
The oort command line (setup, connectors, the local MCP server, recall, import and export), and the TypeScript SDK (docs/sdk.md) |
@oortmem/core |
The engine: secret scrubbing, the write gate, hybrid recall, fusion, tiering and project scope |
@oortmem/store-sqlite |
Storage on SQLite with FTS5 and sqlite-vec, and zstd cold blobs |
@oortmem/writer |
Turns conversation turns into short, self-contained facts |
@oortmem/decide-jev |
Add, update, supersede or skip decisions, using TypeSafe Jev |
@oortmem/embed-voyage |
Embeddings through Voyage AI |
@oortmem/rerank-voyage |
Reranking through Voyage AI |
@oortmem/local-models |
Embeddings and reranking on your CPU (ONNX Runtime): no keys, no account |
@oortmem/claude-code |
Claude Code hooks and transcript import |
@oortmem/mcp |
The MCP tools, schemas, instructions and skill, served over any memory backend |
oortmem on PyPI |
The native Python client (Oort, AsyncOort; docs/python.md) and a launcher for the oort command |
Install bundles for Claude Desktop, Claude Code, Codex, Cursor and Gemini CLI are in
distribution/.
This repo is the open-source engine and CLI only. The hosted side (oortcloud.dev, Oort Cloud and the Oort Pro relay) is a separate service; the engine and CLI reach it only over HTTPS when you use Oort Pro.
Keys, or Oort Pro
Oort calls three model services: Voyage AI (embeddings and rerank), TypeSafe (decisions) and Anthropic (the writer). Bring your own keys with oort keys set. They stay in the macOS Keychain, or in a 0600 credentials file on Linux and Windows.
Or run with no keys and no account: npm i -g @oortmem/local-models && oort models pull downloads small embedding and rerank models (58 MB, MIT and Apache-2.0) and runs them on your CPU, offline. Saving new memories still needs the decision and writer models. Local models.
Or use Oort Pro: $19/month, VAT included where applicable. No API keys needed. Run oort login, then oort cloud use to keep your memories in Oort Cloud in the EU, with a dashboard, a star map and a connector for claude.ai and ChatGPT. You can export or delete them at any time, or keep them on your machine and use only the relay, which stores no content. Pricing.
Projects and trust
Memories are scoped to a project. By default its id comes from the main repository root, so a git worktree shares memories with its main checkout. A project.id in a repo's oort.config.json is ignored until you run oort project link, because a cloned repo could otherwise use it to read another project's memories. Details in docs/cli.md.
Develop
pnpm install
pnpm verify # public-repo and copy checks, format, lint, build, typecheck and every test
The export format is documented in docs/export-format.md.
Security
Please report vulnerabilities to security@oortcloud.dev, not in a public issue.
License
Apache 2.0. Made in Gothenburg, Sweden.
Oort MCP questions
How do I add Oort MCP to Claude Code?
Run claude mcp add --env 'ANTHROPIC_API_KEY=<YOUR_ANTHROPIC_API_KEY>' --env 'OORT_API_KEY=<YOUR_OORT_API_KEY>' --env 'TYPESAFE_API_KEY=<YOUR_TYPESAFE_API_KEY>' --env 'VOYAGE_API_KEY=<YOUR_VOYAGE_API_KEY>' oort -- npx -y oortmem in your terminal. Add --scope user to make it available in every project.
How do I add Oort MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does Oort handle changing facts?
When a fact changes, the old one is marked as superseded and kept for history, while incorrect facts are marked as corrected to ensure recall returns what is true now.
Is my data stored in the cloud by default?
No, everything lives locally in a SQLite file on your machine unless you specifically choose to use the Oort Cloud service.