genesis-memory

Why

Every AI coding agent has the Goldfish Effect: each session starts from nothing. Decisions, invariants, half-finished threads and hard-won debugging insight evaporate. You repeat yourself; the agent re-reads 80k tokens of test output; your bill grows.

GENESIS is a local-first cognitive memory OS that sits between your agents and their models:

Everything is stdlib-only Python, runs under 100 MB RSS, stores to one WAL-mode SQLite file, and never phones home.

Related MCP server: memento

Quick start

pip install genesis-memory          # or: git clone … && pip install -e .

genesis setup --preview             # read-only: what is installed, what would be wired
genesis setup --yes                 # wire every detected client (timestamped backups; --revert undoes)

genesis dashboard --open            # Mission Control at http://127.0.0.1:8090
genesis run -- pytest tests/        # headless, spooled, exit-code preserving
genesis doctor                      # system diagnostics, client matrix & update check
genesis upgrade                     # 1-click self-upgrade to the latest release

Anything not auto-detected:

genesis clients                                     # the universal matrix with detection status
genesis export-config --client zed --format native  # exact snippet in the client's own dialect
genesis export-config --format toml                 # canonical mcpServers as TOML / yaml / json / env / lua / elisp
genesis export-config --all --out ./snippets        # one file per client

Universal client support

genesis setup is a data-driven registry (genesis_memory/cli/client_registry.py): each client declares where its config lives, how to detect it, which primitives it supports and how to render the patch in its own dialect. JSON/JSONC files are deep-merged (your existing servers and comments survive); YAML/TOML/Lisp/dotenv files get an idempotent >>> genesis-memory >>> marker block that re-runs replace and --revert removes.

# Zero code changes for any framework: point the base URL at the gateway.
from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8000/v1", api_key="not-needed")

Architecture

flowchart LR
  subgraph Clients["20 AI clients · any SDK"]
    C1[Cursor] --- C2[Claude Code] --- C3[VS Code / Zed / JetBrains] --- C4[Neovim / Emacs] --- C5[LangChain · CrewAI · …]
  end
  Clients -- "stdio MCP (19 tools)" --> D[genesis-daemon<br/>&lt;100 MB RSS · stdlib only]
  Clients -- "pre-prompt hook<br/>≤200-token capsule" --> H[subconscious_hook.py]
  Clients -- "OPENAI_BASE_URL / ANTHROPIC_BASE_URL" --> P[genesis-proxy :8000<br/>/v1/chat/completions · /v1/messages]
  D & H & P --> S[(memory.db<br/>SQLite WAL · busy 5000ms<br/>BEGIN IMMEDIATE + retry)]
  R[genesis run<br/>headless spooler] -- "redacted bytes" --> SP[(~/.genesis/spool<br/>TTL 7d · LRU 500MB)]
  S --> SL[sleep daemon<br/>Hebbian decay · skills · digest]
  S & SP & P --> M[Mission Control :8090<br/>SSE telemetry · read-only]
  PS[[Privacy Shield<br/>15 patterns + Shannon entropy]] -.guards.-> S & SP

Repository layout

genesis_memory/
├── core/
│   ├── db.py                 # WAL + busy_timeout + BEGIN IMMEDIATE + jittered retry (shared by every process)
│   ├── privacy_shield.py     # structural patterns + Shannon-entropy detector; redact()/scan()/redact_bytes()
│   ├── hebbian_engine.py     # stability τ, decay, reinforcement
│   ├── skill_synthesizer.py  # recurring outcomes → procedural skills
│   ├── ast_edge_extractor.py # dependency closure for attest_closure
│   ├── licensing.py          # offline HMAC-SHA256 tiers
│   └── team_sync.py          # enterprise vector-clock sync
├── daemon/server.py          # stdio MCP daemon · versioned schema · lock-storm resilient dispatch
├── hooks/subconscious_hook.py# ≤200-token capsule, ambient turn capture
├── proxy/                    # aiohttp gateway (OpenAI + Anthropic), compactor, distiller, pricing engine (+ bundled catalog)
├── cli/
│   ├── run.py                # genesis CLI · 60+ toolchain headless spooler
│   ├── client_registry.py    # universal data-driven client matrix (20 specs, aliases, dialect renderers)
│   ├── config_formats.py     # dependency-free JSON/YAML/TOML/env emitters + marker-block merger
│   ├── export_config.py      # genesis export-config / genesis clients
│   ├── init_cmd.py           # genesis setup · preview · backup · --revert
│   └── templates/opencode_plugin.js
├── sleep/                    # consolidation cycle, digest, ledger
└── dashboard/                # Mission Control (stdlib HTTP + SSE) and static/index.html cockpit
site/                         # React 19 + Vite 7 landing page with live interactive demos
tests/                        # 421 tests: chaos, concurrency, multi-process, privacy, clients, dashboard, proxy

Capabilities

Lossless headless spooling — genesis run

Wraps 60+ toolchains (pytest ruff mypy black tsc npm pnpm yarn bun deno cargo go dotnet gradle mvn make docker kubectl helm terraform pip uv poetry git gh …) in a strict headless environment (CI=1 TERM=dumb NO_COLOR=1 PAGER=cat GIT_TERMINAL_PROMPT=0 PIP_NO_INPUT=1 …), refuses interactive shapes (git rebase -i, docker run -it, --watch), captures every byte to an atomic spool, prints a ≤10-line summary with a ctx:log/<id> pointer and preserves the exit code. Agents dereference with genesis_log(id, grep=…).

Zero-trust privacy shield

Two independent detectors — 15 structural vendor patterns (OpenAI, Anthropic, Google, GitHub, AWS, Slack, Stripe, SendGrid, npm, Hugging Face, JWT, Bearer, PEM, basic-auth URLs, KEY=value) and a Shannon-entropy gate at 4.0 bits/char for credentials with no known prefix. Git SHAs, URLs, paths and identifiers pass untouched. Applied at remember() (reject), thread/dialogue fields (redact), and the spool before the atomic write (GENESIS_SPOOL_RAW=1 opts out).

Bulletproof SQLite concurrency

Every connection goes through core/db.py: WAL journal, busy_timeout=5000, synchronous=NORMAL, BEGIN IMMEDIATE transaction scope, jittered exponential retry, and read-only URIs for dashboards/reports. The MCP dispatcher rolls back and retries a tool call that loses a write race. The suite runs 8 threads × 25 writes and 4 processes × 15 JSON-RPC calls against one file and asserts zero database is locked.

Stateless gateway — OpenAI and Anthropic

POST /v1/chat/completions and POST /v1/messages both get structural tool-pair compaction, memory capsule injection and streaming passthrough with TTFT preserved. Shadow mode measures without mutating. GET /v1/telemetry, /v1/pricing, /v1/receipts/{id}, /v1/recovery/{id}.

Biomimetic sleep consolidation

Engrams carry a stability τ; retention decays as e^(−age/τ). Reinforcement widens τ, contradiction narrows it, dormant engrams are tombstoned, recurring wins are distilled into skills, and a bounded Active Digest primes the next session.

Mission Control dashboard — genesis dashboard

Zero-dependency cockpit on :8090, streaming /api/stream SSE: token/dollar diet ticker, orbital Memory Universe (drag · zoom · inspect · reinforce), BM25 Engram Explorer with keyboard navigation, Conflict Deck (accept / keep / dismiss), Skill Browser, Hebbian Sleep curves, Client Mesh with live detection, Privacy Shield sandbox, spool & ledger, and a ⌘K command palette. Read-only over WAL; every action is an explicit audited POST.

MCP tools

Set GENESIS_MCP_TOOL_MODE=gateway to advertise only the gateway tool and shrink every-turn schema bytes.

Benchmarks (reference machine, tests/)

Testing

python -m pytest tests/                     # 421 passed, 1 skipped
python -m pytest tests/test_db_hardening.py # multi-thread + multi-process lock storm
python -m pytest tests/test_privacy_shield.py tests/test_universal_clients.py tests/test_dashboard_server.py

Licensing

Source-available under the Business Source License 1.1 (free for individuals, teams under 10, and all non-production use; converts to MIT on 2029-09-11). Versions ≤ v0.6.1 stay MIT forever. See LICENSE.

Offline-first HMAC-SHA256 — works air-gapped.

genesis auth --key GEN-PRO-<key>
genesis license

Links

• RELEASE_CHANGELOG.md — every change in v0.5.0, with rationale and impact

• docs/ARCHITECTURE.md · docs/MCP_SPEC.md · llms.txt · openapi.json

• Landing page: cd site && npm install && npm run build && npm run preview → http://localhost:4173