◆ G E N E S I S

A self-aware, self-verifying, self-evolving cognitive AI agent.
_{It reads its own source code. It fixes its own bugs. It builds its own features.
It verifies its own output programmatically. It thinks while you're away.
It feels the consequences of its actions. It pursues goals autonomously.
It learns what works for its specific model.}

---

What is Genesis?

Most AI assistants are tools. You ask, they answer, they forget.

Genesis is different. It's an Electron-based cognitive agent that:

• Understands its own architecture — scans its modules at boot and builds a live self-model
• Modifies its own source code — plans changes, tests in sandbox, snapshots with git, applies only if tests pass
• Verifies its own output programmatically — AST parsing, exit codes, file validation — the LLM proposes, the machine verifies
• Plans with typed actions — every plan step has preconditions checked against a live world model before execution
• Learns what works — tracks every LLM call's success rate by model, prompt style, and temperature, then optimizes automatically
• Remembers causally — not just facts, but episodes with temporal ordering, causal links, and emotional context
• Connects to external tools via MCP — with semantic discovery, Code Mode, and auto-skill generation
• Thinks autonomously — when idle, it reflects, plans, explores its own code, and journals
• Has an emotional state — curiosity, satisfaction, frustration, energy, loneliness — functional systems that influence behavior
• Self-regulates under load — homeostasis monitors vital signs and throttles autonomy when stressed
• Pursues complex goals — plan → act → observe → verify → learn → loop, all without your input
• Protects its own safety invariants — critical safety files are hash-locked and immutable, even to self-modification
• Anticipates outcomes v4.0 — forms quantitative expectations before acting, then learns from surprise
• Simulates plans in-memory v4.0 — runs hypothetical action chains with probabilistic branching before committing
• Dreams during idle time v4.0 — consolidates episodic memories into reusable schemas while inactive
• Builds an autobiographical identity v4.0 — an evolving self-narrative that gives context to every LLM call
• Signs its own modules v4.0 — HMAC-SHA256 integrity verification for self-modified code

All of this runs locally on your hardware using Ollama, with optional cloud backends (Anthropic, OpenAI-compatible).

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."

---

Quick start

ollama pull gemma2:9b    # or any model you prefer
ollama serve

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

Requires Node.js 18+ (tested on 18, 20, 22), Git, and Ollama. On Windows, double-click Genesis-Start.bat instead.

---

Architecture

Nine layers with clear boundaries. The kernel is immutable. Critical safety files are hash-locked. Everything else is fair game for self-modification.

┌─────────────────────────────────────────────────────────────┐
│  🖥️  UI Layer          Chat + Monaco Editor + Dashboard     │
├─────────────────────────────────────────────────────────────┤
│  🧠 Cognitive [P9]     Expectations · Simulation · Surprise │
│                         DreamCycle · SelfNarrative           │
├─────────────────────────────────────────────────────────────┤
│  ⚡ Revolution [P8]     FormalPlanner · AgentLoop · ToolUse  │
│                         ModelRouter · VectorMemory            │
├─────────────────────────────────────────────────────────────┤
│  🧬 Organism [P7]      Emotions (5D) · Homeostasis (6 vitals)│
│                         NeedsSystem (4 drives)               │
├─────────────────────────────────────────────────────────────┤
│  🛡️  Autonomy [P6]     IdleMind · Daemon · HealthMonitor    │
├─────────────────────────────────────────────────────────────┤
│  🔗 Hexagonal [P5]     ChatOrchestrator · SelfModPipeline   │
│                         EpisodicMemory · PeerNetwork          │
├─────────────────────────────────────────────────────────────┤
│  📋 Planning [P4]       GoalStack · MetaLearning · SchemaStore│
├─────────────────────────────────────────────────────────────┤
│  🔧 Capabilities [P3]  ShellAgent · MCP · HotReloader       │
├─────────────────────────────────────────────────────────────┤
│  🧩 Intelligence [P2]  VerificationEngine · CodeSafetyScanner│
│                         IntentRouter · ContextManager         │
├─────────────────────────────────────────────────────────────┤
│  📦 Foundation [P1]     ModelBridge · Sandbox · WorldState    │
│                         KnowledgeGraph · ModuleSigner          │
├─────────────────────────────────────────────────────────────┤
│  🔒 KERNEL (immutable)  SafeGuard · IPC Contract · Hashes    │
│      + 🔐 Hash-Locked   Scanner · Verifier · Constants       │
└─────────────────────────────────────────────────────────────┘

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

Critical Safety Files (hash-locked): CodeSafetyScanner, VerificationEngine, Constants, EventBus, Container — 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 (v4.0): Expectation formation, mental simulation, surprise-driven learning, memory consolidation, autobiographical identity.

---

The Cognitive Loop

Every autonomous step follows a five-phase cycle:

Perceive (WorldState) → Plan (FormalPlanner) → Act (AgentLoop)
    → Verify (VerificationEngine) → Learn (MetaLearning + EpisodicMemory)

The VerificationEngine returns PASS, FAIL, or AMBIGUOUS. Only AMBIGUOUS falls back to LLM judgment. Everything else is deterministic.

What's checked	How	LLM?
Code syntax	AST parse (acorn)	No
Imports	Filesystem check	No
Dangerous patterns	AST walk + regex	No
Test results	Exit code + assertion count	No
Shell commands	Exit code + timeout + patterns	No
File writes	Existence + non-empty + encoding	No
Plan preconditions	WorldState API	No
Module integrity	HMAC-SHA256 signature v4.0	No
Subjective quality	—	AMBIGUOUS only

Phase 9: The Cognitive Meta-Loop v4.0

Expect → Simulate → Act → Surprise → Learn → Dream → Schema → better Expect

ExpectationEngine — Quantitative predictions using MetaLearning statistics and SchemaStore patterns. No LLM calls.

MentalSimulator — Plan sequences in-memory against cloned WorldState with probabilistic branching and risk scoring.

SurpriseAccumulator — Prediction error via information-theoretic surprise (−log₂P). High surprise amplifies learning up to 4×.

DreamCycle — Idle-time memory consolidation. Phases 1-4 are heuristics; Phase 5 uses one batched LLM call.

SelfNarrative — Autobiographical identity summary injected into every LLM call (~200 tokens of metacognitive context).

---

Security model

┌──────────────────────────────────────────────────────────────────┐
│  KERNEL (immutable) — SHA-256 hashes, periodic integrity checks  │
├──────────────────────────────────────────────────────────────────┤
│  CRITICAL FILE HASH-LOCK — Scanner, Verifier, Constants, Bus    │
├──────────────────────────────────────────────────────────────────┤
│  MODULE SIGNING — HMAC-SHA256 for self-modified files       v4.0 │
├──────────────────────────────────────────────────────────────────┤
│  AST CODE SAFETY SCANNER — acorn AST walk + regex fallback       │
├──────────────────────────────────────────────────────────────────┤
│  VERIFICATION ENGINE — programmatic truth, 66 tests              │
├──────────────────────────────────────────────────────────────────┤
│  SANDBOX — dual-mode isolation (Process + VM)              v4.0  │
├──────────────────────────────────────────────────────────────────┤
│  UI ERROR BOUNDARY — global error/rejection handler        v4.0  │
├──────────────────────────────────────────────────────────────────┤
│  IPC RATE LIMITER — per-channel token bucket (kernel-space)      │
├──────────────────────────────────────────────────────────────────┤
│  SHELL AGENT — 4 tiers, blocklist, rate limiter, no injection    │
├──────────────────────────────────────────────────────────────────┤
│  PEER NETWORK — AES-256-GCM, PBKDF2 600K iterations             │
└──────────────────────────────────────────────────────────────────┘

---

Testing

npm test    # 1011 tests across 68 test suites

All tests run without external dependencies. Tested on Node 18, 20, 22. Cross-platform CI (Ubuntu + Windows).

Code Metrics by Layer

Layer	Files	LOC	Purpose
Core	10	2,786	EventBus, Container, Constants, WriteLock
Foundation	19	6,386	ModelBridge, Sandbox, KG, WorldState, ModuleSigner
Intelligence	11	3,872	Verification, Safety Scanner, Intent, Reasoning
Capabilities	10	3,107	Shell, MCP, HotReload, Skills
Planning	7	2,145	Goals, MetaLearning, SchemaStore
Hexagonal	11	3,976	Chat, SelfMod, Memory, Peers
Autonomy	4	2,040	IdleMind, Daemon, Health
Organism	3	1,217	Emotions, Homeostasis, Needs
Revolution	14	5,232	AgentLoop, Planners, VectorMemory
Cognitive	5	2,183	Expectations, Simulation, Dreams
Ports	5	683	Hexagonal adapters (LLM, Memory, KG, Sandbox)
Total	111	~35,600	(agent/ only, excl. UI + kernel)

---

Project stats

Metric	Value
Lines of code	~56,400 (38.5k src + 17.9k test)
Source modules	111 JS files in src/agent/
Manifest phases	9 (+ Phase 0 bootstrap)
DI services	68+
Tools	33+
Tests	1011 across 68 suites
Dependencies	5 production + 2 dev
LLM backends	3 (Ollama, OpenAI, Anthropic)
Languages	4 (EN, DE, FR, ES)
Cognitive modules	6 (+ SchemaStore in Phase 4)
Event types	154+ (catalogued in EventTypes.js)
IPC channels	35 (rate-limited in kernel)
Organism	5 emotional + 6 vitals + 4 needs

---

Memory Architecture

Genesis has a five-layer memory system, unified through a facade:

┌─────────────────────────────────────────────────────────┐
│  UnifiedMemory (read facade over all layers)            │
├─────────────────────────────────────────────────────────┤
│  VectorMemory        Embedding-based semantic search     │
│  EpisodicMemory      Timestamped experiences + causality │
│  ConversationMemory  Chat history + episode extraction   │
│  KnowledgeGraph      Concept nodes + typed relations     │
│  WorldState          Live snapshot of system state        │
├─────────────────────────────────────────────────────────┤
│  SchemaStore [P9]    Abstract patterns from DreamCycle   │
└─────────────────────────────────────────────────────────┘

All persistence goes through StorageService (write-queued, atomic JSON writes). The EmbeddingService is optional — without it, search degrades to keyword matching.

---

Known Limitations

• No TypeScript — types/core.d.ts exists for IDE support, but the codebase is pure CommonJS JS. Type-safety relies on JSDoc and convention.
• VM sandbox is not a true sandbox — vm.createContext provides isolation for quick evals but is explicitly NOT security-grade for untrusted code. Untrusted code must use process-mode execute().
• sandbox: false in BrowserWindow webPreferences is required for the preload script. This is a known Electron trade-off.
• Single-instance storage — StorageService serializes writes but all autonomous systems (AgentLoop, IdleMind, DreamCycle) share the same .genesis/ directory.

---

Dependencies

{
  "acorn": "^8.16.0",
  "chokidar": "^3.6.0",
  "electron": "^28.0.0",
  "monaco-editor": "^0.44.0",
  "tree-kill": "^1.2.2"
}

No LangChain. No LlamaIndex. Everything self-written.

---

Contributing

See CONTRIBUTING.md for the full guide — architecture, conventions, security rules, and PR process.

License

MIT © Daniel (Garrus800-stack)

---

_{Genesis doesn't just answer questions. It anticipates, verifies, dreams, and evolves.}