MNEMOS v6.0.0 is the memory operating system for
serious agentic work: a packaged FastAPI runtime, EPIMONE — the six-backend
persistence layer (SQLite + sqlite-vec by default, PostgreSQL + pgvector,
Oracle Database 26ai HNSW INMEMORY NEIGHBOR GRAPH, IBM Db2 12.1.5 (EAP) DiskANN
vector, MySQL 9.0 Enterprise/HeatWave VECTOR_DISTANCE, and MariaDB 11.7+
native VEC_DISTANCE_COSINE + HNSW — every backend self-provisions its schema
on first connect), 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.
v6.0.0 — the split-distribution release. MNEMOS is now a small core (
mnemos-core) plus separately installablemnemos.*namespace subsystems (GRAEAE, PANTHEON, KNEMON, CHARON) and the standalone STIPHOS hive service. It adds Oracle Database 26ai and IBM Db2 12.1.5 (EAP) as first-class persistence backends alongside PostgreSQL and SQLite. Turnkey container images are published toghcr.io/ncz-os(mnemos-core,mnemos,mnemos-enterprise,mnemos-stiphos); see docs/INSTALL.md and AGENTS.md. Enterprise backend driver, DSN, and migration steps are in docs/INSTALL.md. Development history continues on thefeat/oracle-portbranch.
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.
Paste into Claude Code, Cursor, or Codex. The agent runs the install; you confirm. Agents should read AGENTS.md — it has the machine-readable module registry and a deterministic procedure for installing exactly the requested modules on the operator's arch + backend.
The pip package is mnemos-core (the subsystems are separate dists pulled
via extras). mnemos is the published image name, not a pip package.
Turnkey (container, any arch):
docker run -p 5002:5002 -v mnemos-data:/data ghcr.io/ncz-os/mnemos:latest
# everything image: core + graeae + pantheon + knemon + charon. SQLite by default.
# Point at a real DB with -e MNEMOS_DATABASE_DSN='postgres://…' (or oracle://… thin).
pip (compose your own):
Install MNEMOS on this machine.
Steps:
1. pip install 'mnemos-core[server]' # everything; arch-neutral (no openvino)
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 kernel only): pip install 'mnemos-core[edge]'
Single subsystem, e.g. reasoning: pip install 'mnemos-core[graeae]'
Hive (STIPHOS) is a SEPARATE service: pip install 'mnemos-stiphos[mcp]' (port 8080)
Enterprise backends (Oracle Database 26ai, IBM Db2 12.1.5 EAP).
Turnkey is the amd64-only mnemos-enterprise image (everything + Oracle/Db2/
MySQL drivers baked in). Note: Oracle uses the thin driver, so it also runs on
the plain mnemos image and on arm64 — only Db2 actually requires enterprise.
See docs/INSTALL.md
for full driver, DSN, and migration steps.
# Turnkey (amd64):
docker run --platform linux/amd64 -p 5002:5002 \
-e MNEMOS_DATABASE_DSN='db2://user:pass@host:50000/dbname' \
ghcr.io/ncz-os/mnemos-enterprise:latest
# Or from source:
git clone https://github.com/ncz-os/mnemos && cd mnemos
python -m pip install -e '.[server,enterprise]' # or '.[server,oracle]' / '.[server,db2]'
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
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 |
list_deletions |
List soft-deleted memories pending hard deletion |
| 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/
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, MySQL 9.0+ (native VECTOR + VECTOR_DISTANCE — note these functions ship only in MySQL Enterprise/HeatWave, not Community) for the managed-cloud MySQL audience (RDS/Aurora MySQL, HeatWave), and MariaDB 11.7+ (native VECTOR columns, VEC_DISTANCE_COSINE/VEC_FromText, HNSW VECTOR INDEX — all in the free Community edition, embeddings stored in a memory_embeddings join table) as the default open-source/self-hosted vector backend for the MySQL family. All six backends implement the same PersistenceBackend ABC (mnemos/persistence/base.py), self-provision their schema idempotently on backend.open() (DSN-aware, dimension from MNEMOS_EMBEDDING_DIM), and share tests/test_persistence_parity.py. Recommended default for vector/semantic workloads: PostgreSQL + pgvector — the most mature, predictable, and well-scaled vector store (HNSW, broad managed-service support); MariaDB is the strongest MySQL-family option but its vector engine is newer/less battle-tested. GRAEAE handles multi-provider reasoning and model routing; MOIRAI handles operator-audited compression through APOLLO and ARTEMIS.
| 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 (MIF 1.0; MPF legacy) | 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. |
MNEMOS is licensed under the Apache License, Version 2.0. See LICENSE for the full text.