The kit
A memory substrate you own, a methodology-core seed, an activation layer wired through your harness's hooks, and a scripted onboarding that fills the seed so your partner is uniquely yours from session one.
Cognitive-partnership infrastructure
Levain
Ship the seed, not the fossil.
A grown cognitive-partnership methodology can't be shipped as a methodology. Hand someone the finished artifact and they get a fossil. So Levain ships the engine that grows one — a memory substrate you own, a methodology seed, an activation layer that fires on its own, and a scripted onboarding. Your practice accretes from your own sessions, which is why it sticks, and why it's yours.
ClaimReceipt
Sovereignty is a property of the import graph.
The firing tier — everything that lets an open model act as a sovereign entity — imports nothing from the rest of the package. Not by convention, not by review discipline. It physically cannot reach back into the kit, which is what makes it harness-neutral rather than merely described that way.
Structural
levain/firing/ → zero outward edges
every module in the tier, the OpenHands sub-package included
checked by walking each import, function-level ones too
read the tier
A practice transfers as a living starter or not at all.
The proof isn't the endpoint, it's the trajectory. One continuity file rendered at four points across five calendar months: it grew, hit one architectural cliff, then locked into a shape and kept densifying inside it. Your week one looks like the first snapshot — not the last, which is what this operator's partnership grew into.
Accrual
96 → 549 lines, 6 → 9 sections
four snapshots over five months
growth_timeline.md
Your memory lives on your machine, in a store you own.
The store is a local SQLite file. The browser view binds loopback
only and refuses non-loopback hosts. It serves its own UI from the
package, so it renders offline with no CDN. No vendor host, no
account, nothing to revoke. Two model calls can leave the
machine, both on a sovereign entity: the conversation
(levain run --model, which also composes the memory
when run wraps itself) and a standalone
levain wrap --composer. Both default to
glm-5.2:cloud, served through Ollama Cloud; point
them at a plain local Ollama name to keep them on your machine.
Shipped
Levain
Apache-2.0
built on anneal-memory
pypi.org/project/levain
Nothing reaches long-term memory except through a path you govern.
Every edit you make goes through one governed dispatch that records it, so the writable view doubles as an audit log of what you did. Episodes the entity writes, including the Claude Code memory notes Levain mirrors in (one way, on by default, one setting turns it off), land in anneal's hash-chained audit trail, and only a wrap decides what of them becomes long-term memory. The edit-class and zone grammar is enforced at the surface, not requested politely: read-only regions refuse edits rather than trusting a caller not to try.
Governed
one write path, one audit envelope
zones identity / operate / mind
edit classes A / B / C
extensions ride the same auth, confirm and audit envelope
What's actually in the wheel
Three products, one install
Levain is usually described as a kit, which is true and incomplete. It ships three distinct things that share a substrate. The third has been in the wheel for a while without a public description; this is it.
The operator surface
Your partner's memory normally only exists inside a session. These look at it from outside, and let you steer it: a terminal glance, a full-screen TUI, and a live loopback browser view that turns writable with one flag.
The sovereign entity runtime
An entity REPL on an open model, and a consolidate that folds
what it learned into its own lasting memory: you run it with
levain wrap, and a governed seat runs it itself
after a turn once enough has built up. Underneath sits the
firing tier: the harness-neutral contract, the presence seam,
the isolation guard, and the confinement floor. The same entity
can run on a schedule as a governed seat, and by default every
action it takes that reaches outside itself halts before it
runs and leaves the log for you to read. That default can be
switched off per entity; it is not a lock.
The confinement floor
The polarity is inverted on purpose
A sandbox for a coding agent is normally a jail: deny by default, then allow the workspace. That shape is wrong for an entity that is supposed to do real work on a real machine — it spends its life fighting the cage, and every escape hatch you cut weakens the whole thing.
The step-6 file jail was (deny default) → allow the workspace — a JAIL. A replacement inverts it: (allow default) → DENY the crown jewels.
So the floor allows by default and denies a small, explicit, absolute-path-pinned set: the sovereignty crown jewels. The entity works like any normal shell, and the handful of things that must never be readable or writable stay denied whatever the model is told, across every route the floor knows how to close. It is a floor, not a guarantee: the source names the routes it has not closed yet. The module needs only the standard library and one sibling inside the firing tier, so the floor is unit-testable in complete isolation from the thing it protects.
The most load-bearing module in the package.
Denies by absolute path, so a relative-path trick can't walk out of it.
Credential stores are opt-in, not always-on: denying their read breaks the entity's own tooling, and operational fit beats purity.
Boundaries, kept honest
What it does not do yet
A floor that oversells itself is worse than no floor, because you plan around the coverage you think you have. These limits are recorded in the source itself, not just here.
The floor protects the crown jewels and nothing else.
With default-allow, a confabulating model can still destroy a
real repository, force-push, or pipe a download into a shell,
and the floor stops none of it. What covers the rest is a
separate mechanism, the efferent gate: when nobody is watching
(a scheduled seat, or run --task) every action that
reaches outside the entity halts before it runs. In the
interactive REPL the gate is off and you are the check. Setting
efferent_gate: "ungated" turns it off everywhere,
scheduled seats included. What is still
not built: per-domain
threshold policy, so nothing graduates to unattended action.
No security absolutes. The confinement floor is real and
load-bearing, but it is a floor, not a guarantee. It denies a
fixed set of crown-jewel paths and known escape routes, not
"everything dangerous." It denies paths, and it checks names:
before a shell starts it refuses bash if any crown-jewel file has
a second name (a hardlink) anywhere on disk, and the file editor
refuses a path that is another name for one. A link another
process makes after that check, and a copy of a jewel, are not
covered; both are listed in the changelog.
Read the module docstrings in
levain/firing/confinement.py before trusting it
with something that matters.
Harnesses: Claude Code and Codex CLI are hook-wired. OpenHands is hookless and scaffolds a sovereign entity instead. One adapter per install — separate installs if you need more than one.
Always-on daemon and governed seats: macOS
(launchd) and, from 0.5.0, Linux
(systemd --user). Windows Task Scheduler is
planned, not shipped. The sandboxed shell a sovereign entity
works through runs on macOS and Linux (bubblewrap); on Linux it
has no IP network while the entity's floor blocks connections
back to the host. On Linux, bash is refused, with no opt-out, when a crown jewel is a SQLite database at the moment the shell starts (the shell could plant or read its sidecar files); move the store into a directory, as ~/.anneal-memory/ normally is, and the file editor works meanwhile. Since 0.5.3 the shell is also re-checked before every command: if anything it was denied has been replaced, or a database sidecar has appeared beside a jewel, the shell is closed and the next command starts a fresh one over what is there now. The check runs between commands, not during them, so a command that is already running, or one started in the background, keeps its access while it runs, and an encrypted (SQLCipher) store is not recognised. Both are listed as known open issues in the changelog. Elsewhere it gets the file editor and no shell.
One seat at a time: a governed seat runs one entity on one schedule. Coordinating several seats as a fleet is not built yet.
Codex hook reliability: recent Codex versions have a
platform-level hook-trust gap no consumer can work around.
levain verify-hooks proves your scripts fire
correctly by invoking each one with the JSON a harness would
send; whether Codex itself invokes them at runtime is up to Codex.
Install
Two commands to a working partner
pip install levain
levain init --path ./my-partner
That creates the directory, runs the interview, lays down the seed,
registers the adapter you choose, initializes the store at
.levain/memory.db, and records the exact version set it
composed. Then open that directory with Claude Code or Codex and
start working.
levain init --web # browser form instead of the terminal interview
levain doctor # loud, in-environment health check
levain update # reconcile the whole stack to known-good
levain serve # live loopback view of your substrate
levain serve --write # ...and steer it, through the governed path
Levain composes a stack across two version lines that
pip alone can't keep aligned: the library, versioned on
PyPI, and your methodology seed, versioned inside Levain.
pip keeps the library compatible but is blind to
methodology drift — a new memory feature can land as a contradiction
with your older, hand-tuned instructions instead of a clean addition.
That drift is what breaks a long-running install, so
doctor and update exist to hold the set
together.
Build on it
One published seam
Writing your own surface over the substrate?
levain.kernel is the published seam: the data model, the
terminal and web drivers, and the governed write and action dispatch.
Import one namespace instead of reaching into internals. Register
extra read-only panels or extra governed verbs and they ride the same
auth, confirm and audit envelope as the built-in edits. It's a pure
re-export — the governance lives in the substrate, not the surface.
The division of labour with the substrate is the whole idea: anneal-memory is the substrate; Levain is the harness that fires it. anneal-memory deliberately can't reach into your session — a memory library that hooked every prompt would forfeit the neutrality that lets it run under any harness. So on its own it gives you the stores and manual recall, and Levain wires the hooks that surface the right memory automatically. Clean dependency direction, both on PyPI: Levain depends on anneal-memory, never the reverse.
Who it's for
Operator-class developers: the people who already feel session amnesia as a real problem and would otherwise build their own fix. If you've written your own substrate-management scripts, you'll recognize the pieces. If continuity file and session-closing reflection don't land yet, this probably isn't your tool yet.