regesto

README

Regesto

A local knowledge base your agents consult—not another memory cache.

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, recording its date, source, and subject.

Agents forget, compress, and rewrite their own memory. Regesto keeps the decisions you want to preserve as plain Markdown files you own. Before an agent acts, it can search those files for the relevant project decisions, preferences, conventions, and environment facts.

Regesto is designed around three ideas:

• one durable claim per Markdown file;
• a validated way for agents to search and write claims;
• visible history: an outdated claim is marked superseded, not deleted.

For example, a project decision can look like this:

---
id: dec-sessions-not-jwt
title: Sessions are server-side
type: decision
scope: project:aurora
subject: auth
relation: session-transport
status: active
source: human
---

Session state lives server-side. The cookie contains only an opaque identifier.

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

The subject and relation identify what the claim is about. If that decision changes, Regesto can find the previous claim exactly instead of relying on fuzzy similarity.

Quick start

This path is for the built-in Antigravity, Claude Code, Codex, Copilot, Hermes, OpenCode, and Pi integrations. For another client, skip to Connect another agent.

1. Install Regesto

brew install prof18/tap/regesto

You can also use go install github.com/prof18/regesto/cmd/regesto@latest or download a binary from GitHub Releases.

2. Create a knowledge base

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

This creates a local folder containing your facts, configuration, agent adapters, and helper commands. The folder name and location are up to you. Remove --examples if you want to start empty.

During initialization, Regesto detects supported agents installed on this machine and adds them to config.toml. Check that the list matches the agents you want to connect:

integrations = ["antigravity", "claude", "codex", "copilot", "hermes"]

Keep only the integrations you use. Detection is an initial suggestion, not a permanent setting.

3. Connect the agents

regesto install --dry-run
regesto install
regesto doctor

The dry run shows planned changes and summarizes files already up to date. Installation adds the appropriate skills and instructions, registers supported hooks, and backs up host files before editing them. It is safe to run again.

doctor is read-only. It reports what is installed, what needs attention, and the exact remediation for manual steps.

4. Start a new agent session

Open a new session from one of your projects so the agent reloads its hooks, skills, and instructions. Then try:

Remember that Regesto releases are built and signed on the release Mac.

The installed regesto-write skill records the fact through Regesto's validated write path. In a future session, the agent can find that decision before acting.

That is the complete manual workflow. Automatic harvesting and multi-machine sync are optional.

What each built-in integration does

Agent	How it consults Regesto	Setup notes
Antigravity	A first-invocation hook injects relevant context as JSON steps before the first model call of each conversation	Antigravity setup
Claude Code	A session-start hook injects relevant context automatically	Claude Code setup
Hermes	A first-turn hook injects relevant context when its hook registration is current	Hermes setup
Copilot	A session-start hook injects relevant context as JSON before the first turn; the same install covers Copilot in VS Code	Copilot setup
Codex	Persistent instructions tell it when to search; skills provide the search and write procedures	Codex setup
OpenCode	An auto-discovered plugin injects relevant context on the first message of each session	OpenCode setup
Pi	An auto-discovered extension injects relevant context on the first prompt of each session	Pi setup

Antigravity, Claude, Copilot, Hermes, OpenCode, and Pi can enforce consultation at their supported hook boundaries. Codex has no equivalent built-in startup hook, so its consultation is instruction-driven. The integration matrix contains the exact capability reference.

Connect another agent

Choose the first option your client supports:

Client capability	Use
Local skills or a persistent instructions file	Configure a custom integration with the generic profile
Local stdio MCP servers	Launch regesto mcp from the client
Neither	Export the conversation and run regesto promote

Connect any agent to Regesto walks through each path. The custom-agent section is intentionally more detailed because Regesto cannot safely guess an unknown client's paths, memory format, or hook protocol.

Optional: capture agent memory automatically

Direct writes are the safest way to preserve important facts. Regesto can also watch the native memory of configured agents and turn new material into canonical facts:

regesto schedule install
regesto schedule status

The scheduled workflow runs two operations:

• regesto harvest copies new native-memory changes into inbox/;
• regesto cycle normalizes captures, resolves contradictions, rebuilds indexes, and commits a clean pass.

The first harvest only notes the memory your agents already have; it collects what changes after that. To bring in that existing memory as well, answer yes when regesto init offers it, or run regesto harvest --backfill once. It lands in inbox/ like any other capture, and the next regesto cycle turns it into facts. Harvest reads Claude Code, Codex, and Hermes memory. Antigravity, Copilot, OpenCode, and Pi keep no memory files, so there is nothing to collect.

On macOS, schedule install uses launchd. On other systems, schedule regesto harvest and regesto cycle with your preferred job runner.

Cycle health and external alerts

When a cycle is failing, regesto context on the machine that runs it puts the failure reason and start time at the top of agent context and tells the agent to treat generated indexes as stale. Antigravity, Claude, Copilot, Hermes, OpenCode, and Pi receive that warning through their context hooks. Codex has no startup hook, so use regesto context or regesto schedule status when diagnosing its instance.

Regesto does not send desktop notifications itself. A CLI cannot provide a consistent click action across macOS, Linux, and other environments. If you want an external alert, configure the executable or CLI you already use:

[notify]
command = "/absolute/path/to/my-notifier --fixed-option"
renag_hours = "24"

notify.command is whitespace-separated: the executable path and each fixed argument must not contain spaces. Shell syntax, or a path with spaces, requires a wrapper script at a whitespace-free path; the command is not run through a shell.

Regesto executes the command directly when the cycle starts failing, recovers, or reaches the reminder interval. It appends the notification title and message as the final two arguments and also sets these environment variables:

• REGESTO_NOTIFY_KEY — currently cycle;
• REGESTO_NOTIFY_STATE — failing or ok;
• REGESTO_NOTIFY_TITLE;
• REGESTO_NOTIFY_MESSAGE.

The command is optional; without it, cycle health still appears in agent context on the cycle machine and in regesto schedule status. Set on = "off" to temporarily disable a configured command, or renag_hours = "0" to report state transitions without reminders. Because the command is not run through a shell, put pipelines, redirections, quoting, or other shell behavior inside that wrapper script.

More than one machine

Regesto has no sync server. Put the knowledge-base folder in a file-sync tool that keeps a full local copy on each machine, and exclude .state/ and .git from syncing.

Each machine harvests its own agents. Only one machine should run regesto cycle and own the Git repository. See multi-machine setup for the safe order and failure modes.

Everyday commands

Run commands from the knowledge-base directory, or pass --config /absolute/path/to/config.toml after regesto.

Command	Purpose
regesto search	Search facts by text, subject, relation, or scope
regesto write	Validate and record one structured fact
regesto doctor	Diagnose integration setup without changing files
regesto install	Install or refresh configured agent integrations
regesto harvest	Capture changes from configured agent memory
regesto cycle	Normalize captures, reconcile facts, rebuild indexes, and commit
regesto promote	Extract facts from an exported conversation
regesto lint	Validate the knowledge base and report contradictions
regesto config	Show the resolved instance configuration

Use regesto <command> --help for the complete options.

Updating and removing Regesto

After updating the binary, refresh the engine-owned files in the knowledge base:

cd ~/regesto-kb
regesto upgrade --dry-run
regesto upgrade

Regesto leaves files you changed alone and reports them. --force overwrites customized engine-owned files only after backing them up.

To remove scheduled jobs, run regesto schedule uninstall. To disconnect an agent, inspect regesto install --dry-run --json, then remove only the reported Regesto links, hook entries, and the marked regesto:section:start / :end block from the agent's instructions. Regesto does not remove host-owned configuration automatically.

Documentation

• Connect any agent — custom local agents, MCP clients, and conversation exports.
• Integration matrix — exact capabilities and built-in profile metadata.
• Multi-machine setup — sync rules and adding another machine.
• Schema — what a fact is and how supersession works.
• Design — architecture and tradeoffs.
• Contributing — development workflow and compatibility rules.

Requirements

Go 1.26 is required to build from source. Most commands are portable; the built-in scheduler currently targets macOS launchd.

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.