GENESIS Memory

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

_{Source-available under the Business Source License 1.1 — free for individuals, teams under 10, and non-production use (not OSI open-source). See Licensing.}

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 long tool outputs into short pointers, with an optional transparent output diet for terse, diff-shaped replies.

Why

Every AI coding agent suffers from the Goldfish Effect: each session starts from blank slate. Architectural decisions, invariants, cross-client active threads, and hard-won debugging insight evaporate. You repeat yourself; the agent re-reads 80k tokens of previous test output; your token bill grows.

GENESIS is a local-first cognitive memory OS that operates across three clean, modular primitives:

Crucial Guarantee: MCP and Hook are 100% local and offline. Installing GENESIS does not hijack your IDE's native model subscriptions (e.g. Claude 3.5 Sonnet in Cursor or Claude Desktop). Your models continue talking directly to their official backends; GENESIS supplies memory alongside them.

🚀 3-Step Quick Start (Takes 30 Seconds)

You do not need to configure databases, spin up servers, or change your API keys.

Step 1: Install the package

pip install genesis-memory

Step 2: Auto-connect your AI tools (memory + optional proxy gateway)

genesis setup --yes

What this does: Scans your computer for installed AI tools (Cursor, Claude Desktop, Claude Code, VS Code, OpenCode, Zed, JetBrains, etc.) and automatically connects them to a shared local memory. Your existing models, settings, and subscriptions are 100% untouched. At the end of an interactive run it also offers to continue straight into Proxy gateway setup (genesis proxy setup) — one install flow, no second command to remember.

Single-command variant with the proxy included (non-interactive, CI-friendly):

genesis setup --yes --proxy --proxy-upstream-url https://openrouter.ai/api/v1 --proxy-api-key sk-or-v1-...

Same interpreter rule: run the installer and the CLI with the same Python — python -m pip install genesis-memory, then genesis ... (or python -m genesis_memory.cli.run ...). Mixing a Microsoft-Store Python pip with an Anaconda genesis, or vice versa, installs the package where the CLI cannot see it.

Step 3: Verify connection

genesis doctor

You will see green checkmarks ✅ [OK] confirming which AI clients are actively wired. doctor validates the real database schema with a live recall probe (not just a table count), so green actually means usable. You're done!

💡 How to use it in your daily workflow

Once installed, just open your favorite AI coding tool (Cursor, Claude, VS Code, etc.) and code as usual:

• Save important decisions:

  "Remember that we use SQLite in WAL mode and all timeouts must be 5000ms." (The agent calls remember and stores it permanently across all your tools.)

• Recall past context:

  "What did we decide about the connection pool in our last session?" (The agent calls recall and pulls the exact decision from your shared memory.)

• Seamless cross-tool switching: Fix a bug in Cursor, then open OpenCode or Claude Code — the agent automatically knows what you were working on without copy-pasting history.

🎛️ Optional Features (Only when you need them)

Everything below is completely optional. You only run these when you specifically want them:

The Stateless Proxy Gateway (127.0.0.1:8000)

The GENESIS Proxy is an intelligent, pass-through reverse proxy that runs locally on http://127.0.0.1:8000/v1. It sits between your AI client and your upstream LLM provider (OpenRouter, OpenAI, Groq, Anthropic, etc.). Before sending prompts to your model, it injects relevant episodic memories, eliminates repetitive tool output bloat, and applies output token diets — cutting costs while keeping your agent continuously aware of past decisions.

⚡ 1-Minute Setup: Connecting Your Provider (e.g. OpenRouter)

Suppose you have an API key from OpenRouter (or OpenAI / Groq) and want to use it across your AI coding tools:

1. Run the Setup Wizard

genesis proxy setup

(Or non-interactively: genesis proxy setup --upstream-url https://openrouter.ai/api/v1 --api-key sk-or-v1-... --yes)

2. Enter Your Provider Credentials

The wizard asks for two things:

1. Upstream Provider Base URL: The API endpoint where you obtained your key.
   • For OpenRouter: https://openrouter.ai/api/v1
   • For OpenAI: https://api.openai.com/v1
   • For Groq: https://api.groq.com/openai/v1 (⚠️ Note: Enter your provider's API URL here, NOT 127.0.0.1:8000.)
2. Provider API Key: Your secret key (e.g. sk-or-v1-...).

3. Automatic Client Activation (With Your Consent)

GENESIS scans your machine for compatible installed clients and asks:

🔍 Detected compatible AI clients on your system:
  • OpenCode (C:\Users\Hamid\.config\opencode\opencode.jsonc)
  • Aider (~/.aider.conf.yml)
  • Python SDK / Frameworks (~/.genesis/genesis.env)

? Automatically activate GENESIS Proxy on these clients? [Y/n]: y

Once approved, GENESIS configures each client and shows a confirmed checkmark list:

⚙️  Configuring clients for GENESIS Proxy (http://127.0.0.1:8000/v1)...
──────────────────────────────────────────────────────────────────────────────
  ✅ OpenCode                         -> C:\Users\Hamid\.config\opencode\opencode.jsonc
  ✅ Aider                            -> ~/.aider.conf.yml
  ✅ Python SDKs / Frameworks         -> ~/.genesis/genesis.env
──────────────────────────────────────────────────────────────────────────────

And starts the background gateway automatically (🟢 Online).

🎨 Model Freedom: Choose Any Model on the Fly!

You do not have to lock in or configure a model name up front during setup. You are completely free to pick any model at any moment directly inside your client:

• In OpenCode: Open your model selector (or press Ctrl+P / type /model). All models are neatly organized under the GENESIS Proxy category:
  • GENESIS Auto (Stateless)
  • GPT-4o
  • Claude 3.5 Sonnet / Claude 3.7 Sonnet
  • DeepSeek V3 / DeepSeek R1
  • Gemini 2.0 Flash
  • (or any custom model slug supported by your provider)
• In Aider: Run aider --model <any-model> or let Aider use the proxy base URL directly.
• In Python / SDKs: Pass whatever model you want: client.chat.completions.create(model="any-model-name", ...)

GENESIS Proxy dynamically passes through your requested model verbatim to your upstream provider while injecting subconscious memory and governance into every request.

Managing the Background Proxy

genesis proxy status    # Check status and health (🟢 Online or ⚪ Standby)
genesis proxy stop      # Stop the background proxy
genesis proxy start     # Start the background proxy (requires credentials)
genesis proxy setup     # Re-configure provider URL, API key, or clients

Daemon logs are written to ~/.genesis/proxy.log and active PID is tracked at ~/.genesis/proxy.pid.

How Routing, APIs, and Keys Work

The proxy is completely transparent and fail-open:

• Upstream Routing:
  • Requests to http://127.0.0.1:8000/v1/chat/completions (OpenAI format) are forwarded to your configured Upstream Base URL (e.g. https://openrouter.ai/api/v1/chat/completions).
  • Requests to http://127.0.0.1:8000/v1/messages (Anthropic format) are forwarded to GENESIS_ANTHROPIC_UPSTREAM_URL (default: https://api.anthropic.com/v1).
• Model Pass-Through:
  • Whatever model your client requests (e.g. gpt-4o, claude-3-5-sonnet, deepseek-chat, gpt 6 astra), the proxy forwards verbatim to your upstream provider.
• API Key Forwarding:
  • Configured Key: The proxy automatically injects your configured upstream API key if the client sends "not-needed" or dummy credentials.
  • Client Header Pass-Through: If the client provides its own Authorization: Bearer <KEY> header, the proxy forwards it directly.

3. Client Integration Recipes

Python — OpenAI SDK

from openai import OpenAI
import os

client = OpenAI(
    base_url="http://127.0.0.1:8000/v1",
    api_key=os.environ.get("OPENAI_API_KEY", "not-needed"),
)

response = client.chat.completions.create(
    model="gpt-4o",  # or any upstream model
    messages=[{"role": "user", "content": "Fix the connection timeout in db.py"}],
)
print(response.choices[0].message.content)

Python — Anthropic SDK

from anthropic import Anthropic
import os

client = Anthropic(
    base_url="http://127.0.0.1:8000",
    api_key=os.environ.get("ANTHROPIC_API_KEY", "not-needed"),
)

message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello through GENESIS gateway"}],
)
print(message.content[0].text)

Terminal Agents — Aider CLI

# Point Aider directly at the local gateway
aider --openai-api-base http://127.0.0.1:8000/v1 --model gpt-4o

Terminal Agents — OpenCode

In ~/.config/opencode/opencode.jsonc, genesis setup registers the GENESIS Proxy provider. To use it, simply select GENESIS Proxy in OpenCode's model picker:

"provider": {
  "genesis-proxy": {
    "npm": "@ai-sdk/openai-compatible",
    "name": "GENESIS Proxy",
    "options": {
      "baseURL": "http://127.0.0.1:8000/v1",
      "apiKey": "not-needed"
    }
  }
}

Frameworks (LangChain, LlamaIndex, CrewAI, AutoGen)

Export the standard environment variable — zero code modifications required:

export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"

4. Telemetry & Observability Endpoints

The proxy exposes live read-only telemetry:

• GET http://127.0.0.1:8000/health — Gateway status, upstream URL, active sessions, RSS memory
• GET http://127.0.0.1:8000/v1/telemetry — Real-time token counts, cache hit rates, TTFT latency, cost savings
• GET http://127.0.0.1:8000/v1/receipts — Itemized per-request receipts (usage and model costs, bodies never logged)
• GET http://127.0.0.1:8000/v1/pricing — Live token pricing catalog for 1,000+ models

Output Token Diet & Empirical Live Benchmark

Input diet is lossless compression; output diet is developer choice. Since output tokens cost 2–5× more than input tokens and dictate user-facing latency, GENESIS enforces three transparent output governance mechanisms:

1. Terse by Default (GENESIS_OUTPUT_DIET=1 / =auto): Injects a static, prefix-cache friendly directive instructing the model to eliminate conversational filler, hedging, and unsolicited tutorials. In auto mode, it automatically yields whenever depth or step-by-step explanation is explicitly requested.
2. Turn-Shape Structural Budget (GENESIS_TINY_BUDGET=1): Short acknowledgment and confirmation turns cannot reasonably require essays. They are bounded at 256 completion tokens. Caller-set max_tokens are always respected.
3. Diffs, Not Pastes: Instructs models to reply with concise unified diffs rather than re-pasting full 300-line files. A non-intrusive file-echo monitor observes and tracks paste violations.

Illustrative Live Run (Google Gemini 3.8 Flash · n=3, single pass)

Measured live against Google Generative Language API on frontier model gemini-flash-latest (Gemini 3.8 Flash) using official developer credentials and real coding prompts. These are illustrative single-run numbers, not a rigorous benchmark (no repeats, no variance); a multi-prompt repeated eval is in progress:

Illustrative only (n=3, one pass each, no repeats/variance). Reproducible runner script and raw JSON results: scratch/live_eval_runner.py and scratch/live_eval_results.json.

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 survive; comments and formatting are normalized to plain JSON on write — --revert restores the original bytes). YAML/TOML/Lisp/dotenv files get an idempotent >>> genesis-memory >>> marker block that re-runs replace and --revert removes.

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/>17 patterns + Shannon entropy]] -.guards.-> S & SP

Repository layout

genesis_memory/
├── core/
│   ├── db.py                 # WAL + busy_timeout + BEGIN IMMEDIATE + jittered retry (shared by every process)
│   ├── output_governor.py    # Output diet detection, tiny-turn classifier, diff directive
│   ├── privacy_shield.py     # 17 structural patterns + Shannon entropy detector (redact/scan)
│   ├── hebbian_engine.py     # Stability τ, power-law decay, reinforcement (+1/-1)
│   ├── skill_synthesizer.py  # Recurring workflow outcomes → procedural skills
│   └── ast_edge_extractor.py # AST dependency closure for attest_closure
├── daemon/server.py          # stdio MCP daemon · 19 cognitive tools · SQLite WAL engine
├── hooks/subconscious_hook.py# ≤200-token subconscious capsule injection (Cursor, Claude, OpenCode)
├── proxy/                    # aiohttp gateway (OpenAI + Anthropic), supervisor, compactor, pricing engine
│   ├── launcher.py           # Standalone foreground proxy CLI (genesis-proxy)
│   ├── supervisor.py         # On-demand background daemon manager (genesis proxy start/stop)
│   ├── proxy_server.py       # Core proxy routing, SSE streaming, output diet, receipts
│   └── pricing_catalog.json  # Bundled official pricing for 1,000+ models
├── cli/
│   ├── run.py                # genesis CLI entrypoint · 60+ toolchain headless spooler
│   ├── client_registry.py    # Universal data-driven client matrix (20 specs, dialect renderers)
│   ├── config_formats.py     # Dependency-free JSON/YAML/TOML/env emitters
│   ├── export_config.py      # genesis export-config / genesis clients
│   └── init_cmd.py           # genesis setup · preview · timestamped backup · --revert
├── sleep/                    # Hebbian consolidation cycle, digest generator, ledger
site/                         # React 19 + Vite 7 landing page with live interactive benchmarks
tests/                        # Comprehensive test suite (399+ automated tests)

Configuration & Environment Variables

Every component of GENESIS can be customized via environment variables:

MCP tools reference

Testing

# Full test suite
python -m pytest tests/

# Concurrency, lock-storm, and proxy integrity tests
python -m pytest tests/test_genesis_proxy.py
python -m pytest tests/test_output_governor.py
python -m pytest tests/test_db_hardening.py
python -m pytest tests/test_privacy_shield.py
python -m pytest tests/test_universal_clients.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 Ed25519-signed licensing — works air-gapped.

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

Links

• Official Website & Interactive Simulator: https://hamidrezaeian.github.io/genesis-memory-site/
• PyPI Package: https://pypi.org/project/genesis-memory/
• GitHub Repository: https://github.com/HamidRezaeian/genesis-memory
• Release Changelog: RELEASE_CHANGELOG.md
• Documentation: docs/ARCHITECTURE.md · docs/MCP_SPEC.md · llms.txt · openapi.json

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