mnemos: Instructions file for Codex

AGENTS.md — machine-readable install guide for MNEMOS

This file lets an automated agent install/deploy MNEMOS for an operator given a requested set of modules, deterministically. Human guide: docs/INSTALL.md.

The pip package is mnemos-core. mnemos is an image name, not a pip package — never run pip install mnemos or pip install mnemos-os.

---

Governing rule — ABC-first persistence

MNEMOS has an ABC persistence layer for storage. It is not a style preference; it is the contract that makes "six backends" a real claim instead of five backends plus one and a half. Work must respect both layers:

1. Repository ABCs declared in mnemos/persistence/base.py (MemoryRepository, KGRepository, VersionRepository, CompressionRepository, WebhookRepository, and the rest — see the file).
2. A per-backend facade — SqliteBackend, PostgresBackend, OracleBackend, Db2Backend, MysqlBackend, MariadbBackend — which owns those repositories and advertises capability through its supports_* flags.

A new or repaired storage capability is delivered as: ABC method → implementation on all six backends → facade exposure → route calls the ABC.

Raw _lc._pool access outside mnemos/persistence/ is the defect, not the shortcut. require_postgres_pool_or_503 is a symptom of the same mistake and is removed by routing through the ABC, never by deleting the guard.

This is enforced in CI by a ratchet guard — lint:abc-first runs python3 scripts/check_abc_first_guard.py against the committed per-file baseline tests/abc_first_baseline.json. The guard fails when an in-baseline file's raw _lc._pool count goes UP or a new file gains one; it never fails on a reduced count. Remove a reference, then re-run the script with --regen to record the lower count. Full rule text: docs/FEATURES_TO_BE_DONE.md §0b (F-14).

---

Module registry

# id -> how to obtain it. Subsystems share the mnemos.* namespace and are
# external subsystems are runtime-gated; CHARON portability and STYX are core.
modules:
  core:       { dist: mnemos-core,     extra: null,       kind: kernel,   arch: [amd64, arm64] }
  graeae:     { dist: mnemos-graeae,   extra: graeae,     kind: router,   arch: [amd64, arm64] }
  pantheon:   { dist: mnemos-pantheon, extra: pantheon,   kind: router,   arch: [amd64, arm64] }
  knemon:     { dist: mnemos-knemon,   extra: knemon,     kind: router,   arch: [amd64, arm64] }
  charon:     { dist: mnemos-core,     extra: null,       kind: core-router, arch: [amd64, arm64], note: "first-party MIF/MPF portability, ingest, adapters, and STYX; Docling conversion needs the docling extra" }
  stiphos:    { dist: mnemos-stiphos,  extra: null,       kind: service,  arch: [amd64, arm64], port: 8080, note: "separate service, not in the everything image" }

backends:           # selected at RUNTIME via MNEMOS_DATABASE_DSN, not by image
  sqlite:   { driver: bundled,  dsn: "sqlite:////data/mnemos.db", arch: [amd64, arm64], default: true }
  postgres: { driver: asyncpg,  dsn: "postgres://USER:PASS@HOST:5432/DB", arch: [amd64, arm64] }
  oracle:   { driver: oracledb, extra: oracle, dsn: "oracle://USER:PASS@HOST:1521/SERVICE", arch: [amd64, arm64], thin: true }
  db2:      { driver: ibm_db,   extra: db2,    dsn: "db2://USER:PASS@HOST:50000/DB", arch: [amd64], note: "no arm64 Linux wheel exists and the sdist fails to build there; every other backend, including oracle, is arm64-clean (verified 2026-09-10, O6N, incl. a live query against a real production Oracle DB)" }
  mysql:    { driver: aiomysql, extra: mysql,  dsn: "mysql://USER:PASS@HOST:3306/DB", arch: [amd64, arm64] }
  mariadb:  { driver: aiomysql, extra: mysql,  dsn: "mariadb://USER:PASS@HOST:3306/DB", arch: [amd64, arm64] }

accelerators:       # OPTIONAL embedder accel; default is portable CPU llama-cpp
  openvino: { extra: openvino, arch: [amd64] }          # Intel x86-only
  cuda:     { extra: cuda,     arch: [amd64, arm64] }    # needs PyTorch CUDA index
  amd:      { extra: amd,      arch: [amd64] }           # ROCm, linux-only

images:
  mnemos-enterprise: { ref: "ghcr.io/ncz-os/mnemos-enterprise", contains: [core, graeae, pantheon, knemon, charon, oracle, mysql], contains_amd64_only: [db2], arch: [amd64, arm64], port: 5002, note: "the ONLY published container image (operator directive 2026-09-10) — a single multi-arch OCI manifest under one tag, not two images; docker/podman pull automatically resolves the right platform layer. The mysql driver (aiomysql) also serves the mariadb backend. Db2 support is present on the amd64 layer only — see the db2 backend note above." }