GENESIS Memory

The persistent brain & token diet for every AI coding agent.

One local SQLite memory shared by Cursor, Claude Code, VS Code, Zed, Windsurf, JetBrains, Neovim, Emacs, OpenCode, Antigravity, every terminal agent and every SDK —
while collapsing 4,000-line tool outputs into 84-token pointers and scrubbing secrets before they ever touch disk.

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.

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

_{GENESIS Memory — because your AI agent deserves a brain that doesn't reset every session.}