Quick Start

🚀 Fastest path — the free-backend Quickstart. Two commands to durable, MCP-accessible agent memory on a free database. It's built around IBM Db2 12.1.5 — the reference deployment for the "mnemos on Db2" IBM TechXchange write-up — but the exact same image and steps run unchanged on Oracle Database 23ai Free, PostgreSQL + pgvector, or MariaDB 11.7+. Pick a backend in quickstart/docs/BACKENDS.md; we lead with Db2, it works with all of them.

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. 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

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:

3. Webhooks + integrations

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, 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.

Documentation

License

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

Build infrastructure & partners

Continuous integration and package distribution for this project are generously supported by our open-source infrastructure partners:

• GitLab — canonical source hosting and CI pipelines (format / lint / test gates), via the GitLab for Open Source program.
• Buildkite — CI/CD orchestration with hosted macOS and Linux agents, and our APT package registry host (packages.buildkite.com/ncz-os/ncz), via the Buildkite Open Source program.

Thank you to both for backing open-source software.