regesto

README

Regesto

A knowledge base your agents consult — not a memory they carry.

Regèsto (Latin regĕsta, "carried back"): an archivist's register of an archive too large to read end to end — one short entry per document, giving its date, its source and what it is about. Nineteenth-century historians compiled them for medieval collections that could never be published in full.

Every coding agent now ships a memory file. All of them are working-set caches: bounded, pruned by the agent to stay under a cap, lossy by design. That is right for a cache and wrong for the decisions you spent a week arriving at.

Regesto keeps those decisions in plain markdown you own, one claim per file, and makes the agent read them before it acts. Nothing is ever deleted — a claim that stops being true is marked superseded and stays on disk, because how you used to think is part of the knowledge.

knowledge/facts/projects/aurora/dec-sessions-not-jwt.md

---
id: dec-sessions-not-jwt
title: Sessions are server-side; the cookie carries only an opaque id
type: decision
scope: project:aurora
subject: auth
relation: session-transport
status: active
source: human
---

Session state lives server-side. The cookie carries an opaque identifier and nothing else.

**Why:** revocation has to be immediate.

subject + relation are the identity of a claim. Two files sharing that pair assert the same thing, so contradiction is a lookup rather than a guess — which matters, because similarity search cannot do this job. A value flip 8000 → 8080 is more embedding-similar to the original than an honest rephrase is.

---

Quickstart

Ten minutes, one machine, one agent.

1. Install the engine.

brew install prof18/tap/regesto

Or go install github.com/prof18/regesto/cmd/regesto@latest if you have Go, or grab a binary from releases.

2. Create your instance. It is a folder of markdown; put it wherever you keep things you would miss.

regesto init --dir ~/regesto-kb --examples

regesto-kb is just this guide's name for that folder, not a required one — name it whatever you like, and read it back into every later example here as whatever you chose.

That writes the tree, a commented config.toml, both ignore files, this machine's identity, the bin/ shims, the agent adapters, SCHEMA.md, and a handful of example facts to imitate. Drop --examples for an empty one.

3. Install the adapters into your agents.

~/regesto-kb/bin/regesto-install --dry-run   # see what it would touch
~/regesto-kb/bin/regesto-install

Skills are symlinked into each agent, the SessionStart hook is registered (Claude Code), and a short pointer section is appended to your instructions file. It backs up anything it edits and is safe to re-run. This runs for every agent in agents in config.toml, which init already set to whichever it found installed on this machine — edit it if that guess was wrong.

4. Open a session in a project. Its facts are already in context — you did not ask for them, and the agent did not have to decide to look.

5. Record something. Tell the agent "remember that migrations here are forward-only", or run /regesto-write. The fact lands in knowledge/facts/, schema-correct, with a **Why:** line.

That is the whole loop. Everything below is optional.

---

Optional: the automatic half

cd ~/regesto-kb && regesto schedule install    # harvest every 15 min, cycle hourly (launchd, macOS)

LaunchAgents do not read shell startup files. At install time Regesto gives them a deterministic PATH: the directories of the configured normaliser and notifier commands it can resolve, followed by stable user, Homebrew and system locations. For a CLI installed somewhere uncommon, add its directory with [schedule].extra_path and run schedule install again. Keeping this at the scheduler boundary also covers interpreters such as node; using absolute paths for claude or codex alone would not.

Commands other than init and the six with a bin/regesto-* shim (install, search, context, config, index, project) resolve their instance from the working directory, so run them from inside ~/regesto-kb — or pass --config ~/regesto-kb/config.toml from anywhere else.

• regesto harvest diffs each agent's native memory against a per-machine snapshot and files anything new in inbox/. It needs no cooperation from the agent — anything it wrote down gets picked up whether or not it used the skill.
• regesto cycle normalises those captures into facts, reconciles contradictions, rebuilds INDEX.md and the topic pages, and commits.

The cycle stops at the first validation error and commits nothing, which is correct — half a reconciliation is worse than none — but it means one malformed fact halts the whole thing while facts keep being written. Since it runs unattended, it tells you: a notification when it starts failing, another when it recovers, and one reminder a day in between. A working pass says nothing. regesto schedule status prints when the last clean pass was, which is the one thing a failing cycle cannot tell you itself — a job that never fires never reports anything at all.

macOS uses osascript, Linux notify-send. To send them somewhere else — a phone, a chat channel — point [notify].command at any program; it gets the title and message as its last two arguments. [notify].on = "off" disables it.

---

More than one machine

Get the folder onto both machines. That is the entire mechanism — no server, no backend, no daemon of ours. Every machine holds a full replica and reads it locally, so an agent on a laptop greps the laptop's copy, offline on a train if need be. No machine ever queries another to consult knowledge.

How you move it is your choice. Syncthing, a hosted drive, unison on a timer — regesto asks only that the transport replicate plain files and let you exclude two directories. Nothing here is built against one vendor, and swapping later costs you nothing, because the knowledge was never in the tool.

Each machine gets its own engine, its own name, and its own harvest job, because native agent memory is local and nothing else can see it. One machine runs the lint pass, because deciding what becomes a fact has to happen in one place or two machines mint competing vocabulary for the same claim.

Two directories must never sync — .state/, whose per-machine baselines are what make harvesting work, and .git. Both are already in the ignore files regesto init writes.

docs/setup-sync.md — adding a machine, step by step, and what goes wrong.

---

Upgrading

Replacing the binary is half of it. regesto init also wrote files into your knowledge base — the bin/ shims, adapters/, SCHEMA.md — and a new engine does not touch them on its own:

cd ~/regesto-kb
regesto upgrade --dry-run   # what would change
regesto upgrade

It knows the difference between a file it wrote and one you changed, because init recorded a hash of each in .regesto-manifest. Files you edited are left alone and reported, never overwritten; --force overwrites them and backs each one up first. A file it cannot attribute — an instance older than the manifest — is treated as yours.

A file a release retires is removed, but only where it is byte for byte what the engine recorded writing. Edit it and it becomes yours: kept, reported, and no longer tracked. Anything with no recorded hash is never touched at all.

Then it finishes the job: re-renders the skills, relinks them into every agent, drops the ones that were retired, refreshes the instructions section and the hook, and repoints the scheduled jobs if they name an engine that is no longer the one serving this instance. A skill added or withdrawn by a release reaches your agents from this one command — nothing else to run.

Uninstalling

There is no single command, because regesto-install only ever adds to files it does not own outright. Reverse it by hand:

cd ~/regesto-kb && regesto schedule uninstall   # stops the launchd jobs, if you ran `schedule install`

Then remove the three things regesto-install touched: the SessionStart entry under .hooks in ~/.claude/settings.json, the block between the regesto:section:start / :end markers in your instructions file, and the regesto-search / regesto-write / regesto-promote symlinks in each agent's skills directory. Delete the instance directory itself (~/regesto-kb by default) to remove the knowledge base.

Commands

regesto search	query facts by subject, relation, scope or free text
regesto context	the payload the SessionStart hook injects
regesto index	rebuild INDEX.md and knowledge/topics/
regesto lint	validate against SCHEMA.md, reconcile contradictions
regesto harvest	capture native-memory writes into inbox/
regesto normalize	turn captures into canonical facts
regesto cycle	the whole downstream pass, then commit
regesto promote	a chat export → facts → archive
regesto project	the canonical project name for a directory
regesto config	the resolved instance config
regesto init	scaffold a new instance
regesto upgrade	refresh an instance's engine-owned files after the engine changed
regesto schedule	run harvest and cycle automatically
regesto version	which engine this is

---

Agents

Agent	Consultation	Setup
Claude Code	hook-enforced — deterministic	docs/setup-claude-code.md
Codex CLI	skills + instructions	docs/setup-codex.md
Others	skills + instructions	docs/setup-other-agents.md

Only Claude Code exposes a hook that can inject context before the first prompt, so only there is consultation guaranteed. Everywhere else it is likely. That difference is real and this project would rather state it than paper over it.

Adding an agent is a pull request that touches internal/adapters and adapters/, and nothing in knowledge/.

---

Read next

• SCHEMA.md — the contract. What a fact is, how supersession works, what to record and what not to. Read this before writing facts by hand.
• DESIGN.md — why it is built this way, including the research verdicts that saved a week.
• docs/setup-sync.md — running across several machines: the order to do it in, what must never sync, and the failure modes.
• CONTRIBUTING.md — one rule that matters: schema changes need a migration note.

Requirements

Go 1.26 to build. jq for hook registration. macOS for regesto schedule (launchd); the rest is portable, and the jobs are two commands you can run from any scheduler.

License

MIT.

Documentation

Overview

Package regesto carries the instance-side files that have to exist inside a knowledge base rather than inside the engine: the bin/ shims, the adapters (skills, hooks, instructions template) and the schema.

They are embedded rather than copied from a source tree because the engine is distributed as a binary — a released `regesto` has no repository to copy from, and `regesto init` still has to produce an instance that works. Embedding is what lets the two live apart (PLAN 4.a).

The templates keep their `{{kb_root}}` placeholder here; `bin/regesto-install` resolves it per instance.

Index

• Variables
• func Executable(path string) bool
• func InstanceFiles() (map[string][]byte, error)

Variables

var Adapters embed.FS

Adapters is the adapters/ tree: skills, the SessionStart hook and the instructions template. Dot-files are excluded, so the .gitkeep placeholders that keep empty vendor directories in git do not reach an instance.

var Examples embed.FS

Examples are the demo facts `regesto init --examples` copies in: an invented project with a controlled vocabulary worth imitating. An empty knowledge base gives an agent nothing to pattern-match against, and the first few facts set the vocabulary everything after them has to reuse.

var Schema string

Schema is the fact contract. It ships in the engine as the spec and lands in every instance as the document its write skill points agents at.

var Shims embed.FS

Shims are the bin/ entry points that hooks, skills and scheduled jobs call by a stable path. The built binary is deliberately not among them: it is per-platform, and an instance gets it from a release or a local build.

Functions

func Executable

func Executable(path string) bool

Executable reports whether an instance file needs the executable bit. Hooks and shims are run directly by agents and schedulers; nothing else is.

func InstanceFiles

func InstanceFiles() (map[string][]byte, error)

InstanceFiles is every file the engine owns inside an instance, keyed by its path relative to the knowledge-base root.

One list, used by both `init` (which writes what is absent) and `upgrade` (which refreshes what is stale). Two lists would drift, and the failure would be a file that init creates and upgrade never maintains.

Deliberately excluded: config.toml and the ignore files. Those are scaffolded once and then belong to the instance — an engine that rewrote them would overwrite the user's own settings.