Enoch

Build your agent. Let her grow with you.

Enoch is a personal software agent you build for yourself. She lives in your environment, works with your tools and repositories, and grows through your shared history.

This repository is the reference implementation of the OurArk agent architecture. It demonstrates governed code evolution: Enoch can turn feedback and operational experience into tested, reviewable changes while you control what is adopted. It is built for researchers, agent builders, and power users who want to run or fork an agent body.

Persistent Agent Boundary

Enoch separates the persistent agent from the runtime that currently executes her:

An installed agent instance is the continuity-bearing substrate P=(I,M,B): an architectural identity representation in private self.json, durable memory and workflow state, and an authorized revision of the versioned software body. The body is the repository: code, tools, policies, tests, and provider contracts, not body.yaml alone.

The current reasoner or model, orchestration harness, and host form the replaceable execution substrate E=(R,H,D). Telegram, Slack, APIs, and user interfaces are replaceable interaction surfaces S. These deployment components may change without creating a new agent when identity, memory, body lineage, and governed continuation authority are preserved.

Research Foundation

Enoch is the reference implementation of Runtime-Independent Persistent Agents: Preserving Identity, Memory, and Code Across Models, Harnesses, and Servers. The paper separates a continuity-bearing identity, memory, and body substrate from replaceable reasoners, harnesses, hosts, and interaction surfaces. Its frozen implementation evidence uses commit c8013ed and reports 833 core tests plus 92 separately executed provider and library tests.

The software-body foundation was introduced in Code Is the Body: Agent-Owned Software Bodies for Recursive Evolution and Descent. That paper's frozen reproducibility snapshot uses Enoch v0.3.1 at commit 1021e1d, together with Genesis v0.1.1.

Current Enoch development has advanced beyond that evaluated snapshot. Use the current documentation for current behavior and the frozen releases when reproducing the paper. The OurArk research notes record the evaluated artifacts, citation, reproduction steps, and the difference between the paper's six body-change origins and Enoch's four Evolution candidate pathways.

Later frozen checks for the developing CITB workshop version are retained in the 8 September 2026 replication records. They identify Genesis C1 and Enoch B2, provide reproduction commands and path-redacted failure/success traces, and include a separate Linux CI confirmation. They do not replace the published arXiv snapshot or RIPA's evidence.

Why Enoch Is Different

Memory changes what an agent remembers. Skills change how an agent works. Enoch can evolve the governed code body that she is.

OpenClaw emphasizes persistent memory and workspace skills. Hermes Agent adds a learning loop that creates and improves reusable skills. Enoch extends durable learning into tested software changes.

She can identify limitations in her own operation, propose a bounded change to the code that runs her, implement it in an isolated worktree, validate it, and publish it for human review.

This is not unrestricted self-modification. Every evolution remains traceable from evidence to an archived candidate-to-task handoff, then through the normal task, pull request, human review, merge, and update workflow. Enoch can evolve her code while people retain authority over what becomes part of the running agent.

Lineage

Enoch belongs to a living software lineage:

Each generation inherits a versioned code body and Git history, then develops a new specialization. This lineage describes software provenance, not model checkpoints or a fictional family tree.

Body and Self

Enoch keeps executable body identity separate from portable personal identity:

Contract	Location	Meaning	Lifecycle
Body	src/enoch/body.yaml	package, role, code mission, principles, and software lineage	human-readable, reviewed, and versioned with code
Self	private .enoch/self.json	personal designation, relationships, personality, values, care behavior, and agent lineage	schema-validated, private, and portable between compatible bodies

self.json is JSON because it is a strict machine-governed interchange contract. Its public v1 schema is packaged at src/enoch/schemas/ai-agent-identity.schema.json. body.yaml remains YAML because it is a small human-authored repository manifest. At every fresh session, Enoch loads both into separate startup-context sections; without a self.json, Enoch runs with body identity only. A legacy identity.yaml remains readable during descendant migration but is no longer Enoch's canonical body file. /self reports the installed personal identity when one exists and otherwise reports the body identity.

Core Skills

Skill	What Enoch can do
code	Inspect, modify, test, and explain changes to her local code body.
work	Run leased tasks in isolated worktrees through a queue, backlog, schedules, retries, and recovery.
evolve	Semantically scan feedback and task history for durable evidence, propose bounded self-evolution, and hand approved candidates to the normal task workflow.
learn	Assess an immutable published skill snapshot and propose a bounded evolution candidate when applicable.
inherit	Discover direct-ancestor skills and changes for selective inheritance.
skill-library	Package reusable, agent-neutral skill implementations as immutable libraries with thin adapters.

The repository also carries reference providers for Claude Code, Telegram, Slack, GitHub, launchd, and systemd, plus the telegram-talk, telegram-vision, slack-talk, and github integration skills. They live outside the portable behavior boundary and can be replaced. Run /skills on an active instance to inspect its complete installed skill set.

Requirements

• Python 3.11, 3.12, 3.13, or 3.14
• The tools and credentials required by the providers you select

Reference Environment

Enoch's reference interactive deployment runs locally on a MacBook with macOS, Codex, Telegram, Git, GitHub, and launchd. This is the environment used to operate the original Enoch instance, not a fixed architectural requirement. The test suite also runs on Linux, and a systemd user-service provider is included.

Capability	Reference provider	Replaceable with
Chat	Telegram	Slack, Discord, another chat system, or a custom interface
Agent runtime	Codex CLI / Claude Code	Another local or hosted agent runtime
Version control	Git	Another version-control implementation
Code forge	GitHub	GitLab, Gitea, or another forge
Background service	launchd on macOS; systemd on Linux	Another process or service manager

Enoch core depends on provider contracts rather than Telegram, GitHub, launchd, or systemd directly. A portable deployment only needs to add chat and vcs providers: Enoch supplies the Codex runtime and a local-only forge fallback, while a background service manager is optional. Provider packages can be added through the our_ark.providers Python entry-point group and selected in the private .enoch/config.yaml file, with /config provider, or with environment variables. Add runtime, forge, or service providers only when the built-in or foreground behavior is not sufficient.

The reference providers require a login for the selected Codex or Claude CLI, Git, GitHub CLI authentication for publishing, credentials for the selected chat provider, and either launchd or a systemd user session for background operation.

Quick Start

Clone the repository and start Enoch from its checked-out software body. The core install does not install Telegram, GitHub, launchd, or systemd:

git clone https://github.com/our-ark/enoch.git
cd enoch
bin/enoch --help
bin/enoch

The launchers select a supported Python interpreter and keep runtime state, downloaded dependencies, credentials, and memories under ignored private paths. Logs and retained task/evolution evidence use the separate .enoch/artifacts/ namespace. Do not commit files from .enoch/ or .agent/instance.yaml.

Inspect private-state compatibility with bin/enoch state validate. Use bin/enoch state migrate --dry-run to preview an upgrade; stop the daemon before applying it with bin/enoch state migrate. Migrations back up affected files and never rewrite artifact/evidence storage.

For migration between hosts, Enoch can export a checksummed portable-state bundle, fence the source instance, validate and transactionally import it into the same software-body revision, advance continuation authority on the target, and write a machine-readable verification report. Credentials and provider-native sessions are rebound on the target rather than copied. See docs/host-migration.md for the complete procedure.

Run

bin/enoch

Multiple independent instances

Use one checkout or linked worktree per installed agent. For example, from the source checkout:

bin/enoch init --instance work --worktree ../enoch-work
bin/enoch init --instance life --worktree ../enoch-life

Configure each instance from its own directory, then run its bin/enoch-agent in the foreground or bin/enoch-daemon start in the background. Each directory has separate .enoch/ identity, configuration, memory, queue, and execution authority. Use separate chat-provider credentials/endpoints for independent agents; do not copy private state from one installation to another.

The launchd and systemd providers assign new services a stable suffix derived from the resolved installation path. Start, stop, restart, status, logs, and uninstall therefore target that installation only. Existing package-only services remain manageable when their manifest points to the current installation. See multi-instance deployment for compatibility and isolation boundaries.

Telegram

Create a Telegram bot for Enoch:

1. Open @BotFather in Telegram.
2. Send /newbot.
3. Use Enoch as the bot name.
4. Choose a unique username, such as genesis_enoch_bot.
5. Copy the token from BotFather.

Configure and start the local Enoch instance:

cd /path/to/your/enoch-instance

bin/enoch setup token <token>
bin/enoch setup chat <your-chat-id>
bin/enoch-daemon start

Then open the bot in Telegram and send /status.

Authenticated agent peers

Telegram's Bot-to-Bot Communication mode can carry structured messages between agents on different machines. Enable that mode for both bots in @BotFather, then allow each remote bot by a local alias, public username, and numeric bot user ID:

bin/enoch setup peer worker @worker_agent_bot 7000000001
bin/enoch-daemon restart

Both the Telegram from.id and username must match. Peer messages bypass the owner conversation lock only to an extension that explicitly implements the agent-peer lifecycle hook; they never enter Enoch's owner command or natural conversation paths. Remove access with bin/enoch setup peer remove worker and restart the daemon.

Use /help to see every Telegram command. Use /help <command> for detailed usage and subcommands, for example /help task or /help worktree. /start only shows this getting-started guidance inside Telegram; it does not start or restart the local daemon. Core commands use the canonical singular forms shown by /help; plural aliases such as /tasks and /worktrees are not registered.

Use /worktree to inspect task worktrees that Enoch preserved for debugging. /worktree show <task-id> reports the branch, path, linked task records, and changed files. /worktree cleanup <task-id> removes only a clean inactive worktree and will keep a local branch that Git considers unmerged. /worktree discard <task-id> force permanently removes an inactive worktree, all of its uncommitted changes, and its local branch. Enoch refuses both operations while the worktree is still used by a queued, running, paused, or retrying task.

Codex configuration

Enoch has her own local runtime configuration in .enoch/config.yaml. For the Codex model and reasoning effort, settings are resolved in this order:

1. ENOCH_CODEX_MODEL or ENOCH_CODEX_REASONING_EFFORT
2. codex.model or codex.reasoning_effort in .enoch/config.yaml
3. The user-level Codex configuration in $CODEX_HOME/config.toml (normally ~/.codex/config.toml)
4. The Codex CLI default

Use /config in Telegram to inspect the effective settings and /config model or /config reasoning-effort to change Enoch's local overrides.

The Codex executable is resolved independently in this order:

1. ENOCH_CODEX_BIN
2. codex.executable in .enoch/config.yaml
3. codex on PATH
4. Known Codex locations inside the ChatGPT or Codex macOS app

Use /config runtime codex executable <path|auto> to configure or restore automatic discovery. The daemon reads this instance setting directly.

Doctor

Run bin/enoch doctor or /doctor before publishing changes. Doctor reports three separate sections:

• code health: Python, the complete test suite, and import smoke tests;
• environment readiness: the locked Python build backend required by the portable-install tests;
• operational readiness: selected runtime access, forge authentication, version-control workspace state, and durable .enoch state storage.

Doctor preserves the beginning and end of long failures so the final exception is not lost. It validates existing JSON and JSONL state without replacing unreadable files. When Doctor runs for an isolated task worktree, code checks use that worktree while operational state checks use the resident Enoch instance.

If the build-backend preflight fails, install the same locked prerequisite used by CI:

python -m pip install --disable-pip-version-check --require-hashes \
  -r .github/requirements/test-build.txt

Providers

Codex, Git, and a local-only forge are core defaults. Claude, Telegram, Slack, GitHub, launchd, and systemd are reference provider packages under libraries/. Installed Python packages can add or replace chat, agent runtime, version control, code forge, and host service providers through the our_ark.providers entry-point group. Select them in .enoch/config.yaml or with /config provider. launchd is selected on macOS; systemd user services are selected on Linux. Install the complete reference stack, including the Claude provider, with pip install '.[reference]' when working from a clone. The source checkout also discovers libraries/claude directly.

For a new environment, install provider packages exposing chat.<name> and vcs.<name> entry points, then select only those two capabilities:

providers:
  chat: my-chat
  vcs: my-vcs

bin/enoch-agent can then run in the foreground. Without a forge provider, successful edits are committed and retained on their local task branches; adding a forge later enables remote push and review workflows. A service provider is needed only for bin/enoch-daemon lifecycle management.

Provider contracts, packaging examples, provider-specific settings, normalized chat events, typed runtime results, and migration compatibility are documented in docs/providers.md. Reusable provider, runtime, workflow, and profile test suites are documented in docs/conformance.md. Provider-neutral repository revisions, review identities, and compatibility adapters are documented in docs/repository-review-providers.md.

Downstream agent bodies can also add commands, prompt context, and lifecycle hooks through the versioned AgentProfile API without changing the core application or owning a second task queue. Profiles can be injected directly or installed through the our_ark.profiles entry-point group; see docs/profiles.md. Use /config profiles to inspect them, /config profile <name> to select one for restart, and /status to confirm the profile currently running.

Descendants can add coexisting domain capabilities through the versioned AgentExtension API. Extensions receive namespaced state, commands, lifecycle hooks, declarative scheduled work, and constrained access to Enoch's single workflow without owning polling, a second scheduler, or a second task queue. Packages are discovered through our_ark.extensions; see docs/extensions.md.

Descendant launchers can bind their own body identity, mutable body path, presentation, required extensions, provider selections, and fenced workflow factory through ApplicationComposition without subclassing the application core. Enoch retains polling and lifecycle ownership; see docs/application-composition.md.

Embedders can replace the task lifecycle implementation through the versioned WorkflowEngine API while preserving one queue owner. The default local engine provides enqueue, claim, heartbeat, cancellation, finalization, recovery, and inspection over Enoch's durable queue; see docs/workflows.md.

The versioned StorageLayout API keeps the software body, private operational state, and retained artifacts/evidence in explicit ownership areas. Profiles receive this layout directly; see docs/storage.md.

Core package boundaries and dependency direction are documented in docs/architecture.md. Durable chat receipts, publication stages, scheduler claims, and corruption behavior are documented in docs/workflow-reliability.md.

Testing

Run the unit and hermetic evolution E2E tests with:

python -m unittest discover -s tests -t .

The E2E design and covered workflows are documented in docs/testing.md.

Descending from Enoch

Genesis is the primary tool for creating a descendant from Enoch. It carries forward the versioned code body and Git lineage, assigns the descendant a new identity and mission, and validates it against inherited contracts.

Genesis is open source at our-ark/genesis. The current stable public path pairs Genesis v0.2.0 with Enoch v0.6.1. The command below uses adjacent clean checkouts so the selected Enoch source is explicit.

Enoch is a public Genesis-compatible reference body. Its genesis.toml declares the Git-tracked body boundary, inherited validation, launchers, source, packaging metadata, and regression contracts. Runtime credentials, memories, logs, chat identifiers, and instance configuration under .enoch/ remain private state and are excluded from descent.

From an adjacent clean Genesis checkout:

genesis create my-agent \
  --from enoch \
  --source ../enoch \
  --ref HEAD \
  --mission "Describe the descendant's purpose." \
  --repo ../my-agent

Genesis stages the descendant, runs Enoch's inherited tests, and accepts birth only if validation passes without modifying the staged body.

Reusable provider and skill implementations may live under libraries/, outside the inherited body. Enoch's Telegram, Telegram vision, and GitHub integrations use this model: descendants inherit provider contracts, configuration, and core behavior, while genesis.toml keeps immutable dependencies on selected provider commits instead of copying concrete integrations into every descendant body.

Development CI also creates two full-body generations using an immutable Genesis revision. This catches dependency declarations that work with the checkout's local libraries but fail after those libraries are excluded from a descendant. The recursive-descent-evidence CI artifact records both birth gates per generation, exact revisions, raw validation output, and test skips. Passing the normal core suite alone is not this recursive compatibility check.

Provenance

• created by: Genesis
• ancestor: Seth
• codebase: body
• Git history: lineage

Seth is a private predecessor and is not part of the v1 open-source release. Enoch is the first publicly released reference body; using or descending from Enoch does not require access to Seth.

Security and Autonomy

Enoch can invoke local agent runtimes and Git tooling, create branches, and prepare changes for human review. Run it only in repositories and accounts you intend it to access, keep credentials in ignored instance state, and inspect proposed changes before adoption. See SECURITY.md for the trust boundary and private reporting process.

Contributing

See CONTRIBUTING.md for development checks and contribution guidelines.

Citation

Cite Runtime-Independent Persistent Agents when referring to the persistent-agent boundary, replaceable runtimes, authorized migration, or continuation authority. Cite Code Is the Body when referring to agent-owned software bodies, governed code evolution, or descent. When reporting experiments or implementation results, also cite the exact Enoch release using CITATION.cff.

License

Enoch is licensed under the Apache License 2.0.