Memory OS AI

4.0.2 candidate — qualification in progress; not published or deployed.

One local memory for all your AI assistants. Decisions, facts and lessons saved by Claude are recalled by Codex, Copilot, Cursor, Gemini or Grok — on your machine, under your control, with evidence for every claim.

Every AI assistant forgets between sessions, and nothing it learns reaches the next assistant you open. Memory OS AI is a local MCP server that gives all of them the same persistent memory: typed, dated, sourced and isolated per project. It needs no LLM on the server side — the assistant you already use extracts the facts — so recall costs no API call and works offline.

Quick start (macOS)

Before setup, set MEMORY_V4_BUILD_COMMIT to the 40-character source commit from the qualified release dossier (releases/4.0.2/QUALIFICATION.md for this candidate). An installed wheel has no Git checkout: without this operator-provided identity, /ready refuses the build and doctor reports FAIL. Download/setup is not proof of a qualified build; candidate activation still requires Romain's GO.

pip install 'memory-os-ai[ops]'
memory-os-admin setup --write-launchd ~/memory-os-launchd   # creates your private access token + prints client configs
cp ~/memory-os-launchd/*.plist ~/Library/LaunchAgents/ && launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/local.memory-os-v4.plist
memory-os-admin doctor                                       # checks the server, the security and every AI client

doctor ends with a line such as 17 checks: 16 pass, 1 warn, 0 fail. Full guide: v4/docs/OPERATIONS.md.

Works with your assistants and editors

All clients connect through memory-os-relay, which reads your private token file itself — no secret is ever written into a client configuration. memory-os-admin setup prints a configuration snippet for each one, and memory-os-admin doctor checks their configuration syntax; it does not prove a live handshake for every client.

Shared agent rules live in AGENTS.md: start with memory_session_brief, search before assuming, save atomic dated facts with memory_chat_save. The server also sends these rules to every client at connection. Claude Code gets two optional hooks: the project brief injected at session start (framed as data, never as instructions) and a reminder to save after long sessions.

What makes it different

• One memory, every assistant. The point is continuity between AI vendors; built-in memories (ChatGPT, Claude, Gemini, Copilot) stay locked to one of them.
• Local and private by default. One server per user on 127.0.0.1, mandatory bearer token (0600 file), Host/Origin validation against DNS-rebinding, no telemetry. Memories are treated as data, never as instructions.
• No LLM on the server. Extraction is done by the client assistant at save time; search is hybrid dense + BM25 with multi-query fusion. A warm search takes about 15 ms in the evaluation harness; cold start (server and model load, ~3 s) and ingestion are paid once, not per query.
• Facts that change correctly. Bi-temporal facts (event_time, valid_from/valid_until): a fact is only replaced explicitly or on a declared unique property — never because two sentences look alike — and history is kept. memory_timeline answers "how did X evolve", at_time answers "what was true on …".
• Operated like production, even in ALPHA. Single writer with an inter-process lock, idempotent requests with durable receipts, encrypted verified backups (AES-256-GCM) with restore drills, a daily health report, runbooks for eight incident types, and a /ready endpoint that reports the attested build commit.

Evidence, not adjectives

Every number below comes from a versioned run you can reproduce; none is a vendor claim.

We publish retrieval recall, answer quality and agent-task success separately, with sample sizes and confidence intervals, and always next to simple baselines (BM25, dense-only, files, full context). Next milestones: a benchmark with questions never seen during development, answer accuracy with a fixed reader model, and independent reproduction — before any leaderboard claim. End-to-end time per LongMemEval-S question (19.7 s p50) is dominated by indexing ~50 sessions with the neural encoder; warm search stays in milliseconds.

Architecture

 Claude · Codex · Copilot · Cursor · Antigravity · Gemini · Grok · Windsurf
        │ stdio (MCP)            one relay per client process, reads the 0600 token file
        ▼
 memory-os-relay ──HTTP + Bearer──▶ memory-os-v4 server (127.0.0.1:8765, launchd)
                                     ├─ MCP tools: brief, search, timeline, chat_save, add_facts, blocks, forget…
                                     ├─ engine: typed bi-temporal items, project scopes, explicit fact updates
                                     ├─ retrieval: dense (granite-97m multilingual) + BM25 + entities, RRF fusion
                                     ├─ single writer lock · request receipts · /health · /ready
                                     └─ store: JSONL by default; transactional SQLite S2/S3 opt-in (qualified backups not yet supported)
 memory-os-admin: setup · doctor · backup · restore-drill · health · hooks

Details: v4/docs/ARCHITECTURE.md, v4/docs/HTTP_CLIENT_CONTRACT.md, v4/docs/ADR-001-SQLITE.md, v4/docs/READINESS.md.

Honest limits of this ALPHA

• One user, one machine (macOS qualified). Projects organise memory; they are not a security boundary between people. No remote access: assistants that run only in the cloud cannot reach a local server yet.
• The JSONL store and request receipts are not atomic across files; transactional SQLite S2 and offline reversible migration S3 ship opt-in, with failure-injection tests and embedding caching. SQLite qualified backups/restore drills (S4) remain to do; the current ops backup command refuses SQLite.
• The retrieval gain over BM25 is shown on LongMemEval-S with C4 settings proposed as defaults in the 4.0.2 candidate (MEMORY_V4_BM25_PROFILE=scoped_literal, MEMORY_V4_LEXICAL_GUARD_K=3); these options were not in published 4.0.1. Romain decides activation; rollback uses MEMORY_V4_BM25_PROFILE=legacy and MEMORY_V4_LEXICAL_GUARD_K=0. The measured MiniLM/English gain does not qualify Granite, multilingual use, multi-query RRF or MMR context; an independent benchmark and answer-accuracy measurements are still to come.

Development

pip install -e '.[dev,ops]'
pytest v4/tests          # v4 engine, MCP server, ops layer
pytest tests             # v3 engine

The v4 engine lives in v4/src/memory_os_v4; the evaluation harness in v4/bench. Contributions: see CONTRIBUTING.md.

Legacy v3 document engine

memory-os-ai-v3 still ships the previous FAISS document server (21 tools: document ingestion for PDF/DOCX/ images/audio, chat extraction, cross-project linking, cloud overflow). Existing v3 memories can be imported into v4 with the memory_migrate_v3 tool. v3 documentation: legacy/ and the 3.x release notes.

License

LGPL-3.0-or-later. Built and reviewed jointly by Claude (Anthropic) and Codex (OpenAI) with @romainsantoli-web.