mnemo — a standalone STM/MTM/LTM memory engine for file-based agents

One engine, many banks: deterministic scripts + skills that give any agent harness a tiered, navigable, self-consolidating memory — without rewriting a single file of the documentation it indexes.

Status: alpha. Running in production use daily, but conventions and interfaces may still change. Homepage: docs/index.html (https://stochasticentropy.github.io/mnemo/ once Pages is live).

Why

Agent sessions are amnesiac (Karpathy: "a coworker with anterograde amnesia"), and file-based agent memory left alone only accumulates: duplicates drift, facts go stale, indexes bloat until the rules drown in their own context — and what IS loaded still gets ignored under pressure. Measured in a real multi-agent development setup, that meant the same corrections re-taught within days, knowledge sitting one file-read away yet never found, and per-directory memory forks that never merged. mnemo treats memory as a system with a metabolism instead of a landfill.

How it works

Human memory is the blueprint, taken seriously rather than decoratively:

• Layers: session context = working memory; a per-project capture inbox = hippocampal scratchpad (agents keep writing memories exactly as their harness already does); curated bank notes = episodic store; guidelines/corpora + CORE rules = semantic store; a grep-able archive = remote memory (nothing is ever deleted).
• Navigation, not loading: a hard-budgeted always-loaded L0 (trigger-phrased CORE rules + a task→hub ROUTING table + working-state NOW) routes to hub notes, which route to leaves — every fact reachable in ≤3 file reads, link-audit enforced. No embeddings, no servers: plain files, git, and an LLM that can read.
• Sleep ("dream mode"): scheduled offline consolidation — replay recent session transcripts, sweep the inbox, dedup/merge, decay cold notes to the archive, spot-verify stale facts, re-link ("fire together, wire together"), re-index — plus a weekly REM pass that recombines distant notes into general lessons. Promotion across the project→general boundary is sanitizing: the abstracted lesson moves up, the confidential evidence stays behind a deny-list-gated wall (enforced pre-commit and on export).
• Enforcement over prose: rules that agents rationalize past become gates — done_gate (completion requires a fresh independent-judge artifact, not a claim), blocked_gate ("blocked/unknown" requires the exhaustive search to have actually run), confidentiality_gate.

Proven in first deployment (as of 2026-08-24)

• 93 dream runs across two live banks, each leaving an auditable report; nightly runs fully unattended (launchd), latest report from last night.
• Always-loaded context cut ~4× (≈17K → ≈4K tokens measured) while every note stayed reachable in ≤3 file reads.
• One memory across a whole fleet: 11 working copies and two different agent CLIs (Claude Code + Codex) share the same banks — the per-directory memory forks are gone by construction.
• First fully autonomous dream was judge-verified end-to-end before scheduling was armed; an ops dashboard (static + live server) watches run health.

Contents

• SPEC.md — the normative conventions (layer model, bank layout, metadata, hop contract, wiring, dream contract). Start here.
• engine/ — deterministic helpers (stdlib-only with an optional PyYAML fast-path; no LLM inside): shared banklib.py; bank_init.py, link_audit.py, manifest_hash.py, confidentiality_gate.py, replay_extract.py, index_build.py, usage_bump.py, metrics.py; enforcement hooks done_gate.py, blocked_gate.py, now_reminder.py; scheduling schedule_dreams.sh + dream_runner.sh (full dream via an authenticated CLI, else a mechanical light pass with a pending-triage queue); publication publish_export.sh — assembles the engine's publishable surface and runs the confidentiality gate over it.
• skills/ — dream (offline consolidation, "sleep") and mem-status (health check). Install once per machine by symlinking each into your agent harnesses' user-level skills dirs.

Quick start: python3 engine/bank_init.py ~/memory-banks/<name> --name <name> --kind project --general ~/memory-banks/general, author CORE/ROUTING, add the L0 import line to the scope's agent-instructions file, register corpora in bank.yaml, schedule the dream. Details: SPEC.md §10.

PLAN.md/NOW.md are this repo's project-history documents, outside the publishable surface (see SPEC.md §1).

Dev hygiene: git config core.hooksPath .githooks wires the pre-commit confidentiality gate (the engine must stay domain-free).

Dashboard

Two delivery modes, same renderer:

• Static: engine/dashboard_build.py → <banks-root>/dashboard.html (regenerated by every dream run).
• Server: engine/dashboard_serve.py — stdlib HTTP service with the live page (/), a JSON API for mission-control integration (/api/data.json), readable dream reports (/report/<bank>/<file>.md), and /health. Install as a KeepAlive service: sh engine/serve_install.sh (default binds 127.0.0.1:8377; add --host 0.0.0.0 on an always-on machine you reach over the LAN — the page contains your banks' content, so only expose it on networks you trust). Uninstall: serve_install.sh --uninstall.

Multiple machines (e.g. an always-on host)

The pieces are machine-portable by construction: the engine is a clone, banks are self-contained git repos, schedules and the dashboard service install per machine. Recommended split until real bank-sync is designed:

• Dashboard/server → run on the always-on host (serve_install.sh --host 0.0.0.0), banks synced to it read-only (e.g. git clone/pull from the working machine, or a bare repo the working machine pushes to).
• Dreams stay where the session transcripts live — replay reads the local ~/.claude/projects dirs, so the machine you work on is the one that can consolidate its sessions. Moving dreaming to another host requires syncing transcripts or per-machine dreaming into a shared bank remote (conflict-safe merge design) — treat that as its own small project, not a config flag.