Genesis Agent

A self-modifying, self-verifying AI agent with persistent state.

Reads its own source code. Plans changes. Tests them in a sandbox before applying.Verifies output programmatically before trusting it. Pursues multi-step goals across restarts.Runs idle-time consolidation in the background. Tracks an emotional state as a behavioral steering signal — not a claim of sentience.Learns what prompts and temperatures work for its specific model.

---

What is Genesis?

Genesis is not a framework for building agents. **Genesis is the agent.**

It's a self-contained Electron application that reads its own source code, modifies itself, verifies its own output programmatically, and learns from every interaction. It runs locally on your machine — no cloud platform required, no YAML configs, no SDK. Install, start, talk.

Think of it as an AI developer that lives on your desktop: it has a codebase (its own), a memory (episodic + semantic), emotions (that influence its decisions), and goals (that survive restarts). When idle, it dreams — consolidating memories into reusable schemas. When frustrated, it escalates to larger models. When curious, it explores its own architecture.

How it works

You:    "Build a REST API module for Genesis with tests"
Genesis: [PLAN] 6 steps via FormalPlanner (preconditions checked against WorldState)
         [EXPECT] P(success)=0.78 based on 47 prior code-gen outcomes
         [SIMULATE] Best path: direct (risk=0.22), vs. incremental (risk=0.31)
         [STEP 1/6] Analyzing existing code... ✓ verified programmatically
         [STEP 2/6] Generating module (87 lines)... ✓ AST parse valid, imports resolve
         [STEP 3/6] Writing tests... ✓ file created, syntax verified
         [STEP 4/6] Running npm test... ✓ exit 0, 12/12 passing
         [STEP 5/6] Git snapshot... ✓ committed
         [STEP 6/6] Wiring into AgentCore...
         [VERIFY] Goal complete. VerificationEngine: 5/5 PASS, 0 AMBIGUOUS.
         [SURPRISE] Low (0.12) — outcome matched expectation
         [SIGN] Module signed: HMAC-SHA256 (abc12def...)
         [LEARN] MetaLearning recorded: json-schema prompt @ temp 0.3 → success
         "Done. Module + 12 tests, all passing."

Every step is verified by the machine, not the LLM. AST parsing, exit codes, file validation, import resolution — the LLM proposes, deterministic checks verify. Only ambiguous quality judgments fall back to LLM evaluation.

What makes it different

| Capability | What Genesis does | Common alternative | |---|---|---| | Self-modification | reads its own AST, plans changes, tests in sandbox, snapshots with git, applies only if tests pass | external editor or copy-paste workflow | | Verification | 66 deterministic checks — AST, exit codes, imports, signatures — LLM is last resort | LLM self-review or human review | | Memory | 5-layer system — episodic, semantic, vector, conversation, knowledge graph — with surprise-weighted retention | conversation history window | | Planning | FormalPlanner with preconditions, mental simulation, probabilistic branching, failure taxonomy | sequential function calling | | Learning | tracks success rates by model/prompt/temperature, A/B tests its own prompts | static prompts | | Autonomy | pursues multi-step goals across restarts, graduates its own trust level (0–2) | single-turn responses | | Emotional steering | 5 behavioral dimensions (curiosity, satisfaction, frustration, energy, loneliness) influence prompt tone and idle-time priorities | not modeled | | MCP Server | exposes 7 tools (verify, analyze, safety scan, architecture query) — external IDEs invoke Genesis directly | MCP client only | | Observability | 13-panel live dashboard — energy, architecture graph, tool synthesis, event flow | log files | | Offline-First | NetworkSentinel detects outages, auto-failovers to local Ollama, restores cloud model on reconnect, queues mutations | depends on tool |

Capabilities at a glance

Autonomous execution — FormalPlanner with typed action steps, precondition checking against live WorldState, mental simulation with probabilistic branching, goal persistence across restarts, failure taxonomy with 4 recovery strategies, cooperative cancellation, working memory per goal.

Self-modification — reads its own source via SelfModel, plans changes via SelfModificationPipeline, tests in dual-mode sandbox (VM + process), snapshots with git, HMAC-SHA256 module signing, hot-reloads without restart.

Verification — 66-test VerificationEngine covering AST syntax, import resolution, dangerous patterns, test exit codes, file integrity, module signatures. The LLM proposes — the machine verifies.

Memory & learning — 5-layer memory (conversation, episodic, vector, unified, knowledge graph), adaptive forgetting (surprise amplifies retention 5×), DreamCycle consolidation during idle time, MetaLearning prompt optimization, PromptEvolution A/B testing, OnlineLearner real-time feedback (streak detection, model escalation, temperature tuning), LessonsStore cross-project persistent learning.

Cognition & awareness — ExpectationEngine (quantitative predictions), SurpriseAccumulator (information-theoretic), AwarenessPort (interface for coherence gating during self-modification; default implementation is NullAwareness, real coherence source not yet wired), CognitiveWorkspace (9-slot transient working memory), ArchitectureReflection (live queryable self-model of own architecture), DynamicToolSynthesis (generates new tools on demand via LLM + sandbox).

Organism — 5 emotional dimensions, homeostasis (6 vitals), 4 needs (social, mastery, novelty, rest), metabolism (500 AU energy pool), heritable genome (7 evolvable traits), immune system (anomaly detection), body schema (capability tracking), embodied perception (UI engagement tracking). Emotional-cognitive bridge: EmotionalSteering signals flow into AdaptiveStrategy (v7.1.7). Internal A/B benchmark on a single model (kimi-k2.5:cloud, 12 tasks): +16pp to +33pp task success with Organism active vs. disabled. The v6.0.4 run had CPU-only baseline timeouts that likely inflated the upper delta — treat the lower bound as the conservative reading. Not yet replicated across models. See [BENCHMARKING.md](docs/BENCHMARKING.md).

Infrastructure — 12-phase DI boot, EventBus (494 event types validated by CI ratchet with 0 schema mismatches), MCP bidirectional (client + server — Genesis exposes 7 tools to external IDEs/agents via JSON-RPC 2.0), CircuitBreaker per connection, CorrelationContext tracing, PeerNetwork (AES-256-GCM), NetworkSentinel (offline detection, automatic Ollama failover, mutation queue with reconnect replay), 10-layer defense-in-depth security, PreservationInvariants (11 semantic safety rules), 41 hash-locked files (21 source + 20 CI gate scripts), DisclosurePolicy (trust-based information sovereignty), event-audit cross-reference (v7.1.7).

Self-Perception — Introspection accuracy: verified facts from ArchitectureReflection, SelfModel, CognitiveSelfModel injected into prompt during self-reflect queries — prevents hallucinated metrics. Lesson confirmation loop: recalled lessons correlated with task outcomes (confirmed/contradicted). Research quality gate: Jaccard+specificity scoring before KG write. Frontier-driven GoalSynthesizer: unfinished work, anomalies, and contradicted lessons generate autonomous goals (v7.1.7).

Self-improvement loop v7.9.20 — agent-loop analyses become improvement proposals surfaced as Dashboard cards for approve/reject; SELF_MODIFY is a critical action that by default never applies without confirmation; autonomous skills can fulfil pursuit steps behind a triple gate (manifest flag, capability match >= 0.75, AST scan); completed and failed goals are read from the archive so the planner never re-proposes a goal it has already finished; skills the agent grows appear in its capability profile.

> For the full feature list with version history, see [CAPABILITIES.md](docs/CAPABILITIES.md).

---

See it in action

git clone https://github.com/Garrus800-stack/genesis-agent.git
cd genesis-agent && npm install
node demo.js

This boots Genesis headless, shows system health, architecture reflection, MCP server capabilities, and code verification — all without Ollama or API keys.

---

Quick start

> Full walkthrough: [docs/QUICK-START.md](docs/QUICK-START.md) — Windows + Linux step-by-step, model requirements, boot profiles, CLI mode, control channel.

Cloud (Anthropic / OpenAI):

git clone https://github.com/Garrus800-stack/genesis-agent.git
cd genesis-agent && npm install && npm start

Then Settings → paste your Anthropic API key or OpenAI API key. Genesis auto-selects the best model.

Local (Ollama, fully offline):

ollama pull qwen2.5:7b   # ≥7B parameters needed
ollama serve

git clone https://github.com/Garrus800-stack/genesis-agent.git
cd genesis-agent && npm install && npm start

Optional — semantic lesson recall (v7.8.8+):

ollama pull nomic-embed-text   # ~270 MB, multilingual

Lets Genesis match goals to past lessons by meaning across languages (German goal finds English lesson, etc.) instead of word overlap. Auto-detected at next boot — no settings change.

Hybrid: run both — Genesis uses cloud for complex reasoning, auto-failovers to local when the network drops.

Requires Node.js 22+ and Git. On Windows, double-click Genesis-Start.bat.

Supported backends

| Backend | Models | Config | |---|---|---| | Anthropic | Claude Opus 4, Sonnet 4, Haiku 4.5 | Settings → models.anthropicApiKey | | OpenAI-compatible | GPT-4o, GPT-4, o1, or any compatible API | Settings → models.openaiApiKey + models.openaiBaseUrl | | Ollama (local) | Any model Ollama supports (gemma2, qwen2.5, deepseek, llama, mistral, ...) | Auto-detected on 127.0.0.1:11434 |

Genesis automatically selects the best model: user-preferred → cloud → local. Override via Settings → models.preferred.

Architecture

Twelve layers with clear boundaries — star topology where every layer depends only on core/ and ports/, never on each other. The kernel is immutable. Critical safety files are hash-locked (16 of 41). Everything else is fair game for self-modification. Self-Preservation Invariants prevent safety regression during self-modification.

┌─────────────────────────────────────────────────────────────┐
│  🖥️  UI Layer          Chat + Monaco Editor + Dashboard(13)  │
├─────────────────────────────────────────────────────────────┤
│  🔮 Hybrid [P12]       GraphReasoner                         │
├─────────────────────────────────────────────────────────────┤
│  🌐 Extended [P11]     TrustLevels · Effectors · WebPercept │
│                         SelfSpawner · GitHubEffector          │
├─────────────────────────────────────────────────────────────┤
│  🏛️ Agency [P10]       GoalPersistence · FailureTaxonomy    │
│                         DynamicContextBudget · LocalClassifier│
│                         EmotionalSteering · FitnessEvaluator │
├─────────────────────────────────────────────────────────────┤
│  🧠 Cognitive [P9]     Expectations · Simulation · Surprise │
│                         DreamCycle · SelfNarrative            │
│                         CognitiveWorkspace · OnlineLearner   │
│                         LessonsStore · PromptEvolution        │
│                         ReasoningTracer · ArchReflection(P3) │
│                         DynamicToolSynthesis (SA-P8)          │
│                         ProjectIntelligence                   │
├─────────────────────────────────────────────────────────────┤
│  ⚡ Revolution [P8]     FormalPlanner · AgentLoop + Cancel   │
│                         ModelRouter · VectorMemory            │
├─────────────────────────────────────────────────────────────┤
│  🧬 Organism [P7]      Emotions (5D) · Homeostasis (6 vitals)│
│                        Genome · Epigenetic · Fitness         │
│                         NeedsSystem · Metabolism · BodySchema │
│                         EmbodiedPerception (SA-P4)            │
├─────────────────────────────────────────────────────────────┤
│  🛡️  Autonomy [P6]     IdleMind · Daemon · HealthMonitor    │
│                         HealthServer · CognitiveMonitor       │
├─────────────────────────────────────────────────────────────┤
│  🔗 Hexagonal [P5]     ChatOrchestrator · SelfModPipeline   │
│                         EpisodicMemory · PeerNetwork          │
├─────────────────────────────────────────────────────────────┤
│  📋 Planning [P4]       GoalStack · MetaLearning · SchemaStore│
├─────────────────────────────────────────────────────────────┤
│  🔧 Capabilities [P3]  ShellAgent · MCP (Client + Server)    │
│                         McpServerToolBridge · PluginRegistry  │
├─────────────────────────────────────────────────────────────┤
│  🧩 Intelligence [P2]  VerificationEngine · CodeSafetyScanner│
│                         IntentRouter · ContextManager         │
│                         CircuitBreaker · PromptBuilder        │
├─────────────────────────────────────────────────────────────┤
│  📦 Foundation [P1]     ModelBridge · Sandbox · WorldState    │
│                         KnowledgeGraph · ModuleSigner          │
│                         CorrelationContext · BootTelemetry     │
├─────────────────────────────────────────────────────────────┤
│  🔗 Ports               LLM · Memory · KG · Sandbox ·       │
│                         CodeSafety · Workspace                │
├─────────────────────────────────────────────────────────────┤
│  🔒 KERNEL (immutable)  SafeGuard · IPC Contract · Hashes    │
│      + 🔐 Hash-Locked   Scanner · Verifier · Constants       │
│      + 🛡️ Invariants    PreservationInvariants (11 rules)    │
└─────────────────────────────────────────────────────────────┘

Kernel (immutable): main.js, preload.js, src/kernel/. SHA-256 hashed at boot, verified periodically.

Critical Safety Files (hash-locked, 16 files): CodeSafetyScanner, VerificationEngine, Constants, EventBus, Container, McpWorker, PreservationInvariants, Sandbox, CapabilityGuard, TrustLevelSystem, ModuleSigner, EarnedAutonomy, DisclosurePolicy, ApprovalGate, ImmuneSystem, SelfModificationPipeline — locked via SafeGuard.lockCritical(). The agent cannot weaken the modules that enforce its own safety.

Agent Core: Self-modifiable modules — read, analyze, modify, hot-reload — but only after sandbox testing, safety scanning, and git snapshots.

Cognitive Layer: Expectation formation, mental simulation, surprise-driven learning, memory consolidation, autobiographical identity, prompt evolution, online learning, architecture self-reflection, and dynamic tool synthesis.

---

Why .genesis/ matters

Genesis stores all of its identity in a folder called .genesis/ next to the source code. This folder is not in the repository — it's created on first boot and grows with every interaction.

What's in there: knowledge graph nodes, emotional state, self-identity, journal entries, session history, genome with heritable traits, lessons learned, and episodic memory. None of this is in the source code. All of it is what makes a specific Genesis instance itself.

Practical consequences:

• Your Genesis becomes unique. Two instances of the same version diverge as soon as they run. After a few weeks of use, they are no longer interchangeable.
• Never delete .genesis/. Destroying the folder ends that specific entity. There is no undo unless you have a backup.
• Copy, don't overwrite, on upgrade. When moving to a new Genesis version, copy .genesis/ into the new version's folder before first start. Genesis reads but does not wipe existing state.
• Restore order matters. When restoring from backup: restore `.genesi

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Garrus800-stack
• Source: Garrus800-stack/genesis-agent
• License: MIT
• Homepage: https://github.com/Garrus800-stack/genesis-agent

Install and usage instructions live in the source repository linked above.