Mnemosyne OS README

The sovereign AI Operating System

Open to build on · Private at the core

English ·  Français ·  Español ·  Deutsch ·  Português ·  Русский ·  中文

Everyone is building the intelligence. Mnemosyne builds the relationship — the memory that makes an AI truly know you, across sessions and across time. On your machine. Yours to see.

→ Why the relationship layer

🔏 Every installer above is cryptographically attested to this exact repo, workflow and commit — via GitHub Artifact Attestations (Sigstore-backed build provenance). Don't take the download on faith — verify the file you got matches what our CI actually built:

bash

Copy

gh attestation verify Mnemosyne-OS-Infinity-Setup-x64.exe -R Mnemosyne-OS/Mnemosyne-Neural-OS

🌐 mnemosyne-os.io — the product, for builders · mnemosyne-os.com — the company, press & labs · 📖 docs.mnemosyne-os.io — the user guide

[!TIP] 📖 The user documentation is live: docs.mnemosyne-os.io — every engine explained step by step, in English · Français · Español.

🌍 Fully multilingual — the OS speaks your language

The entire interface is localized in seven languages — onboarding, settings, chat, the voice assistant, every dialog. Switching language even re-selects the ★ recommended embedding model for it, so retrieval quality follows your language, not just the labels. Open windows pick the change up instantly.

	Language		Status
	English	Your memory. Your machine. Your rules.	Stable
	Français	Ta mémoire. Ta machine. Tes règles.	Stable
	Español	Tu memoria. Tu máquina. Tus reglas.	Stable
	Deutsch	Dein Gedächtnis. Deine Maschine. Deine Regeln.	Beta
	Português	Sua memória. Sua máquina. Suas regras.	Beta
	Русский	Твоя память. Твоя машина. Твои правила.	Beta
	中文	你的记忆。你的机器。你的规则。	Beta

Sovereign, local-first memory — in your language: un système d'exploitation de mémoire souverain et local · un sistema operativo de memoria soberano y local · ein souveränes, lokales Gedächtnis-Betriebssystem · um sistema operacional de memória soberano e local · суверенная локальная операционная система памяти · 主权的本地优先记忆操作系统.

Not another agent-memory library

Mem0, Zep and Letta give agents a memory layer you wire into a cloud stack.

Mnemosyne OS is a personal memory OS that runs on your machine — your data never leaves it, a human governs it, and it scores 77.1% on LongMemEval-M (audit it yourself).

The AI that remembers you — not infrastructure you plug into someone else's.

Where the project lives

Published by XPACEGEMS LLC. These are its official addresses:

Why call it an "OS"?

Not because it has a kernel or drivers — because it does what an OS does: it manages resources on behalf of processes that shouldn't have to manage them themselves. Linux does that for programs (CPU, RAM, disk, network). Mnemosyne does the same thing for AI agents, and the resources are just different:

This isn't a marketing stretch invented for this repo. MemGPT (Packer et al., UC Berkeley, 2023, arXiv:2310.08560) proposed the same "OS for LLMs" analogy in a peer-reviewed paper — virtual context management modeled on OS memory hierarchies. Mnemosyne takes that same premise further: not a single-session context-paging technique, but a system that runs continuously, isolates multiple agents, and persists on the machine as a daemon — not a library you import and lose on exit.

The flagship app — Mnemosyne OS Infinity Edition

The reference application of the ecosystem: a local-first AI Operating System that puts a sovereign memory core under strict user control. It runs LLMs locally or in the cloud, keeps every encrypted vault on your machine, and — for agent-to-agent sync — can speak over a libp2p transport (@mnemosyne-workspace/mnemosync-p2p).

Unlike fragmented AI wrappers, Mnemosyne never exposes your knowledge vault indiscriminately. Every agentic connection is governed by FGAC (Fine-Grained Access Control) and 400 Zod-validated IPC channels, ensuring total sovereignty over what executes, what's stored, and what syncs.

Core Modules

Under the hood — the engines

Not one big "AI" black box — several independent, purpose-built engines:

• Embedding engine — a priority-ordered chain of embedding providers (cloud, local ONNX, Ollama). Tries each in order and fails loud rather than returning a null vector — a failed embedding must never silently become an invisible memory.
• Retrieval engine — an in-RAM, decrypted vector cache (int8-quantized to scale), ANN search unioned with exact term matching before the final re-rank pass.
• Spine engine — classifies every memory by semantic nature (its "spine" + tags), from a taxonomy that lives as data, not hardcoded logic — so new categories don't require a code change.
• Dream State — two-speed consolidation. A fast, low-latency tier extracts facts during active use; a heavier tier runs at idle/night to resolve contradictions and link memories across sessions. Output is appended alongside raw retrieval, never silently replacing it — see the benchmark results below.
• Adaptive RAG (the "gearbox") — rather than injecting every retrieved candidate, context selection (top-k / MMR / low-discrepancy sampling) scales to both the model tier you're running and the thinking mode you pick.
• Theia — the vision engine — named for the Titaness of sight, who in the myth is Mnemosyne's sister. A complete image-memory engine: your images are embedded 100% locally (SigLIP 2, in an isolated sidecar) into their own vector space, recalled in chat as thumbnails through three rank-fused channels — semantic, pixel-color palette, and emergent categories the engine discovers on its own — and browsed in a living gallery. The human always outranks the model: rate, pin, describe, teach, rename or merge its categories. Honest by construction: a cold or still-indexing engine says so, instead of inventing "no matches". Off by default — one Settings toggle.
• Voice engines, STT and TTS, fully independent — speech-to-text runs small models in-process and large models in an isolated GPU/CPU sidecar (a big STT model loaded in-process can crash the whole app); text-to-speech runs system, cloud, or local (offline binary or GPU voice cloning), scheduled sample-accurately for gapless playback. No NVIDIA GPU → automatic CPU fallback, never a hard block.
• 400 Zod-validated IPC channels connect all of the above to the UI — auto-generated and checked by a drift test on every build.

📄 Deep dive: The Resonance Engine — technical whitepaper. The full architecture behind these engines: why memory should resonate rather than be looked up, how consolidation and adaptive selection work, and the LongMemEval results — kept current as the engine ships.

📚 Full documentation — the user guide lives at docs.mnemosyne-os.io; concepts, architecture, governance, and design decisions live in doc/.

How memory works

flowchart LR
    A["Document · conversation · file"] --> B["Vault<br/>domain-isolated, graduated protection"]
    B --> C["Chronicle<br/>content + semantic type + embedding vector"]
    C --> D["Semantic retrieval (RAG)"]
    D --> E["query() / ask()"]
    F["Dream State<br/>cold consolidation"] -. replays & links .-> C

    style B fill:#1a1a2e,stroke:#7c3aed,color:#fff
    style F fill:#1a0e1a,stroke:#ff6b9d,color:#fff

Proven on LongMemEval-M — not just a pitch

LongMemEval is a public, independent long-term-memory benchmark. Its full-haystack variant surrounds every question's evidence with ~480 distractor sessions — the closest published setup to a real, lived-in memory vault, and harder than the -S slice most reported numbers use.

Which judge graded a number changes what it means, so we publish both. Under July's flexible judge the same build measures 81.3 %; under the strict one, 77.1 %. Both ledgers ship, and the channel's gain is honestly smaller under the flexible reading (+7/−2) than under the strict one (+9/−1).

July's 72.9 % stays on the record as what it was: a lower bound under the flexible judge, and a composed one — only the multi-session category had been re-run with the full engine, the other 40 rows carried from the baseline. It is archived and DOI-pinned rather than withdrawn. It is not the same instrument as 77.1 %, so the two are published side by side and never chained into a single progression.

Don't take any of it on faith — audit it. The published grader and per-question verdicts let you re-derive every score in one command, no engine and no network. Full methodology, root-cause analysis, and the raw run logs of both campaigns are public too:

🔍 Audit it yourself — live results page →  ·  raw logs & methodology

Citing this work. Both the evidence and the architecture are archived under permanent identifiers, so they can be cited rather than merely linked:

Interface Gallery

The infinite canvas (v1.4.0): pan the void, zoom 10%–100%, and make the plane yours — the image gallery, MnemoHub, diagnostics, world clocks, weather and stickers, all living on one endless surface


Thirteen seconds of the real thing — the canvas panned, zoomed and decorated live · watch in higher quality

Turn memory on for your images. One Settings toggle gives your vaults an eye: drop in a folder of photos and Mnemosyne OS remembers every image you add — indexed 100% locally, organized in a living gallery you can rate, pin and teach, and recalled in chat: ask for "the pieces that look like a blue cup" and your own photos answer.

Neural Map: your vault rendered as a living mathematical topology — Enneper surface, Klein bottle, Lorenz attractor, Clifford torus… the equation is the shape



Every node is a memory, every edge a measured semantic link — here the same graph wound onto a torus, tuned live



Multi-model by design: run memory 100% local, cloud, or hybrid — Gemini, Claude, OpenAI, Groq, Mistral, DeepSeek, Ollama



MnemoHub: build a cartridge on the SDK, sign it with your sovereign wallet, and publish it to the ecosystem



Sovereign Notes: write in a local, classified vault — every note is embedded and retrievable, feeding the same memory your agent draws on

Two doors between your IDE and your memory

You already run an agent next to your editor. It opens every session without the history of the project it is working in, so it reasons its way back to conclusions you reached weeks ago, and it will do that again tomorrow. Part of that history is not lost: the agent wrote it down itself. It is sitting in a dot-directory beside the code, usually gitignored, read by nothing.

Mnemosyne OS opens two doors onto it, and they run in opposite directions.

Door one, memory reads the agent. DocWatch watches a folder you deliberately point at, whatever its name, so .claude/…/memory is treated like any other source and what your agent noted becomes retrievable next to your documents and your code. Shipped in v1.4.3: before that a blanket ignore rule dropped every dot-directory, in silence.

→ Connect your coding agent's memory

Door two, the agent reads memory. @mnemosyne_os/mcp is a Model Context Protocol server: one entry in your client config, and the agent can search a vault, ask it a question in prose, and write back what it worked out.

npx -y @mnemosyne_os/mcp

→ Connect Claude to Mnemosyne OS (MCP)

Three of those tools need neither the app, nor a vault, nor a single token: they read the transcripts your harness already writes to disk. That is what makes "is another session live on this branch before I commit?" cheap enough to actually ask.

The mechanism is the whole claim. We publish no measurement of what this saves in tokens or in minutes, so we assert none. Retrieval is not reasoning: a decision a model can look up is a decision it does not derive a second time, and the context it would have spent reconstructing where it is goes to the task instead. Watch it in your own sessions rather than taking a number for it.

Build on Mnemosyne OS

You've seen what it is and that it works — now build on it. Your apps, agents, and skins talk to the private AI memory runtime through a public Gateway contract: a stable, documented surface you build against, while the Cognitive Core stays sealed and never exposed.

Two ways in:

• 🛠️ Build on it — scaffold an app and you're talking to the memory vault in minutes.
• 💾 Run it — install the flagship desktop app, Infinity Edition.

npm create @mnemosyne_os/app

Start from the cartridge boilerplate and you're ingesting and querying the vault — under FGAC, scoped, and consent-gated — in minutes.

🛡️ Zero-Trust by design. Every SDK connection authenticates with a short-lived JWT, listens on 127.0.0.1 only, and is bounded by the scopes your app manifest declares. The OS sees your requests; you never see the core.

The cartridges are real — and readable

The apps in MnemoHub aren't black boxes. Each ships its actual src/ (React + the SDK), public and inspectable — clone one as a reference implementation and read exactly how a real app connects to the memory runtime, ingests, and queries the vault through the SDK. Don't learn the SDK from API docs alone — download a working app and copy the patterns. A few live examples:

MIT cartridges are yours to fork and ship anywhere. The Cartridge License is source-available — read it, learn from it, modify it — with one condition: it runs inside the Mnemosyne OS ecosystem.

🧩 Make your own. Scaffold a cartridge from the boilerplate, build it against the SDK, and publish it to MnemoHub — exactly how these were made. From npm create to a signed, installable cartridge, the whole path is yours.

The open ecosystem

The open surface of Mnemosyne OS is MIT-licensed and free to build on:

• Layer-2 SDK (/packages) — the integration surface above: connect apps, build skins, scaffold projects, evaluate against the Gateway.
• MnemoForge CLI (/cli) — the sovereign developer tool: give any AI agent persistent memory, a behavioral identity, and an automated publish pipeline.

npm install -g @mnemosyne_os/forge
mnemoforge

→ CLI Documentation · npm package · Release notes

Why it's safe to build on

The open SDK and the sealed core are separated by a single boundary: the Gateway. Apps speak a public contract; the core's internals are never shipped to, or reachable from, third-party code.

flowchart TB
    subgraph Renderer["Renderer Process (React)"]
        UI["React 18 · TypeScript strict · Vite<br/>i18next (EN/FR/ES) · 30+ lazy-loaded routes"]
    end

    subgraph Bridge["contextIsolation: true · nodeIntegration: false"]
        CB["Context Bridge<br/>400 Zod-validated IPC channels"]
    end

    subgraph Main["Main Process (Electron)"]
        SVC["Services: AI · Vault · Drive · Workspace<br/>Shadow · Window · Network · FGAC · Scheduler"]
    end

    subgraph Net["Sovereign network (127.0.0.1 only)"]
        SDKWS["SDK WebSocket"]
        MCP["MCP server"]
    end

    subgraph Chain["Base L2 — on-chain"]
        ENGRAMM["Engramm License"]
    end

    UI <--> CB
    CB <--> Main
    Main --> SDKWS
    Main --> MCP
    Main -. verify via Gateway .-> ENGRAMM

    style Main fill:#1a1a2e,stroke:#7c3aed,color:#fff
    style Renderer fill:#0f172a,stroke:#38bdf8,color:#fff
    style Chain fill:#1a1a0e,stroke:#f39c12,color:#fff

The Engramm License

Running Mnemosyne OS is unlocked by an Engramm — named after the engram, the physical trace a memory leaves in the brain. Fitting for a memory OS: it's your own verifiable trace of ownership.

Rather than an account and a monthly subscription, your license lives on-chain (Base), bound to your wallet — not to a machine, not to an email. You hold it, so you own your copy and carry it to any device you want, and anyone can verify it. The same Engramm drives your sovereign pseudonym and cloud credits. Holding it and checking it cost you nothing — see below.

Auth — cold boot / warm boot

A local wallet is the only credential. No account, no password server-side to breach.

No gas fees, no crypto to manage. The chain is plumbing, not a paywall — you never pay a network fee, hold a token, or approve a transaction. Ownership is recorded on Base so it stays publicly verifiable, but every network cost is covered for you. A wallet you never have to think about.

sequenceDiagram
    participant U as "You"
    participant W as "Sovereign wallet (local)"
    participant G as "Gateway"
    participant C as "Base L2 (chain)"
    participant T as "OS keystore"

    Note over U,T: Cold boot (first launch / new machine)
    U->>W: launch the app
    W->>G: signed challenge
    G->>C: verify Engramm on-chain
    C-->>G: does this wallet hold the license?
    G-->>W: signed verdict

    Note over U,T: Arming encryption at rest — separate, and up to you
    U->>W: turn on encryption at rest
    W-->>U: 24-word recovery phrase — confirm it
    U->>W: confirmed
    W->>T: seal the AES-256 key

    Note over U,T: Every launch after
    W->>T: read the sealed key
    T-->>W: key → vaults open encrypted

    Note over W,T: Once armed, physical theft = encrypted SQLite.<br/>Until armed, vaults are local but in cleartext.

Security-first Electron architecture

• contextIsolation: true, nodeIntegration: false on every window
• sandbox: true for web content — relaxed only for the local-AI worker threads, mitigated by context isolation + Zod-validated IPC
• Explicitly declared IPC methods via Context Bridge, validated with Zod + audit logging
• Strict Content Security Policy
• Windows builds code-signed (Certum OV, RFC-3161 timestamped); every release binary carries a Sigstore build-provenance attestation tying it to the exact CI run and commit that produced it

Sovereignty enforced in code

• FGAC governs exactly what an agent — or a third-party app — can read, write, or sync
• 24h TTL on access grants, auto-healing on refresh
• P2P Shadow Sync with alert system and OS notifications
• No telemetry without consent

Stack

• Runtime: Electron 31, Node.js 22
• Frontend: React 18, TypeScript (strict mode), Vite
• State: Zustand with useShallow atomic selectors
• AI Integration: Claude API, Ollama (local LLMs), OpenAI-compatible endpoints
• Testing: Vitest + Testing Library — green CI gate
• CI/CD: GitHub Actions — typecheck + lint + i18n validation + tests

Open-core & Licensing

Mnemosyne OS follows an open-core model: an open, MIT-licensed developer ecosystem built around a proprietary core.

The SDK and MnemoForge CLI are MIT licensed — fork them, build on them, ship your own apps. The Mnemosyne Neural OS platform — the desktop application, Neural Map, MnemoHub, Dream State, Vaults, and associated services — is proprietary software. No part of the platform may be copied, modified, or distributed without explicit written permission from XPACEGEMS LLC.

End-user licensing is separate from the code license above. Running Mnemosyne OS is unlocked per user by the Engramm — an on-chain license bound to your wallet, not a subscription — while the SDK and CLI you build with stay MIT.

Why the core is closed. Everything you need to build is open; what stays sealed is the part that took years of full-time R&D to get right — the memory engines (Spine, Retrieval, Dream State) behind the LongMemEval numbers above. Keeping that core proprietary is what lets an independent lab sustain the project, fund the open ecosystem around it, and grow a team — instead of handing a hard-won engine to anyone who would re-skin it. The trade is deliberate: everything above the Gateway is yours to fork; the engine that makes it worth building on stays ours.

For licensing inquiries: dev@mnemosyne-os.com

Quality

TypeScript errors     : 0   (strict mode, noUncheckedIndexedAccess)
ESLint warnings       : 0
Test suite            : Vitest + Testing Library (green CI)
CI pipeline           : ✅ Green (typecheck → lint → i18n → tests)
Languages             : 3 (EN / FR / ES)
i18n namespaces       : 47
Electron security     : context isolation · Zod-validated IPC · CSP

Development Philosophy

Mnemosyne is built on three principles:

1. Sovereignty — Your data stays local. Your models run locally if you choose. No telemetry without consent. FGAC controls what the AI can and cannot access.

2. Multi-model — No vendor lock-in. Claude, GPT, Gemini, Groq, Mistral, DeepSeek, and MiniMax in the cloud; Ollama or a local GGUF model fully offline; any OpenAI-compatible endpoint on top — switch per task, or let the app route automatically.

3. Agentic by design — Not a chat interface with file upload. A real orchestration layer where multiple AI agents coordinate, with policy enforcement and audit trails.

🔬 Mnemosyne Labs — research, activated

The numbers above are not marketing copy — they are published, citable research artifacts. Mnemosyne Labs is the research arm of the project: methodology in the open, benchmarks anyone can audit, artifacts archived with a DOI.

Artifact	DOI
📄 The Resonance Engine — technical whitepaper v2.1: the architecture behind the engines, consolidation, adaptive selection, the hybrid lexical channel, and the LongMemEval results
🔍 LongMemEval-M audit kit — the scorer, per-question verdicts and honest methodology, packaged so you can audit the claims yourself. This DOI pins the July deposit (the 72.9% campaign); the live kit also recomputes the August one

Both records are open access (CC BY 4.0), cite each other on Zenodo, and are bound to the founder's research identity — ORCID 0009-0009-1087-3917.

→ Mnemosyne Labs · → How to cite this work · → Live audit page

Roadmap

Shipped

• 🚀 Infinity Edition — 22 public releases, now at v1.4.5 · The Locked Door
• 🖼️ Theia — image memory & visual recall — Mnemosyne's sister engine (named for the Titaness of sight) gives every vault an eye: your images are embedded locally (SigLIP 2, no cloud, no API), recall answers with thumbnails under the reply, and a living gallery shows them with categories the engine discovers on its own — categories you can rate, correct, rename or teach, because the human's word always outranks the model's guess. Off by default; one Settings toggle installs, downloads pinned weights and indexes.
• 🧩 MnemoHub — signed cartridge marketplace, community submission pipeline, live publishing
• 🪪 Sovereign identity — claim a public pseudonym bound to your wallet, no account, no password
• 💤 Dream State — a consolidation engine that replays and links your memories while you're away
• 🗜️ Octave — multi-resolution memory compression — the engine behind the compression milestone, aboard since v1.3.8: while you're away, consolidation prepares each memory at several resolutions, so the answer path can carry more memory into a small context window. Strictly extractive — every compressed line is a verbatim excerpt of the original, provable by character offsets, never a paraphrase — and compressed derivatives inherit the exact vault protection of their source. Serving them on the answer path stays off by default until the full benchmark campaign clears it.
• ⚡ MnemoForge CLI v1.4.7 on npm — @mnemosyne_os/forge · Soul Protocol · Canvas Rules · Chronicle System · MCP Server
• 🌱 Public beta — v1.1.0-beta.1 — where it started (personality-profile builder, semantic memory graph, first-contact onboarding)

What's next

• 🗜️ Context compression, on by default — the Octave engine is already aboard (see Shipped): while your machine is idle, every memory is prepared at several resolutions — strictly extractive, offset-provable, never a paraphrase. What remains is serving those compressed forms on the answer path for everyone, gated behind the full measurement campaign, so a lifetime of accumulated memory stays cheap to carry into the small context windows of on-device models. Memory that keeps growing must stay cheap to carry — this is what keeps Mnemosyne sovereign on modest hardware.
• 📱 Mobile companion app — take notes and reach Mnemosyne OS running on your desktop remotely: capture on the go, sync back into your local vault, chat with your own memory away from the machine
• 🔗 Synaptic P2P — a sovereign libp2p mesh (mnemosync-p2p) so your Mnemosyne can reach a trusted peer's directly: no cloud relay, no VPS, no account. Built for teams who want to share a deliberate slice of memory (an architecture decision, an API contract, a chronicle) without exposing the rest — and, eventually, direct messages between instances. Authentication reuses your existing sovereign wallet; nothing leaves your vault unless you explicitly publish it.
• 👥 Team features — shared vaults, multi-agent coordination
• 🖥️ Self-hosted sync server
• 🕸️ Permaweb archival — pay-once, permanent memory storage on Arweave, no subscription and no server that can disappear. Psyche (souls for any AI agent) is the vehicle; bringing it into Mnemosyne OS as a cartridge is the path to making permanent archival a native option for chronicles, and eventually vault backups
• 💰 Creator economy — paid visibility for cartridges, revenue flowing back to builders

About

XPACEGEMS LLC — Independent AI software lab
Headquarters: 2932 NW 72 AVE, Miami, FL 33122, USA
Founder & Lead Architect: Tony Trochet
Product: mnemosyne-os.io — downloads, docs, build on it
Company: mnemosyne-os.com — press, research, Labs
Documentation: docs.mnemosyne-os.io — every engine, step by step
LinkedIn: Tony Trochet
GitHub: @yaka0007

Built through Neural Coding — human-architected, with Claude (Anthropic), Antigravity (Google DeepMind), and Cursor directed as instruments.

📰 What's new

A new build ships most weeks. Windows builds are code-signed (Certum OV, RFC-3161 timestamped) and auto-update once installed.

→ All releases

✍️ From the blog

The longer stories behind the releases and the campaigns, on the product site:

• A multiplier cannot rescue a zero — dense embeddings can't hear a rare proper noun. What worked: a second, fully local ranking fused by rank — with two reproduced runs, a 48-question holdout, and every number auditable.
• 72.9% — and the three questions we miss — LongMemEval on the full-haystack variant, the one nobody shows: the number, the protocol, the levers we refuted, and the misses we own.
• We gave personality control of memory. It cost 31 points. — the most seductive feature we built this year made retrieval measurably worse; the ablation, and why personality shipped as a costume.
• Present is not the same as loadable — a package can be there, at the right version, and still be unreachable to the code that imports it.
• The memory my brain kept asking for — why this OS exists: not a product, a prosthesis for a brain that ran too fast for the world. (original in French)

→ All posts