MNEMOS + GRAEAE

MNEMOS (v6.0-rc — release/v6.0-rc branch, v6.0-rc tag) is the memory operating system for serious agentic work: a packaged FastAPI runtime, four-backend persistence layer (PostgreSQL + pgvector, Oracle Database 26ai HNSW INMEMORY NEIGHBOR GRAPH, IBM Db2 12.1.5 (EAP) DiskANN vector, SQLite + sqlite-vec), GRAEAE reasoning bus, operator-audited compression stack, divergent dream-state pipeline (REPLAY -> CLUSTER -> CONSOLIDATE -> SYNTHESISE -> EXTRACT), GDPR right-to-be-forgotten worker, PERSEPHONE archival subsystem, PANTHEON unified LLM facade, KRONOS recall observability, and CLI-first deployment surface.

MNEMOS is not just a place to put bytes. It is a runtime of named subsystems that manage the full lifecycle of agent memory across providers, agents, and time horizons: write, embed, search, compress, version, reason-over, audit, federate, export, import, and operate.

Release candidate. This README documents the v6.0-rc tag — the canonical release candidate. It adds Oracle Database 26ai and IBM Db2 12.1.5 (Early Access Program) as first-class persistence backends alongside PostgreSQL and SQLite. The most recent published latest published PyPI release is 5.0.1 (legacy); 6.0.0rc1 is the source-install candidate from the v6.0-rc tag (Postgres + SQLite only). Enterprise backends ship from source against the tag until pip extras are published: git clone -b v6.0-rc https://github.com/ncz-os/mnemos. See docs/INSTALL.md for driver, DSN, and migration steps. Development history continues on the feat/oracle-port branch.

Quick Start

Memory and reasoning runtime for AI agents: persistent search, versioned storage, webhook fanout, and a unified LLM routing bus - all behind a single MCP interface.

---

1. Agent-driven install

Paste into Claude Code, Cursor, or Codex. The agent runs the install; you confirm.

Install MNEMOS on this machine.

Steps:
1. pip install 'mnemos-os[server]==6.0.0rc1'  # source-install from v6.0-rc tag until PyPI publish
2. mnemos init                         # scaffold config + token
3. mnemos serve                        # start API on :5002
4. mnemos doctor                       # verify subsystems
5. Set MNEMOS_BASE=http://localhost:5002 and MNEMOS_API_KEY=<token from step 2>
   in shell env and any agent config that needs to reach it.

Edge device (SQLite, no Postgres): pip install 'mnemos-os[edge]==6.0.0rc1' instead.
Full install with all subsystems: pip install 'mnemos-os[full]==6.0.0rc1'

Enterprise backends (Oracle Database 26ai, IBM Db2 12.1.5 EAP). Until the next PyPI release is cut, install from source against the v6.0-rc tag (or the feat/oracle-port development branch) and add the matching extras. See docs/INSTALL.md for full driver, DSN, and migration steps.

git clone -b feat/oracle-port https://github.com/ncz-os/mnemos
cd mnemos
python -m pip install -e '.[server,oracle]'   # or '.[server,db2]' or '.[server,enterprise]'
export MNEMOS_DATABASE_DSN='oracle://user:pass@host:1521/service_name'
# or:  MNEMOS_DATABASE_DSN='db2://user:pass@host:50000/dbname'
mnemos install --profile server
mnemos serve --profile server

---

2. Connect an agent via MCP

Add to ~/.claude/mcp_servers.json (Claude Code) or equivalent:

{
  "mcpServers": {
    "mnemos": {
      "command": "mnemos",
      "args": ["serve", "mcp-stdio"],
      "env": {
        "MNEMOS_BASE": "http://<host>:5002",
        "MNEMOS_API_KEY": "<token>"
      }
    }
  }
}

For HTTP/SSE transport (ChatGPT, remote agents): mnemos serve mcp-http on :5004.

Key MCP tools the agent gets:

Tool	What it does
search_memories	Semantic + filtered search across the memory store
create_memory	Write a new memory with category, tags, and content
get_memory	Fetch a memory by ID
kg_search	Query the knowledge-graph triple store
kronos_anomalies	Surface recall anomalies and memory health signals

---

3. Webhooks + integrations

Integration	What connects	How
Claude Code	Hooks fire on session-start, prompt-submit, stop - auto-log to MNEMOS	integrations/claude-code/ - copy hooks + set MNEMOS_BASE
ZeroClaw	Zeroclaw agent reads/writes memories via MCP	integrations/zeroclaw/ + mnemos serve mcp-stdio in zeroclaw config
OpenClaw	OpenClaw gateway routes memory ops through MCP	integrations/openclaw/ + MCP server entry in openclaw.json
Hermes	Optional memory skill mounts MNEMOS as a tool provider	integrations/hermes/optional-skills/memory/mnemos/
Webhooks (any)	Push memory.created, memory.updated, memory.deleted, consultation.completed events to any HTTPS endpoint	POST /api/webhooks/register with {"url": "...", "events": [...]}
Cursor / Cline / Continue.dev / Zed / Aider	Any MCP-capable IDE connects via stdio or HTTP transport	See docs/connectors/

---

Full documentation: docs/

Architecture

MNEMOS is a packaged FastAPI service with a single mnemos CLI for installation, serving, MCP transport, and operational checks. Agents connect through MCP stdio, MCP HTTP/SSE, REST, or OpenAI-compatible SDKs, while the runtime routes memory, reasoning, session, webhook, federation, portability, and observability work through the mnemos/ package. Persistence is selected by profile and DSN: SQLite + sqlite-vec for edge and development installs, PostgreSQL + pgvector for server deployments, Oracle Database 26ai (23.26.1-ee, HNSW INMEMORY NEIGHBOR GRAPH, JSON Duality, TDE) for enterprise installs, and IBM Db2 12.1.5 (native VECTOR(768, FLOAT32) + DiskANN vector index; runs through Db2 Oracle Compatibility Mode with cursor-level Oracle→Db2 token translation — a native Db2 dialect port is on the v6.x roadmap, see docs/v6.1-roadmap.md. Db2MemoryRepository.semantic_search emits native Db2 SQL — VECTOR_DISTANCE(..., EUCLIDEAN) + FETCH APPROX FIRST — engaging the DiskANN index on the user-facing query path) for enterprise installs. All four backends implement the same PersistenceBackend ABC (mnemos/persistence/base.py) and share tests/test_persistence_parity.py. GRAEAE handles multi-provider reasoning and model routing; MOIRAI handles operator-audited compression through APOLLO and ARTEMIS.

Documentation

Topic	File
Installation	docs/INSTALL.md
Specification	docs/SPECIFICATION.md
System requirements	docs/SYSTEM_REQUIREMENTS.md
Memory architecture	docs/MEMORY_ARCHITECTURE.md
Compression	docs/COMPRESSION.md
GRAEAE reasoning	docs/GRAEAE_FEATURES.md
PANTHEON provider facade	docs/PANTHEON.md
KRONOS observability	docs/KRONOS.md
Portability format	docs/MEMORY_EXPORT_FORMAT.md
Scaling	docs/SCALING.md
Single-binary builds	docs/SINGLE_BINARY.md
Operations	docs/OPERATIONS.md
Benchmark harness	scripts/bench_v4.py — cross-backend vector-search harness (PG / Oracle / Db2 / SQLite). Results published post-GA.

License

MNEMOS is licensed under the Apache License, Version 2.0. See LICENSE for the full text.