genesis-web-override

<img src="docs/images/genesis-banner.svg" alt="Genesis" width="680">

<img src="docs/images/genesis-dashboard.gif" alt="Genesis Neural Monitor — live subsystem health" width="720">

<img src="https://img.shields.io/badge/python-3.12-blue" alt="Python 3.12"> <img src="https://img.shields.io/badge/LOC-298%2C000%2B-informational" alt="Lines of Code"> <img src="https://img.shields.io/badge/license-MIT-green" alt="License"> <a href="#get-involved"><img src="https://img.shields.io/badge/contributors-welcome-brightgreen" alt="Contributors Welcome"></a>

<a href="https://github.com/anthropics/claude-code"><img src="https://img.shields.io/badge/Claude_Code-black?logo=anthropic&logoColor=white" alt="Claude Code"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node.js-339933?logo=node.js&logoColor=white" alt="Node.js"></a> <a href="https://playwright.dev"><img src="https://img.shields.io/badge/Playwright-2EAD33?logo=playwright&logoColor=white" alt="Playwright"></a> <a href="https://discord.com/invite/Zkc3XMQpJX"><img src="https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white" alt="Discord"></a>

Contents

• Genesis in 30 seconds
• What this is
• Getting started
• How it thinks
• Memory
• Learning
• Autonomy
• Infrastructure
• Real-world integration · Modules
• What's inside
• Roadmap — V4 & V5
• Primitives from the Genesis portfolio
• Get involved

---

Run your own personal AGI. Genesis is a complete, open cognitive architecture—clone it, run your own instance, and extend the core. What follows is the case for why that's worth doing.

We have the most capable AI models ever created, and we're using them like search bars with better grammar.

Every other AI agent puts you in the driver's seat—and keeps you there. YOU figure out what you need. YOU debug the failures. YOU manage the infrastructure. YOU supervise every step.

But now? This is my run at personal AGI—the most complete open-source cognitive architecture for a persistent personal agent.

Not the sci-fi version. The real one: a system that remembers everything, learns from every interaction, thinks while you sleep, earns autonomy through demonstrated competence, and gets fundamentally better every day it runs. Clone it, run it; tell me I'm wrong!

Truthfully, no, I do not genuinely consider this to be "true" AGI. In order to get to something resembling "true" AGI, it would need to be built from first principles, which would require the orchestration (that IS Genesis) to be built into the LLM layer, the most foundational part of Genesis' compute layer itself. Nor am I of any particular belief that LLMs are necessarily the right architecture for this pursuit in the first place. But because I cannot change the LLM layer, and no better technology currently exists, this is the best I can do today. Call it "proto-AGI;" "pseudo-AGI" even.

But what I can tell you is this: Genesis is far closer to AGI than anything else I've seen, and even if it's not AGI from first principles, it mimics a lot of the same outcomes and behaviours and capabilities that AGI would presumably need to exhibit. If AGI sounds like something you'd like to help contribute to, come build with us →

---

Genesis in 30 seconds

Personal AI does what you tell it. Personal AGI does what you need.

Your current AI—however capable—is reactive, stateless, and session-scoped. You direct it. You re-explain context every time. It's equally ignorant about you on day 100 as day 1. It's a tool: smart in the moment, dumb about you.

Genesis is different:

• It knows what to do without being told — because it's accumulated months of context about your projects, your decisions, your patterns. You never re-explain yourself.
• It acts between sessions — thinking, researching, monitoring, surfacing what matters while you're not there. Not waiting for a prompt.
• It has judgment that improves with evidence — earned autonomy per action category. First failure triggers demotion. Trust is rebuilt through performance, not time.
• It's a fundamentally different system at month 6 than month 1 — not because of updates you installed, but because of what it learned living alongside you.

With personal AI, you are the intelligence directing the tool. With personal AGI, it is an intelligence working alongside you—and the amount you need to manage shrinks over time.

How it does this:

• Autonomous cognitive cycle — a dual-ego architecture that wakes up, assesses the situation, proposes actions, and earns the right to execute them. Not waiting for prompts. Not following scripts. Thinking.
• Massive capability layer — 60+ tools out of the box: browser automation, outreach pipeline, research, content creation, infrastructure monitoring, campaign execution. Not a framework you build on—a system that works, out of the box.
• 4-layer memory — essential knowledge, proactive recall, deep search, knowledge pipeline. Hybrid retrieval that compounds across months, not conversations.
• Closed-loop learning — outcome classification, causal attribution, procedure extraction. Laplace-smoothed confidence, not vibes.
• Earned autonomy — trust granted per action category through demonstrated competence. The system gets measurably better at its job, and it can show you the receipts.

Day 1 — a strong generalist with full cognitive infrastructure. Day 30 — a personalized specialist in every domain you've touched. Day 90 — anticipating needs you haven't articulated yet. Day 180 — evolving its own architecture to serve you better.

Get started →

---

What this is

Genesis is a cognitive architecture that makes the AGI claim explicitly—and backs it up with open-source code you can read, run, and challenge.

Not a chatbot. Not an API wrapper. Not another prompt chain with a for loop.

It uses Claude Code as its reasoning engine. Genesis is what it's been missing: the mind that remembers, reflects, learns, and decides.

<img src="docs/images/tin-man.jpg" alt="The Tin Man" width="320"> <i>"Claude Code already had the brain. We gave it the heart."</i>

50+ subsystems. 4 MCP servers. 2 vector databases. Every design decision made by one engineer working full-stack across infrastructure, cognition, and integration layers. That's the point. If one developer with the right cognitive infrastructure can build and run a system this complex, imagine what a team becomes capable of.

<img src="docs/images/genesis-architecture.png" alt="Genesis cognitive architecture — three concentric rings" width="820"> _{<a href="docs/genesis-architecture-interactive.html">View interactive diagram →</a>}

---

<a id="getting-started"></a>

Getting started

System requirements

Genesis is a full system, not a pip package. It runs best on a dedicated Linux machine.

Resource	Minimum	Recommended	Notes
OS	Ubuntu 22.04+	Ubuntu 24.04 LTS	Debian-based required for auto-install. Other Linux works with manual setup.
RAM	8 GB	16 GB+	Genesis + Qdrant + Claude Code + background tasks. 8 GB is tight under load. Service memory caps are percentage-based, so Genesis right-sizes itself to the box — scaling down on an 8 GB host and up on a 32 GB+ one.
Disk	15 GB	40 GB+	The installer's pre-flight check requires 15 GB free and stops below it. Fresh install ~400 MB; memory, logs, and caches grow steadily with use.
CPU	2 cores	4-8 cores	Concurrent background tasks benefit from parallelism.
Network	Internet access	Always-on	Cloud LLM APIs required. Offline not supported.

These are the requirements for the host VM. Genesis runs inside a container the installer creates.

Before you start

What you need	Why	Where
Claude account	Powers the Claude Code agentic sessions — the reasoning Genesis does as an agent	claude.ai
At least one LLM provider key	Required. Genesis's own cognitive layer — routing, reflection, triage, memory extraction — calls these directly and does not run on your Claude subscription. Several have free tiers	see secrets.env.example
Telegram bot token (optional)	Only if you want the Telegram channel: proactive messages, approvals, voice	@BotFather
Tailscale (free)	Remote dashboard access from any device — no port-forwarding	tailscale.com

Install

One script sets up the entire infrastructure: Incus container, Guardian health monitor, bidirectional SSH, all dependencies.

git clone https://github.com/WingedGuardian/GENesis-AGI.git ~/genesis-setup
cd ~/genesis-setup
./scripts/host-setup.sh

Genesis is installed inside a container the script creates — the clone on your host is only the installer. Everything below happens in the container.

Step 1 — go in:

genesis   # alias the installer adds; drops you into the container at ~/genesis

If the alias isn't recognised yet, open a new terminal or source ~/.bashrc.

Step 2 — start your first session and let it set you up:

claude    # onboarding collects your API keys, profile and channels

Onboarding is interactive and covers the credentials Genesis needs. If it doesn't start on its own, run /setup. You can also edit ~/genesis/secrets.env directly inside the container — the installer creates it from the template but leaves it to you to fill in.

At minimum, set one LLM provider key. Without it the cognitive layer — routing, reflection, triage, memory extraction — has nothing to call, and those are the parts described above. Telegram is optional and configured in the same file (TELEGRAM_BOT_TOKEN from @BotFather, plus TELEGRAM_ALLOWED_USERS — message @userinfobot for your numeric id); leave both blank to run without that channel.

What you get:

Component	What it does
Full cognitive stack	Memory (4-layer hybrid retrieval + knowledge graph), self-learning loop, reflection engine, earned autonomy, dual-ego decision layer—all running continuously
Genesis server	Dashboard, API, and all subsystems at http://<container-ip>:5000
Qdrant	Vector database powering semantic memory (2 collections: episodic + knowledge)
Channel integration	Telegram (proactive outreach, approvals, voice), email triage, browser automation, inbox monitoring
Background cognition	Autonomous sessions that think, research, and audit while you're away—surplus compute, reflection cycles, goal tracking
Self-healing infrastructure	Guardian (host VM) + Sentinel (container)—two independent systems monitoring each other in a closed loop
Claude Code	CLI with Genesis hooks + 4 MCP servers auto-activated per session

Optional: local embedding

Component	Install
Ollama	`curl -fsSL https://ollama.com/install.sh \	sh`
LM Studio	Download from lmstudio.ai

Without these, Genesis uses cloud embedding APIs. With them: private, faster, free.

---

Your Genesis

Your Genesis install is one operational system: the public GENesis-AGI codebase, your private fork for customizations, and your private encrypted backups repo. See .claude/docs/your-genesis.md for the full model.

• Backup — runs every 6h via a systemd user timer (enable it once configured — see SETUP.md). SQLite, Qdrant snapshots, memory, transcripts, secrets—GPG-encrypted before push.
• Restore — git clone <your-fork> → scripts/bootstrap.sh → scripts/restore.sh. Back in minutes.
• Contribute — a distributed bug fixing pipeline automatically detects eligible fixes, pushes them to GitHub for inspection, and opens upstream PRs.

---

How it thinks

Four cognitive layers, running continuously:

graph TB
    subgraph "Cognitive architecture"
        EGO["Ego<br/><i>Two egos: signal-driven focus,<br/>goal tracking, autonomous action</i>"]
        AL["Awareness loop<br/><i>5-min tick, 18+ signals,<br/>zero LLM cost</i>"]
        RE["Reflection engine<br/><i>Micro / Light / Deep / Strategic<br/>with relevance tagging</i>"]
        SL["Self-learning loop<br/><i>Dopaminergic feedback</i>"]
    end

    subgraph "Infrastructure"
        RT["Operational runtime<br/><i>Dashboard, API, extensions</i>"]
        CC["Claude Code<br/><i>Reasoning, tools, sessions</i>"]
    end

    subgraph "Memory and data"
        QD["Qdrant<br/><i>2 vector collections</i>"]
        SQ["SQLite + FTS5"]
        MCP["4 MCP servers<br/><i>memory / recon / health / outreach</i>"]
    end

    EGO -->|"dispatches work"| CC
    AL -->|"depth signal"| RE
    RE -->|"observations"| EGO
    RE -->|"interaction data"| SL
    SL -->|"weight updates"| AL

    AL <--> RT
    RE <--> MCP
    MCP <--> QD
    MCP <--> SQ

    style EGO fill:#1a1a2e,stroke:#e94560,color:#fff
    style AL fill:#1a1a2e,stroke:#e94560,color:#fff
    style RE fill:#1a1a2e,stroke:#0f3460,color:#fff
    style SL fill:#1a1a2e,stroke:#533483,color:#fff

Every 5 minutes, the system collects 18+ signals across all its inputs—entirely programmatic, zero LLM cost. Signals get classified by how much thinking depth they warrant. Routine health checks get a quick pass. Novel patterns in user behavior get a deep analysis. Accumulated smaller reflections trigger strategic synthesis. The depth decision is automatic, and each cognitive layer feeds the next.

On top of this sits the ego layer: two autonomous decision-makers that read the system's observations and act on them. The User Ego (running Opus) focuses on user goals, activity patterns, and pending work. The Genesis Ego (running Sonnet) handles system health, infrastructure, and operational decisions. Each one assembles its own context from filtered observations, proposes actions via Telegram, and dispatches Claude Code sessions to execute approved work. They run on adaptive cadence—more frequently when things are active, backing off when they're not.

The ego doesn't just observe—it runs a unified cognitive loop. Signals (a stale goal, a conversation, a system event) enter a queue. A focus selector picks what matters most. Context gets assembled for that focus. The ego thinks, proposes, acts—cycle repeats. What you experience: Genesis notices when your goals go stale, reviews them with full context, tells you when subgoals complete a milestone, and adjusts its own review frequency per goal. It doesn't wait for you to ask "how's that project going?"—it already checked.

When Genesis isn't handling a user request, it doesn't sit idle. It researches topics you'll ask about tomorrow. It audits its own memory for contradictions and staleness. It tests whether its learned procedures still hold up. It works through problems it got stuck on earlier. The system you come back to on Monday is measurably sharper than the one you left on Friday.

<img src="docs/images/genesis-24h-timeline.svg" alt="24 hours of autonomous Genesis cognition — awareness, reflection, learning, surplus, outreach, and sessions" width="900">

---

Memory

Most AI memory is a vector database with a retrieval function. Genesis runs a four-layer architecture—because "what are we working on?", "what's relevant right now?", "find everything about X", and "what does the external documentation say?" are fundamentally different operations that need different retrieval strategies.

L1: Essential Knowledge (~300 tokens, injected at every session start)
    Pure DB queries. No LLM, no network, no latency.
    Content: active context, recent decisions, structural overview.
    → The forest view. Always available, even if everything else is down.

L2: Proactive Recall (fires on every user message, ~4.5s budget)
    Surfaces the most relevant memories automatically—before Genesis
    even starts thinking about your question. How many depends on what
    you asked: one for a bare command, three for general conversation,
    six for a question or a decision (a configurable ceiling caps it at eight).
    Hybrid: FTS5 keyword + Qdrant vector + activation scoring → RRF fusion.
    → You never have to ask "do you remember?"—it already checked.

L3: Deep Search (on-demand, ~1-2s)
    Full pipeline: two to five ranked signals fused via Reciprocal Rank
    Fusion — vector, keyword and activation, plus intent and event
    signals when they apply. Degrades to keyword+activation with no
    embedding provider.
    Wing/room filtering, intent classification, graph traversal.
    → When you need everything Genesis knows about a topic.

L4: Knowledge Pipeline (external, permanent)
    Ingests from text, PDF, audio, video, web pages, YouTube transcripts.
    Separate vector collection. Idempotent — re-ingesting updates, never duplicates.
    → Domain knowledge that doesn't decay with time.

LLMs lose the forest for the trees—that's a known weakness of large-context reasoning. The layer model is the architectural compensation: L1 maintains the forest (what are we doing, what have we decided, what matters), while L2-L3 drill into specific trees on demand. L4 provides the reference library.

What actually happens when you send a message:

Every prompt triggers L2 before Genesis starts reasoning about your question:

1. Your message hits a pre-processing hook
2. In parallel: FTS5 searches for exact keyword matches (~5ms), Qdrant searches for semantic similarity (1024-dim embeddings, ~400ms)
3. Activation scoring weighs each candidate: confidence × recency × (base + w₁·access_freq + w₂·connectivity) × class_weight — a weighted blend, not a bare sum. The base term is a floor (default 0.6) so a never-retrieved memory isn't buried by the cold-start problem; the weights are a tunable knob.
4. Reciprocal Rank Fusion combines the ranked lists—memories appearing in multiple signals accumulate score
5. Results inject into context with provenance metadata, as many as the stance budget allows

If the embedding provider is down, vector search is skipped—FTS5 still works because it's compiled into SQLite with zero external dependencies. Memory degrades gracefully, never goes dark.

Not just documents in a vector space:

Memories aren't isolated documents—they're connected. The knowledge graph creates typed links between memories across 12 edge types: supports, contradicts, extends, elaborates, succeeded_by, preceded_by, and more. When a memory is stored, auto-linking finds its nearest neighbors and creates typed edges based on similarity. When you recall a fact, Genesis can walk the graph to find what supports it, what contradicts it, and what replaced it. As of September 2026, on the install this was measured from: ~86,000 memories, of which ~81,000 are embedded into the episodic vector collection (a second collection holds ~3,900 knowledge-base entries), wired together by ~264,000 typed connections.

An event calendar tracks time-anchored information—deadlines, scheduled tasks, recurring cycles—so Genesis knows not just what happened but when, and can anticipate what's coming. Procedural memory captures reusable multi-step workflows extracted from experience, each with a calibrated confidence score that promotes or demotes it based on outcomes.

Activation scoring ensures relevance isn't just cosine similarity—it's time-aware decay (configurable half-lives: 30-60 days by source type), access frequency (log scale, capping at 20 retrievals), graph connectivity, and class weighting. A steering rule from month one outranks a casual observation from yesterday.

Two collections, different lifecycles:

Collection	What lives there	Lifecycle
Episodic	Conversations, decisions, reflections, evaluations	Decays over time. Subject to correction.
Knowledge	External domain data, ingested reference material	Permanent. Authoritative. Re-ingested, never duplicated.

Session extraction: After conversations end, a pipeline extracts what mattered—entities, decisions, evaluations, action items, relationships—each tagged with provenance back to the source conversation and line range. The system doesn't just remember what you said. It identifies what's worth keeping.

Wing taxonomy: Memory is classified into 12 structural domains (autonomy, career, channels, dev_workflow, employment, general, infrastructure, integrations, learning, memory, research, routing) with subtopics. Querying within a specific domain cuts noise from the full store. Classification uses tiered confidence signals: file path patterns (strongest) → keywords → tags → source pipeline → fallback.

Volume is the least interesting thing about this, and it is what a vector database with a lot of rows in it also has. The question worth asking is whether retrieval still works once the store is large — so Genesis grades its own recall weekly with an LLM judge and keeps the series:

<img src="docs/images/memory-quality-chart.svg" alt="Weekly judged retrieval quality — hit rate and MRR holding steady as the memory store grows" width="760">

Weekly snapshots from eval_snapshots, 2026-05-10 to 2026-09-06, on a single install. An LLM judge scores each recall; hit rate is whether a relevant memory came back at all, MRR is how near the top it landed.

• Sample size varies a lot between weeks — from single digits to several hundred. The bars along the bottom are those counts. A high point on a thin bar is noise, not a result.
• The first three weeks are blank because no recalls were judged yet. They render as a gap rather than as zeros.
• The x-axis is evenly spaced by snapshot, not by date. Sixteen of the eighteen intervals are exactly seven days; two in June are about half that, and are drawn the same width as the rest.
• Store size is reconstructed, by counting rows that exist today and were created on or before each week. It cannot see deletions: a memory created in May and deleted in July is missing from May's figure too. That understates the early weeks, which flatters the growth multiple rather than the quality lines.
• Precision is not plotted, and it is the metric that has slipped. Proactive recall returns a fixed number of memories rather than everything above a relevance bar, so when fewer memories are genuinely relevant than the budget asks for, the remaining slots get filled anyway. That caps precision by construction. It is an open design question, tracked in the issue tracker.

Regenerate with python3 scripts/gen_memory_quality_chart.py.

---

Self-learning

Most AI systems log what happened. Genesis classifies why it happened, extracts a reusable principle, and verifies that principle works next time. The pipeline runs automatically after every meaningful interaction:

1. Triage        → Should we learn from this at all? (5 depth levels)
2. Outcome       → What happened vs. what was expected? (5 outcome classes)
3. Delta