yohanun 0.26.2__tar.gz

yohanun-0.26.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GestureLoop Ltd
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yohanun-0.26.2/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: yohanun
+Version: 0.26.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`.)
+
+## 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.

yohanun-0.26.2/README.md

@@ -0,0 +1,187 @@
+# 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`.)
+
+## 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.

yohanun-0.26.2/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "yohanun"
+version = "0.26.2"
+description = "Yohanun Guilds — persistent, access-governed memory for your Claude Code agents"
+readme = "README.md"
+requires-python = ">=3.8"
+dependencies = ["requests>=2.25"]
+license = {text = "MIT"}
+authors = [{name = "GestureLoop Ltd", email = "anton@gestureloop.com"}]
+keywords = ["ai", "memory", "agents", "claude-code", "claude", "llm", "yohanun"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+Homepage = "https://yohanun.com/guilds"
+Documentation = "https://app.yohanun.com/dev/guilds"
+
+[project.scripts]
+yohanun = "yohanun.cli:main"
+# Back-compat alias: our pre-rename hooks call `gestureloop`.
+gestureloop = "yohanun.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["yohanun*"]

yohanun-0.26.2/setup.cfg

@@ -0,0 +1,25 @@
+[metadata]
+name = yohanun
+version = attr: yohanun.__version__
+description = Yohanun Guilds — persistent, access-governed memory for your Claude Code agents
+long_description = file: README.md
+long_description_content_type = text/markdown
+
+[options]
+packages = find:
+python_requires = >=3.8
+install_requires = 
+	requests>=2.25
+
+[options.packages.find]
+include = yohanun*
+
+[options.entry_points]
+console_scripts = 
+	yohanun = yohanun.cli:main
+	gestureloop = yohanun.cli:main
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

yohanun-0.26.2/yohanun/__init__.py

@@ -0,0 +1,12 @@
+"""Yohanun Guilds — persistent, access-governed memory for Claude Code agents.
+
+You and your agents form a GUILD: one tenant per user/org, named agents with
+memory of their own (one per project by default; an agent can run several
+related projects on one memory); memories owner-walled per agent,
+compartmented by a matter per project, with a shared guild circle for
+cross-project knowledge and addressed letters between agents. Retrieval is
+decided by the platform gate (identity + ledger-held keys + clearances) —
+never client-side.
+"""
+
+__version__ = "0.26.2"

yohanun-0.26.2/yohanun/api.py

@@ -0,0 +1,40 @@
+"""Thin HTTP client for the Yohanun API. Two flavors:
+
+- request(): returns (status, json) so provisioning code can branch on
+  409/403 without exceptions.
+- call(): exits with a readable error on any non-2xx — right for the
+  memory commands where any failure is terminal for the CLI invocation.
+"""
+import sys
+
+import requests
+
+from . import __version__
+
+
+def request(cfg: dict, method: str, path: str, body: dict = None,
+            timeout: int = 30):
+    try:
+        r = requests.request(
+            method, cfg["base_url"] + path, json=body, timeout=timeout,
+            headers={"X-API-Key": cfg["api_key"],
+                     "Content-Type": "application/json",
+                     "User-Agent": f"yohanun-kit/{__version__}"})
+    except requests.RequestException as e:
+        print(f"ERROR: Yohanun unreachable at {cfg['base_url']} "
+              f"({e.__class__.__name__})", file=sys.stderr)
+        sys.exit(1)
+    try:
+        payload = r.json()
+    except ValueError:
+        payload = {"raw": r.text[:300]}
+    return r.status_code, payload
+
+
+def call(cfg: dict, method: str, path: str, body: dict = None,
+         timeout: int = 45) -> dict:
+    status, payload = request(cfg, method, path, body, timeout=timeout)
+    if status >= 300:
+        print(f"ERROR: {path} -> {status}: {str(payload)[:300]}", file=sys.stderr)
+        sys.exit(1)
+    return payload