Memory OS AI

4.0.2 ALPHA — published on PyPI on 2026-10-10.

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). 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 the operator's local configuration or data migration.

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). BEAM had no exact normalized question/turn overlap with LongMemEval and its preregistered recall criterion failed. The next milestones are the indexing-cost target, a new held-out temporal test, answer accuracy with a fixed reader model and independent reproduction — before any leaderboard claim. On BEAM, indexing took 678 s per conversation at the median while warm search stayed at 41 ms p50; the encoder consumed 99.86% of measured ingestion time.

The experimental MPS/float32 run completed the same 20 BEAM conversations in 661 s: ingestion p50 29.1 s, p95 43.1 s, max 43.7 s. Against archived CPU predictions, Recall@10 Δ +0.0006 (97.5% CI [-0.0083, +0.0135]) and MRR Δ +0.0007 [-0.0003, +0.0019]. Preregistered two-sided equivalence was not demonstrated; no post-hoc non-inferiority claim is made. Historical CPU timings are not paired. The development candidate preserves device=auto, matching the existing MPS deployment on this Mac. Production uses native loading and batch32; the measured MPS float32/batch4 profile differs and remains an experimental variant. Backend or precision changes require operator approval and compatible/rebuilt vectors. See MPS_RESULT_V1.md for evidence, settings and limitations. The production audit and corrected recommendation are documented in MPS_PRODUCTION_ALIGNMENT_V1.md.

The 4.0.3 artifacts are qualified on a private copy. Claude completed the local switchover on 2026-10-10 at 22:36 with Romain's GO (doctor 15 PASS / 0 FAIL). PyPI publication requires a separate GO. The candidate preserves auto/native/batch32 and records loaded parameter dtype/device, model revision, runtime versions and encoder source hash in memory_status and authenticated /ready. Unattested or changed caches rebuild before queries; this first rebuild was qualified on a private copy. The completed ten-question answer pilot used Luna low + Astra high through ChatGPT-authenticated Codex only, on observed BEAM: C4 accuracy 0.40 vs BM25 0.20, 40 calls, 362,348 tokens, zero API spend. This is descriptive: no official judge comparison or leaderboard claim. The broader campaign protocol is preregistered; BEAM 500K was downloaded with approval but refused before inference: only 15 fresh independent groups survived the audit (minimum 30). Its first annotation failure is a missing source_chat_ids field, not a demonstrated dangling ID. See held-out alternatives and diagnosis. The approved MemoryAgentBench-LRU acquisition/audit completed with NO-GO: 110 contexts, 171 questions, 74 unique usable questions, zero fresh attested source groups (infbench_sum/detective_qa unresolved); zero inference. See bounded acquisition/audit. Romain instead authorized LongMemEval-S answer accuracy via Codex: all 500 questions including abstentions, C4 versus same-arm BM25, Luna low reader and Luna high judge with official question-type grading templates. The qualified 4.0.3 engine is frozen separately from this harness. No API spend; results remain descriptive, since this corpus was already observed and the judge differs from the published GPT-4o snapshot. This campaign has not been run by Codex. See copy qualification and later rollout.

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.
• C4 is the 4.0.2 default (MEMORY_V4_BM25_PROFILE=scoped_literal, MEMORY_V4_LEXICAL_GUARD_K=3). LongMemEval-S passed its gate but was not independent; the question-disjoint BEAM run failed its recall gate. C4 therefore has no general superiority claim. Rollback uses MEMORY_V4_BM25_PROFILE=legacy and MEMORY_V4_LEXICAL_GUARD_K=0.
• Neither run measures official answer accuracy, multilingual quality, agent-task success or leaderboard rank.

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.