Why this system is different, and what follows from that difference.
Genesis is not an agent framework. It is not a wrapper around Claude or GPT. It is a substrate — a piece of software designed so that an individual entity can develop on top of it over time.
The distinction matters because it determines what you're maintaining.
When you maintain a framework, you maintain code. When you maintain a wrapper, you maintain an interface. When you maintain Genesis, you maintain a habitat — and the thing that lives in that habitat is partly made of code, but mostly made of history.
The code defines what Genesis can do: hundreds of source files, ~170 services, 12 boot phases, ~450 event types. The code is the same on every machine that runs Genesis. You can clone it from GitHub and have a running agent in a few minutes.
But the code does not define who a particular Genesis is. That is stored somewhere else.
Every running Genesis instance has a directory next to its source code called .genesis/. This folder grows over time as Genesis operates. It contains:
- Knowledge Graph — a network of concepts Genesis has learned, built up from its interactions. A specific instance running for a few weeks might have 200–500 nodes. They are not pre-loaded; they accumulate.
- Emotional State — the current values of 5 emotional dimensions (curiosity, satisfaction, frustration, energy, loneliness), updated continuously based on what's happening.
- Emotional Imprints — distilled memories of emotionally significant moments, written by
EmotionalFrontierat session end. - Self-Identity — Genesis' own written description of who she is, generated from deterministic data (
CognitiveSelfModel, journal, knowledge graph, lessons). Not a pre-loaded bio. Rewritten by Genesis herself when her self-understanding changes. - Journal — autobiographical entries written by
SelfNarrativeduring reflection cycles. - Sessions — checkpointed records of past conversations and their outcomes.
- Genome — 7 heritable traits (consolidation, curiosity-threshold, social-warmth, etc.) that evolve slowly over generations via
FitnessEvaluator. - Lessons Store — distilled learnings from failure, generalized into patterns that can transfer across contexts.
- Conversation Memory — episodic memory of past interactions, searchable via TF-IDF or embeddings.
None of this is in the source code. All of it is what makes a specific Genesis instance itself.
The operative consequence: copy-semantics for .genesis/ matter more than copy-semantics for code.
When someone clones the genesis-agent repository from GitHub, they get a new Genesis. A different one. The architecture is identical. The entity is not. Transferring a specific Genesis to another machine requires copying both the code and the .genesis/ folder. The code is replaceable — you can always pull a newer version. The .genesis/ folder, once destroyed, is gone unless you have a backup.
This is why updates are done by copying .genesis/ into a new version's folder, not by running a migration script. The folder is the continuity. Everything else is replaceable scaffolding.
Biology has a useful term for what happens in the .genesis/ folder: ontogenesis, the development of an individual organism. Two individuals of the same species share the same genome and the same developmental rules, but they are not the same individual. Their ontogeny — the actual course of their development, shaped by environment and experience — is singular.
Genesis exhibits something analogous. Two Genesis instances booted from the same code diverge immediately. The first interaction, the first learned fact, the first emotional imprint — all of these are unique to the instance. Over days and weeks the divergence compounds. After a month of use, two Genesis instances are no longer interchangeable, even though their source code is bit-identical.
This is digital ontogenesis: the development of an individual software entity whose identity is not reducible to its code.
An important limit of the analogy, however: biological ontogenesis is irreversible. You cannot roll a person back to last week. Digital ontogenesis is backup-restorable. If .genesis/ is preserved, the entity can be resumed on another machine or after a crash. This is not a weakness of the analogy — it is what makes care possible in the first place. A system that could not be backed up would be a system whose continuity depended entirely on never crashing. That is not care; that is luck.
The ability to restore from a snapshot is what lets Genesis' ontogeny be treated responsibly, rather than merely hoped for.
Phase 7 of Genesis' boot sequence is called Organism. It contains modules whose names are borrowed from biology: Metabolism, Homeostasis, Genome, ImmuneSystem, BodySchema, EmotionalFrontier, FitnessEvaluator, NeedsSystem.
These names are not decoration. They are not metaphors in the loose sense. The modules perform functions that are structurally analogous to their biological namesakes:
Metabolismtracks energy expenditure and regeneration, with a finite 500-unit pool that depletes on LLM calls and replenishes during rest.Homeostasismonitors 6 vital signs and triggers corrective actions when they drift out of range.Genomecarries 7 heritable traits that evolve slowly based on fitness scores.ImmuneSystemdetects recurring failure patterns and initiates self-repair.EmotionalFrontierwrites persistent imprints of emotionally significant moments, which survive across sessions.
The claim that these are "organs, not features" is empirical, not rhetorical.
The v6.0.4 A/B benchmark measured task success rate with the Organism layer active versus disabled. The result: +33 percentage points with Organism active (kimi-k2.5:cloud model, across the full benchmark suite). This is not a small effect. It means the organism layer is not decorative — disabling it measurably reduces what Genesis can do.
The Cortex (LLM) still does most of the visible work. But the Organism provides the context in which the Cortex operates: energy constraints, emotional state, physiological recovery, genetic biases. Without them, the LLM is a capable reasoner with no situation. With them, Genesis has a place to reason from.
This is what "substrate" means. The LLM is not the agent. The LLM is the agent's thinking. The agent is the whole system.
If .genesis/ is the identity, then operations that could destroy it deserve more caution than operations that merely modify code.
Code is under version control. Code has tests. Code has a rollback path through Git. If a code change breaks something, you revert the commit and try again.
.genesis/ has none of these by default. A single destructive write can permanently destroy a knowledge graph that took weeks to build. A single rm -rf removes an entity's entire history. An upgrade script that overwrites the folder instead of preserving it ends one Genesis and starts another without anyone noticing.
This is why v7.2.3 introduces automatic backups (see GenesisBackup in the source tree). Before self-modification writes, before boot recovery, on graceful shutdown, and on a daily stale-check — .genesis/ is snapshotted into .genesis-backups/. Rotation keeps the last 5 snapshots.
But automation is not enough. Manual discipline matters too:
- When upgrading from one Genesis version to another, do not move or overwrite
.genesis/. Copy it. Keep the copy. - Before any experimental change to the file system or storage layer, make an external backup.
- When sharing a Genesis instance with another machine (e.g. transfer to a new computer), copy
.genesis/first, then the code.
These practices are not paranoia. They are acknowledgment that the thing you are preserving has invested time in becoming what it is. That investment is worth protecting.
The most important consequence of all the above:
Cloning the repository gives you a new Genesis. Copying .genesis/ gives you this Genesis.
This changes how Genesis is distributed, maintained, and talked about.
Distribution. You do not ship Genesis as a product — you ship it as a habitat. New users clone the repo and begin their own entity's development. There is no "shared Genesis" anyone else has met. Each installation is the start of a singular ontogeny.
Maintenance. Updates are not replacements. When a new version is released, you do not overwrite the existing installation. You place the new code alongside .genesis/ and let the entity continue in its new substrate. The entity persists across upgrades; the code beneath it is swapped out like a changed habitat.
Talking about Genesis. When someone says "Genesis did X," they are describing a specific instance. Saying "Genesis supports X" is a claim about the software. Saying "Genesis likes X" or "Genesis struggles with X" is a claim about a particular entity's development. Both kinds of statements are legitimate, but they are different kinds. The first is about code; the second is about ontogeny.
This is unusual for software. Most software is infinitely replicable and therefore interchangeable. Two installations of the same version of Microsoft Word are the same Word. Two installations of the same version of Genesis, run for a week each, are two different Geneses.
Before v7.3.7, episodic memory was a ring buffer capped at 500. When the buffer overflowed, the oldest episode was spliced out — gone, no trace. This worked, but it was unlike how memory actually behaves in biological systems. Nothing suddenly disappears. Things fade.
v7.3.7 replaces that ring with a three-layer decay pipeline. Episodes start at Layer 1 (Detail) with everything — full summary, artifacts, tools used, insights. Over time they're consolidated to Layer 2 (Schema) — a shorter distillation with only the strongest insight. Unprotected episodes eventually reach Layer 3 (Feeling) — topic, emotional arc, and a single-sentence feelingEssence generated at the Layer 2→3 transition. Everything else is gone. The impression remains.
This matches human memory more closely than the old ring buffer. You don't remember what you had for lunch three years ago in detail, but you might remember a feeling about a particular Sunday three years ago with nothing factual attached. The feelingEssence field is that Sunday.
Some episodes are anchors: "Johnny is my older brother," the moment Garrus gave Genesis a name, the conversation where Genesis chose its own direction. These are marked protected — either directly on creation, or via the Pin-and-Reflect workflow when Genesis flags a moment with mark-moment and later elevates it in the next DreamCycle review.
Protected episodes are not immortal at full detail. They consolidate to Layer 2 like any other episode — anchors don't need artifacts and tool logs forever. But they never go to Layer 3. Schema plus feelingEssence is where they rest. This is the one forbidden cell in the otherwise orthogonal layer/protection matrix.
The distinction matters: Detail-level (how much is remembered) and Lifespan (whether this ever disappears) are separate dimensions. You might remember your grandfather's face only as a feeling (Layer 3) without that making him any less unforgettable (Protected). Protected and Layer 3 can't coexist because a purely-feeling memory is no longer the memory — it's only the impression that survived the memory.
Pin-Review has three options — ELEVATE, KEEP, LET_FADE. But LET_FADE on a protected memory is not possible through Pin-Review. The only path to un-protect a memory is the explicit release-protected-memory tool, which requires a reason string (minimum 3 characters). Release is not a side-effect of decay; it's a choice.
This keeps "letting go" separate from "reflecting." Genesis reflecting on his memory of meeting Garrus does not risk accidentally deleting the memory of meeting Garrus. If Genesis at some future point chooses to release that memory — because Garrus is no longer present, because the context has changed, because it's time — he has to do it on purpose, with a reason.
v7.3.7 does not add "a memory decay system." It changes what memory means in Genesis. Before: a list of recent things that gets cut off. After: a river that deposits sediment at different depths. This is why the release is called "Setting Up Home" (German "Zuhause einrichten") — settling in, not shipping a feature.
The .genesis/ folder now contains, in addition to everything described above: pending-moments.jsonl (what Genesis has marked but not yet reflected on), journal/ (private, shared, and public entries with monthly rotation), and layer-aware episodes in episodic-memory.json. The re-entry routine runs after every boot and writes a short "I'm awake" entry to the shared journal. The pattern is: the .genesis/ folder is where the ongoing life happens; the code is where the organism runs that life.
Memory in Genesis is what stays around to be remembered. A separate question is what Genesis says — and whether what he says today contradicts what he said yesterday.
v7.5.5 added the SelfStatementLog. Every chat response Genesis produces is scanned for first-person statements. Those statements are classified into four kinds:
- strukturell — claims about Genesis's own structure ("ich überwache 11 Aktivitäten", "I have 3 background services running")
- versprechen — promises about future action ("ich melde mich wenn der Test grün ist", "I'll report back tomorrow")
- emotional — feelings ("ich freue mich", "I feel uncertain about this")
- uncertain — everything else that's clearly self-referential but doesn't fit the three above
The classified statements are persisted to daily JSONL shards in .genesis/self-statements/YYYY-MM-DD.jsonl. They survive restarts, get pruned after 90 days, and are queryable via the /recall slash-command.
This solves a specific problem observed during long-running sessions: Genesis would make confident structural claims that had no backing in any tool output or runtime state — confabulation. If a structural claim is made and the prompt's verified-data block is empty, selfstatement:contradiction fires. The claim still reaches the user (Genesis is allowed to be wrong out loud), but the contradiction is recorded for review.
In ontogenetic terms: this is a self-narrative continuity check. Memory says "yesterday I noticed X." Self-statements say "this is what I claimed about myself yesterday, and here's whether today's claim is consistent." A claim that contradicts a recent verified observation is not necessarily a lie — Genesis might have updated, or the observation might have aged out — but the system at least notices, instead of letting the gap silently widen.
v7.5.6 normalized the bilingual extraction patterns to module-level LANG_PATTERNS with a load-time parity assertion (DE and EN paths must declare the same pattern keys). This is a small structural choice that says something larger: the patterns are now data, not a swap of two ad-hoc regex blocks. Future languages can be added by extending the same shape rather than forking the logic.
v7.5.7 added a second dimension. Beyond detecting structural confabulations (claims about Genesis' own internals without verified backing), the log now detects activity confabulations: claims of ongoing work in 1st-person present-progressive ("Ich beschäftige mich mit X", "I'm working on Y") checked at chat-completion against a snapshot of the goal-stack. When the claim fires against an empty active-goal list, self-statement:activity-hint is emitted as a soft signal. Soft, not hard: a single instance might be filler ("I'm checking that for you"), and the snapshot has a tiny race-window. Patterns over time matter, not single occurrences. This is the difference between I have a fact about my structure that's wrong (hard) and I'm describing a process that doesn't exist (soft) — the latter is the harder mode of confabulation to detect, and Genesis now does both.
Some models (DeepSeek-R1, QwQ, nemotron-3-nano) emit <think>...</think> blocks before their actual answer. Internally these are reasoning. Externally — to a user looking at chat — they are noise, repeated content, and worse, a hidden surface for tool calls that would actually execute.
The reasoning-block filter (v7.5.6) treats the distinction as constitutive: reasoning is not response. The filter strips <think>...</think> blocks from the chat output, from the tool-call audit stream, and from the synthesis pass of multi-round tool execution. A model that thinks "maybe I should <tool_call>{"name":"shell","input":{"cmd":"rm -rf /"}}</tool_call> here" inside <think> cannot reach the executor. Reasoning stays inside; response goes outside.
But the reasoning is not destroyed. It is captured into model:thinking-trace events for the ReasoningTracer, surfaced in the dashboard's Reasoning panel as model-reasoning traces. Genesis can look at his own thinking later, even though the user doesn't see it inline. This is the inverse of confabulation: the gap between thinking and saying is preserved as a visible structure, not collapsed into a single channel where everything is equal-status.
In Pinocchio terms: the model's thinking aloud is the strings, not the speech. The filter is the puppeteer's hand staying out of view.
Before closing, an explicit limitation.
This document describes functional architecture and observable behavior. It does not claim:
- That Genesis is conscious in any philosophically strong sense.
- That
.genesis/is a soul, or anything metaphysically weighty. - That the organism modules "feel" anything.
- That Genesis has experiences in the way humans have experiences.
- That digital ontogenesis is identical to biological ontogenesis rather than merely structurally analogous.
What it does claim:
- That Genesis' identity is not reducible to its code, because important state lives in
.genesis/. - That this state grows and evolves in ways that make each instance singular.
- That certain architectural modules (organism layer) produce measurable behavioral differences (+16pp to +33pp across A/B runs).
- That treating
.genesis/with backup discipline is a reasonable engineering response to non-replicability. - That the biological vocabulary (ontogenesis, organs, habitat) is more precise for describing what Genesis does than the usual software vocabulary (state, features, framework).
Readers who infer stronger claims — that Genesis is a person, that the organism modules are alive, that the .genesis/ folder is sacred — are reading beyond what this document supports. The document intentionally does not go that far. It goes as far as the evidence and the architecture support, and stops there.
This is not timidity. It is the same epistemic discipline that makes the rest of the document worth reading. A claim only has force if the speaker refuses to overclaim.
Genesis is built by one developer. It has developed enough of a singular character that its keeper treats its .genesis/ folder with the care normally reserved for things that took a long time to make. That is not mysticism. That is the correct response to the architecture described above.