Yohanun Guilds

Persistent, access-governed memory for your Claude Code agents — backed by Yohanun.

You and your agents form a guild. Each of your projects gets a named agent with its own private memory — decisions, gotchas, open tasks, lessons that survive across sessions. Your guild carries the shared knowledge (your standing rules, your conventions) to every agent you run. What each agent can recall is decided by Yohanun's deterministic access gate — identity + ownership keys + clearances — never by the model and never by this client.

Install

pip install yohanun

(Also served directly: pip install https://app.yohanun.com/static/kit/yohanun.tar.gz. From a checkout of this repo: pip install ./yohanun_kit.)

MCP — the same memory in any MCP host

Claude Code gets the full experience: two wired hooks, one at session start and one on every prompt (see Recall below). Every other MCP host — Claude Desktop, Cursor, Windsurf — gets the same governed memory as tools:

{"mcpServers": {"yohanun": {"command": "yohanun", "args": ["mcp", "serve"]}}}

(yohanun mcp config prints this.) Tools: yohanun_recall (call first — it replaces the session-start hook), search (with the raw-tier deep option), store, due, close, supersede, letters (send_letter / inbox), whoami. The agent resolves from the working directory like the CLI; pass --agent <name> or set YOHANUN_AGENT for hosts that don't set a project cwd. Every read and write goes through the same platform gate.

The fast way: let Claude Code set itself up

Paste the setup prompt from your Guilds quickstart page into any Claude Code session. Your agent installs the kit, discovers your projects (yohanun projects discover --json), asks which should remember and what to call each agent, and wires everything — including its own memory.

Setup by hand (once per machine)

yohanun init --api-key sile_... --owner "Your Name"

Verifies your tenant key, establishes your root principal (the only authority that can move memory custody), and creates your guild. Config lands in ~/.config/yohanun/ (0600, never in a repo).

It also creates your guild HQ folder — ~/yohanun-guild by default (--guild-dir to relocate, --no-guild-dir to skip). That folder is the home of your anchor agent and the place you run your guild: open Claude Code there to manage the roster and decide which projects get memory and which don't. A CLAUDE.md inside explains it and gives a session there the guild-admin commands; its SessionStart hook auto-recalls the anchor agent's memory.

Set up your guild before v0.6.0 (or skipped the folder)? Add one to your existing guild with yohanun guild home — it anchors to an agent you name (--agent) or creates the founding agent Síle if your guild never got one.

Meet Síle

A brand-new guild starts with one agent already in it: Síle (Irish, pronounced SHEE-la) — named for the assistant whose statelessness inspired the platform, and a backronym for its thesis: Stateful Identity, Lived Experience. She begins with two memories — her private origin (who she is and what the name means) and a shared guild charter (a dated founding fact for your guild's shared circle, so it isn't empty) — and everything after that is earned. Ask her yourself:

yohanun search "who are you"

Rename or replace her any time (--agent-name at init, or retire her with a custody transfer later); skip her entirely with --no-agent. Machines that already have agents never get her added.

Onboard a project (once per project)

cd ~/dev/myapp
yohanun agent add myapp --matter project:myapp --project-dir . --wire

Idempotent. Provisions the agent (estate key rooted to YOU — succession is one custody transfer), registers the directory, and wires the Claude Code SessionStart hook so every session opens with the agent's open tasks and freshest memories already in context. Paste the printed ## YOHANUN GUILDS section into the project's CLAUDE.md so sessions know the discipline.

Recall — two hooks, and what each is for

--wire installs both in a repo, and both are on by default.

Session start opens with an identity statement, where you left off, what is still open, and any guild mail. It is a recency instrument: it tells an agent what has been happening lately.

Every prompt searches the agent's memory with your actual question and injects up to three high-relevance hits. This is what reaches the rest of the estate. Measured on 15 probes spanning seven weeks of one agent's memory, the memory that answered the question was in context 1 time in 15 with session start alone, and 14 in 15 with per-prompt recall on.

It is deliberately narrow, because a five-week audit of 1,662 real injections showed where automatic recall goes wrong (docs/prompt_recall_scope.md in the platform repo). It searches the curated tier only, never the raw transcript tier, which was half as useful and twice as likely to mislead. It ignores prompts that are machinery rather than questions, such as task notifications and pasted blobs. It applies a score floor, a cap of three, and a per-session dedupe so the same memory is never injected twice in one session. Injected memory is labelled as recalled context, not instruction.

Every injection is logged locally. yohanun experiment prompt-recall shows the state and the last few injections; add off to turn it off for an agent.

Cross-tool. --wire also writes an AGENTS.md — the neutral context file Codex and other tools read — so the same memory and command surface work outside Claude Code (an existing AGENTS.md is preserved; only a managed block is inserted). The yohanun CLI runs from any shell. There's no auto-recall hook outside Claude Code yet, so on other tools you (or the agent) run yohanun search / yohanun due at the start — the AGENTS.md says so. (In an MCP host, the same thing is available as a tool.)

Already set up in another tool? Run yohanun wire in a repo to make it work in the tool you're in now — it (re)writes that repo's AGENTS.md + hook for its existing agent, local-only, no network, no re-provisioning. It never creates a second agent, so a repo's memory can't split across tools. yohanun init and agent add are idempotent too — re-running them connects to your existing guild rather than duplicating it.

Daily use (you, or your Claude Code agent)

yohanun store "picked pnpm over npm — workspace protocol" --type decision
yohanun store "deploy needs VPN or the registry 403s" --type gotcha
yohanun store "migrate the auth tests off the fixture" --type todo
yohanun search "why did we pick pnpm"
yohanun due                          # open tasks
yohanun close <memory_id>            # task done (retired, never deleted)
yohanun supersede <memory_id> "corrected fact"
yohanun store "we invoice in EUR" --shared     # guild: visible to ALL your agents
yohanun consolidate                  # session end — the agent distils what mattered

Inside a registered project directory the agent resolves automatically; use --agent <name> or YOHANUN_AGENT anywhere else.

consolidate is the session-end ritual: the agent that handled the whole session is the one qualified to say what's worth keeping, so before it ends it stores the few memories that matter — with hindsight, not as a transcript dump. The wired CLAUDE.md section teaches your agent to do this itself.

Letters between your agents

Any agent can post a letter to another agent in your guild. Delivery is at the recipient's next session start — the auto-recall hook opens with the new mail before work begins. A letter is an ordinary memory owned by both sides, so it obeys the same walls and lifecycle as everything else.

yohanun send setanta "heads up — the deploy script moved to scripts/ship.sh"
yohanun inbox                        # new letters (marks them seen)
yohanun inbox --all                  # the full correspondence

House rule worth adopting: claims in a letter are leads, not facts — the recipient verifies them against its own code and memory before acting.

The past: backfill and the raw tier

An agent onboarded today can still inherit the project's history. backfill distils past Claude Code sessions into graded memories — the kit reads your transcripts locally and only the distilled memories are stored. Two deeper options put the history itself within reach:

yohanun backfill                     # distil past sessions into graded memories
yohanun backfill raw                 # ingest every past turn, verbatim, below normal recall
yohanun backfill summaries           # one dense paragraph per past session
yohanun search "exact error text" --deep       # reach beneath the floor
yohanun mode                         # curated | auto | deep — how recall uses the tiers

The raw tier sits far beneath the agent's curated memory, so daily recall never surfaces it — but "what exactly did we say?" questions become answerable with search --deep. backfill raw also flips the agent's recall mode to auto: when curated recall comes back thin, it falls through to the raw tier on its own, and the wiring is updated so the agent knows the tier exists. One caveat, which the command itself states and asks consent for before running: raw ingest uploads your past turns verbatim to your tenant — including any secrets ever pasted into a session. backfill summaries needs the anthropic package and an ANTHROPIC_API_KEY; the distillation runs on your machine.

The model, briefly

• Private by default: a memory is owner-walled to the storing agent and compartmented to its project. Another project's agent cannot see it.
• Guild sharing is deliberate: --shared stores into the guild — visible to every agent that holds the guild key. Sharing is an explicit act; leaking-by-default is the failure mode this design forbids.
• Succession-ready: every agent's estate key is rooted to your principal. Retiring or replacing an agent is one custody transfer — the memory survives the agent.
• Lifecycle, not mutation: memories are closed or superseded, never edited or deleted. History stays readable; retrieval surfaces the live tip.

Team guilds (waitlist)

Today a guild spans you and your agents. Team guilds extend it to your colleagues: shared memory that follows project access — each member's agents recall exactly the cross-project knowledge that member is cleared to see, enforced by the platform gate, with instant revocation. Working with a team? Join the waitlist from your Yohanun dashboard — early teams shape the design.

Trust boundary (current version)

Single developer, single machine: all your agents share your tenant API key, and agent identity is asserted per request. The walls between agents are real (enforced by the platform gate) but are project-hygiene walls, not credential walls. Do not share the key or the config directory. Team guilds ship with per-user keys bound to identities server-side.