arbor is a framework for an agent without sessions: many context windows run at once over one shared record, so work moves in parallel, replies come fast, and every window can find everything that was ever done.
A deployment composes the pieces it wants and registers plugins for the domains it serves. The framework guarantees what an agent cannot guarantee for itself - the record, isolation, exactly-once effects, the checks, dispatch - and leaves everything that takes judgment, such as git, merges and conflicts, to the agent.
- No sessions to manage. Work runs in disposable context windows. Any number run at the same time; none of them owns anything, and a window that ends loses nothing. The model looks up what it needs instead of carrying it.
- One record, shared live. Every input, tool call, result, send and note revision goes into one journal and is visible to every window as soon as it is written. Records never merge and are never lost.
- Dispatch by a judge. A judge (Jev by default, replaceable) decides which live window takes a new input, or opens a new one. There is no router session and no main line.
- Current without locks. Windows run in parallel. New events on a conversation a window is in are steered into it as they arrive; only a note write is checked against the revision the window read.
- Mechanisms in the framework, policy in the agent. The framework guarantees what an agent cannot guarantee for itself - the record, isolation, exactly-once effects, the checks, dispatch. Everything that takes judgment, such as git, merges and conflicts, is the agent's.
- A shared workspace with per-window checkouts. The default workspace is
ovnfs: one shared folder every window reads, and a window opens its own
copy-on-write checkout of the project it needs, works there and merges back
with
apply. It falls back to a plain directory per window when ovnfs is not installed. It is not a sandbox: ovnfs isolates files, not processes. - A self-changing environment. The model adds and changes skills, MCP
servers and resident services itself; a
reloadvalidates the change and broadcasts it to every live window as a delta of names and descriptions. - Minimal limits. The framework sets no policy. Permissions, privacy review, budgets and approvals belong to deployments built on it, through hooks.
- Direct tools plus code mode. Decisions are direct tools; everything else
is a module called from
code_exec. There is no CLI. - Every module is replaceable. The agent backend (pi by default), the journal, notes, workspaces, the judge, channels and the rest are interfaces (docs/architecture.md).
Node 24 or newer. Every package is published separately, so a deployment installs the core and the defaults it wants:
npm install @4fu/arbor-core @4fu/arbor-journal-sqlite @4fu/arbor-notes-sqlite \
@4fu/arbor-environment-dir @4fu/arbor-supervisor-process @4fu/arbor-agent-pi \
@4fu/arbor-workspace-dir@4fu/arbor-plugin-http is optional; it is the example plugin below.
@4fu/arbor-segmenter-jieba is an optional peer of the lexical package, and
@4fu/arbor-search-zvec an optional peer of the journal: absent either one, the
journal searches lexically and nothing else changes.
The smallest host needs a journal and a backend. Adding the defaults and one plugin is what a deployment usually starts from:
import { mkdtemp } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { Arbor } from "@4fu/arbor-core";
import { DirectoryEnvironment } from "@4fu/arbor-environment-dir";
import { SqliteJournal } from "@4fu/arbor-journal-sqlite";
import { SqliteNoteStore } from "@4fu/arbor-notes-sqlite";
import { ProcessSupervisor } from "@4fu/arbor-supervisor-process";
import { DirectoryWorkspace } from "@4fu/arbor-workspace-dir";
import { PiAgentBackend } from "@4fu/arbor-agent-pi";
import { HttpChannel, httpPlugin } from "@4fu/arbor-plugin-http";
const root = await mkdtemp(join(tmpdir(), "arbor-"));
// Every module below is a default implementation of an interface. Replace any
// one by passing your own; the host does not change.
const journal = new SqliteJournal({ path: join(root, "journal.sqlite") });
const notes = new SqliteNoteStore({ path: join(root, "notes.sqlite"), journal });
const supervisor = new ProcessSupervisor({ root: join(root, "services") });
const environment = new DirectoryEnvironment({ root: join(root, "env"), supervisor });
const workspace = new DirectoryWorkspace({ root: join(root, "workspaces") });
// A plugin adds; it never patches the core. This one is a chat channel: a
// webhook in, a window's sends out, and a page that drives the whole host.
let arbor;
const channel = new HttpChannel({ host: "127.0.0.1", port: 8787, board: () => arbor.boardLines() });
arbor = new Arbor({
journal,
notes,
backend: new PiAgentBackend(),
workspace,
environment,
supervisor,
plugins: [httpPlugin({ channel })],
});
await arbor.start();
await channel.listen();arbor.open(task) dispatches one task, and the journal is where everything that
happened can be read back (docs/journal.md). The workspace a
window gets, and how a continuation keeps working in it, are in
docs/workspaces.md.
| Package | What it is |
|---|---|
@4fu/arbor-interfaces |
every replaceable interface, plus the core's own shapes. Types only. |
@4fu/arbor-errors |
the error shape every refusal uses: the rule and the next action |
@4fu/arbor-prompt |
typed blocks, the one deterministic renderer and the replaceable text table |
@4fu/arbor-tools |
the entry points: direct tools, code mode modules, the host API |
@4fu/arbor-journal-sqlite |
the default Journal and BlobStore on SQLite |
@4fu/arbor-notes-sqlite |
the default NoteStore on SQLite, beside the journal |
@4fu/arbor-segmenter-jieba |
the default Segmenter: jieba's dictionary segmentation for the word index, optional |
@4fu/arbor-lexical |
the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
@4fu/arbor-search-zvec |
the optional semantic channel: event text embedded and searched by meaning with zvec |
@4fu/arbor-workspace-dir |
the fallback Workspace: one directory per window, with a continuation working in its predecessor's directory in place |
@4fu/arbor-workspace-ovnfs |
the default Workspace when ovnfs is installed: one shared folder, per-window copy-on-write checkouts the model opens and applies back |
@4fu/arbor-environment-dir |
the default Environment: one /env directory, a revision per item, validation and deltas |
@4fu/arbor-supervisor-process |
the default Supervisor: one host process per service, restart with backoff, logs |
@4fu/arbor-judge-jev |
the default Judge: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
@4fu/arbor-agent-pi |
the default AgentBackend: pi-agent-core in process |
@4fu/arbor-plugin-http |
the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
@4fu/arbor-core |
the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects and schedules |
Every default above is a reference implementation of its interface, written to be read and replaced. A real deployment is expected to swap out the ones that do not fit: the SQLite journal and notes, the directory workspace, the process supervisor, the environment directory, the HTTP test plugin and the Jev judge are all examples of what an interface can be satisfied by, not commitments. What a deployment keeps is its own choice, and the interfaces are the contract (docs/architecture.md).
Each package's own documentation holds the limits of that default, so a deployment can see what it would be taking on before it adopts one.
| Page | Contents |
|---|---|
| docs/overview.md | goals, concepts, principles, routes considered |
| docs/architecture.md | layers, interfaces, stack, models, plugins, hooks, data placement |
| docs/journal.md | events and their order, targets, watermarks, external ids, refs, tracing, media, redaction |
| docs/windows.md | window lifecycle, prompt layout, reminders, continuation |
| docs/dispatch.md | task sources, judge decisions, insertion timing, backpressure, scheduled tasks |
| docs/coordination.md | the board, expectations, deliveries and broadcasts, staying current, effects |
| docs/environment.md | skills, MCP servers and services: using, changing, reload, built-in skills, deltas |
| docs/memory.md | notes, the active set, anchors, links |
| docs/workspaces.md | the shared folder and per-window checkouts: isolation, continuity, what the agent does |
| docs/tools.md | direct tools and code mode modules |
| docs/prompting.md | how every model-facing text is written: layers, notes, deliveries, errors, judge questions, terms |
| docs/release.md | calendar versioning, the manual release steps, how a package is published |
pnpm check typechecks and tests every package on its TypeScript sources.
pnpm build emits the dist publishing needs, and pnpm pack shows what each
tarball would contain (docs/release.md).
| Path | Layer |
|---|---|
packages/interfaces |
the interfaces layer: every replaceable interface, plus the core's own shapes. Types only. |
packages/errors |
the error shape every refusal uses: the rule and the next action |
packages/journal-sqlite |
the default Journal and BlobStore on SQLite |
packages/segmenter-jieba |
the default Segmenter: jieba's dictionary segmentation for the word index, optional |
packages/lexical |
the lexical search the journal and notes share: word segmentation, the FTS5 helpers and the merge order |
packages/notes-sqlite |
the default NoteStore on SQLite, beside the journal |
packages/judge-jev |
the default Judge: Jev, TypeSafe AI's System One classifier, answering the dispatch decisions |
packages/workspace-dir |
the default Workspace: one directory per window, with a continuation working in its predecessor's directory in place, and the lookup of another window's directory it contributes to the catalog |
packages/environment-dir |
the default Environment: one /env directory, a revision per item, validation and deltas |
packages/supervisor-process |
the default Supervisor: one host process per service, restart with backoff, logs |
packages/plugin-http |
the HTTP test channel: a webhook in, sends out, a page that drives the whole host |
packages/prompt |
typed blocks, the one deterministic renderer and the replaceable text table |
packages/agent-pi |
the default AgentBackend: pi-agent-core in process |
packages/tools |
the entry points: direct tools, code mode modules, the host API |
packages/core |
the service layer: one implementation of every operation - the window lifecycle, dispatch, coordination, the board, notes access, workspaces, effects, schedules and the snapshot epochs |
mise.toml pins the toolchain - Node and pnpm - installed under
~/.local/share/mise, and .agents/setup prepares a machine from it. A machine
without mise is expected to carry Node 24 or newer and pnpm 12 already.
MIT, see LICENSE.