📍 Canonical source: GitLab

The authoritative source for this project lives on GitLab — always: https://gitlab.com/ncz-os/mnemos

This GitHub repository is retained only to host the mnemos-enterprise container image on ghcr.io. Development, issues, and merge requests happen on GitLab.

MNEMOS v6.4.1 is the memory operating system for serious agentic work. It 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.

What is in the box:

• a packaged FastAPI runtime with a CLI-first deployment surface
• EPIMONE, the six-backend persistence layer — SQLite + sqlite-vec by default, PostgreSQL + pgvector, Oracle AI Database 26ai, IBM Db2 12.1, MySQL 9.0 Enterprise/HeatWave, and MariaDB 11.7+. Every backend self-provisions its schema on first connect. See Persistence.
• the GRAEAE reasoning bus and PANTHEON unified LLM facade
• an operator-audited compression stack
• a divergent dream-state pipeline: REPLAY → CLUSTER → CONSOLIDATE → SYNTHESISE → EXTRACT
• a GDPR right-to-be-forgotten worker
• the PERSEPHONE archival subsystem
• KRONOS recall observability

How it is packaged. MNEMOS ships as a small core (mnemos-core) plus separately installable mnemos.* namespace subsystems (GRAEAE, PANTHEON, KNEMON, CHARON) and the standalone STIPHOS hive service. The published container image is ghcr.io/ncz-os/mnemos-enterprise — a single multi-arch (amd64 + arm64) manifest with every backend driver (Oracle, MySQL, MariaDB) except Db2, which is amd64-only. Pin the minor line (:6.3) to keep a fleet on identical code. Install and DSN/driver setup for each backend are in docs/INSTALL.md; the agent-facing contract is in AGENTS.md.

🚀 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 — the reference deployment for the "mnemos on Db2" IBM TechXchange write-up — but the exact same image and steps run unchanged on Oracle AI Database 26ai 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.

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-enterprise: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):

None of mnemos-core, mnemos-graeae, mnemos-pantheon, mnemos-knemon, mnemos-charon, or mnemos-stiphos are currently published to PyPI. pip install 'mnemos-core[...]' will 404 — the [server]/[full] extras recurse into these names on the public index. Until they're published, install from source. This exact sequence is tested in a clean venv:

# Core (arch-neutral, no openvino):
git clone https://gitlab.com/ncz-os/mnemos && cd mnemos
python -m pip install -e .

# Add-ons, straight from GitLab — core's already-installed version satisfies
# each add-on's own mnemos-core floor, so pip resolves it locally and never
# needs to reach PyPI for mnemos-core itself:
pip install 'git+https://gitlab.com/ncz-os/graeae.git'
pip install 'git+https://gitlab.com/ncz-os/knemon.git'
pip install 'git+https://gitlab.com/ncz-os/pantheon.git'   # needs graeae + knemon installed first
pip install 'git+https://gitlab.com/ncz-os/charon.git'

mnemos init                         # scaffold config + token
mnemos serve                        # start API on :5002
mnemos doctor                       # verify subsystems
# Set MNEMOS_BASE=http://localhost:5002 and MNEMOS_API_KEY=<token from mnemos init>
# in shell env and any agent config that needs to reach it.

# Hive (STIPHOS) is a SEPARATE service, same pattern:
git clone https://gitlab.com/ncz-os/mnemos-stiphos && cd mnemos-stiphos
pip install -e '.[mcp]'   # port 8080

Run pip check afterward as a sanity check — a clean install reports "No broken requirements found." Anything it does report is a real gap; install it.

Edge device (SQLite kernel only): after the core install above, pip install aiosqlite sqlite-vec (the [edge] extra's own two deps — both real, published packages, unaffected by the above).

Enterprise backends (Oracle AI Database 26ai, IBM Db2 12.1). mnemos-enterprise is a single multi-arch (amd64 + arm64) image with every backend driver baked in. The one asymmetry: Db2's driver has no arm64 wheel, so the Db2 backend is amd64-only — Oracle (thin driver), MySQL, and MariaDB all work on arm64 too. 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 (see the "pip (compose your own)" section above for the
# add-on install order — enterprise adds the same set plus the driver extra
# on core itself):
git clone https://gitlab.com/ncz-os/mnemos && cd mnemos
python -m pip install -e '.[enterprise]'   # or '.[oracle]' / '.[db2]' — core's own extras, real PyPI deps
pip install 'git+https://gitlab.com/ncz-os/graeae.git'
pip install 'git+https://gitlab.com/ncz-os/knemon.git'
pip install 'git+https://gitlab.com/ncz-os/pantheon.git'
pip install 'git+https://gitlab.com/ncz-os/charon.git'
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, which listens on :5003 by default.

Key MCP tools the agent gets:

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. GRAEAE handles multi-provider reasoning and model routing; MOIRAI handles operator-audited compression through APOLLO and ARTEMIS.

The backend is chosen at runtime by DSN scheme, never by rebuild. Six are implemented, in mnemos/persistence/:

Every backend satisfies the same PersistenceBackend protocol set (mnemos/persistence/base.py) and self-provisions its schema idempotently on backend.open(), DSN-aware, with the dimension taken from MNEMOS_EMBEDDING_DIM. SQLite and PostgreSQL share the cross-backend harness in tests/test_persistence_parity.py; Oracle, Db2, MySQL, and MariaDB are each covered by their own live suite.

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

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.