Architecture

fortytwo is a local-first personal-assistant spine built around existing agent runtimes and tool ecosystems. It is not intended to replace Claude Code, Codex, MCP servers, plugins, skills, or other agent runtimes. The project provides the durable personal-assistant infrastructure around them: memory, lifecycle, scheduling, channels, optional policy enforcement, and related supporting components.

Claude Code is currently the primary/reference runtime, but the architecture avoids unnecessary coupling to a specific model provider: components remain usable when Claude Code itself is configured against alternative compatible model providers.

Why this exists

An agent runtime alone is stateless between sessions and reactive to input. A personal assistant needs continuity: durable memory, durable time (scheduling), channels that reach the user, and a lifecycle that survives reboots and upgrades. fortytwo adds exactly that layer — and nothing more.

Principles

• Wrap, don't reimplement. fortytwo adds continuity and infrastructure around an existing agent. Anything the runtime or its MCP/plugin ecosystem already owns stays there.
• Local-first. Durable state lives on the user's machine (SQLite + local files). No cloud service is required.
• Small, focused repositories. Each package owns one concern and is publishable and usable on its own.
• The LLM is the only expensive resource. Scheduling, claiming, gating and recurrence math are pure DB/JS; an LLM turn runs only after a cheap gate passes.

System overview

channels / scheduler
        |
        v
      runner
        |
        v
   agent runtime
  (Claude Code today)
        |
        +---- MCPs / plugins / skills / tools
        |
        +---- fortytwo memory

optional surrounding components:
- gate
- salience

bootstrap / distribution / documentation:
- installer
- persona
- marketplace
- docs
- website

Ownership map

A useful rule when deciding where code belongs:

fortytwo should add continuity and infrastructure around an existing agent, not reimplement capabilities already owned by the agent runtime or its MCP/plugin ecosystem.

For example: browser automation should normally come from an existing MCP/plugin rather than a fortytwo-specific browser implementation.

Canonical project locations

• Website: forty-two.it
• GitHub organization: github.com/justfortytwo
• Architecture/design documentation: justfortytwo/docs

Key guarantees

• Channel-agnostic output. Agent output is always written to the memory journal; Telegram (or any other channel) is an optional notifier, never the system of record.
• Single writer for job execution. Producers only insert pending rows; the scheduler daemon is the single writer of the running transition.
• No scheduler↔telegram coupling. Both depend on runner; neither depends on the other.

Scope

In scope (MVP): installer bootstrap, persona rendering, memory journal and registry, runner process lifecycle, scheduler with durable jobs, Telegram channel.

Deferred / optional: gate policy enforcement, salience extraction, additional channels beyond Telegram.