Metadata-Version: 2.4
Name: yohanun
Version: 0.27.2
Summary: Yohanun Guilds — persistent, access-governed memory for your Claude Code agents
Author-email: GestureLoop Ltd <anton@gestureloop.com>
License: MIT
Project-URL: Homepage, https://yohanun.com/guilds
Project-URL: Documentation, https://app.yohanun.com/dev/guilds
Keywords: ai,memory,agents,claude-code,claude,llm,yohanun
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Dynamic: license-file

# Yohanun Guilds

Persistent, access-governed memory for your Claude Code agents — backed by
[Yohanun](https://yohanun.com).

**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

```bash
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 (SessionStart auto-recall via the
wired hook). Every other MCP host — Claude Desktop, Cursor, Windsurf —
gets the same governed memory as tools:

```json
{"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](https://app.yohanun.com/dev/guilds)
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)

```bash
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:

```bash
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)

```bash
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.

**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.

**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)

```bash
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.

```bash
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:

```bash
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](https://app.yohanun.com/dev/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.
