Agent Rulebook

Agent Rulebook is a local-first Resolution Memory for coding agents. It stores observed problems, immutable solution revisions, context-scoped outcomes, and exact source-evidence locators as portable YAML. A derived SQLite index provides retrieval; machine-local project paths never enter canonical data.

Install and initialize

npm install -g agent-rulebook
npx -y [email protected] --help
npx -y [email protected] mcp
agent-rulebook init
agent-rulebook index rebuild

[email protected] is an immutable package version. This checkout prepares the 0.3.2 local candidate; registry publication and runtime activation are pending. Registry tags such as latest are mutable and are not asserted by this artifact. Release receipts in docs/releases/ record artifact and runtime verification separately. Historical version 0.3.0 passed full registry acceptance on macOS arm64 with Node 26.2.0; see docs/releases/0.3.0.json. Use the exact version for reproducible MCP configuration.

The home defaults to ~/.agent-rulebook and can be overridden with AGENT_RULEBOOK_HOME. Portable Git data is limited to config.yaml, problems/, solutions/, and outcomes/. projects.local.yaml, index/, and logs/ stay local.

For an explicitly approved clean break from a legacy rules home, preview the exact deletion allowlist first. Execution requires an exact resolved home, the confirmation phrase, a Git worktree, and remote.origin.agentRulebookPrivacy=private:

agent-rulebook home reset --dry-run --json
agent-rulebook home reset --execute \
  --expected-home /absolute/path/to/.agent-rulebook \
  --confirm 'RESET LEGACY RULEBOOK' --json

Reset removes only legacy rules/ and the derived index/, then establishes the v3 bootstrap files and directories. It preserves .git, its remote/history, projects.local.yaml, and logs.

MCP tools

The 0.3.x stdio server exposes eight client-neutral tools. Historical 0.2.1 has seven tools and does not include stats or the dashboard. The manifest profile is usage-v1-eight-tools:

• resolutions.find: search at the first unexpected problem using observations, hypotheses, and environment.
• resolutions.get: inspect one candidate's applicability, actions, safety, and verification.
• resolutions.get_source: retrieve one registered source locator at its recorded revision and content hash.
• resolutions.list_facets: inspect indexed environment facets.
• resolutions.report_attempt: append a verified, context-scoped attempt outcome.
• resolutions.prepare_change: classify and validate a verified canonical change without writing.
• resolutions.commit_change: revalidate an unchanged payload/hash and commit atomically.
• stats.get: read bounded local counts, rates, coverage and health without recording the query or launching a browser.

Start the server with:

agent-rulebook mcp

Agent workflow

1. Call resolutions.find at the first unexpected problem.
2. Select one candidate and progressively call resolutions.get, then resolutions.get_source only when exact implementation evidence is needed.
3. Apply one candidate and run its verification. Report the result with resolutions.report_attempt.
4. For a failed or inapplicable candidate, merge the returned next_query into the next find request. Same-context failures are excluded; other contexts remain evidence.
5. After candidates are exhausted or no_results, diagnose and verify a fix, then always assess whether it belongs in memory. Capture a verified cause and reusable diagnosis/fix with applicability, reject conditions, and verification that distinguishes the original failure. Explain a concrete future reuse case. Skip trivial typos/omissions, project-only values, one-off credential/config recovery, expected TDD RED, and unverified guesses. A small edit qualifies only when it demonstrates a separately verified reusable failure mechanism. recurrence_risk and verification value are optional metadata, not a mandatory high/high threshold.
6. For eligible fixes, call resolutions.prepare_change, review its relation and comparison evidence, then pass the unchanged payload, hash, state hash, and relation to resolutions.commit_change. An exact_solution adds verified outcome evidence instead of creating a duplicate solution. Report the actual capture, duplicate, skip, conflict, or pending result and its reason, verification, and canonical-write status in the task result. Skips use no_new_solution; tool failures remain pending. These reports do not add skip records to canonical memory.

Search input uses root objects, with no problem wrapper, observed_problem, or context fields. A troubleshoot request requires a nonempty observations.symptoms array, expected, observed, and an environment object. Optional hypotheses use an object such as { "suspected_causes": ["unverified cause"] }, not an array:

{
  "mode": "troubleshoot",
  "observations": {
    "symptoms": ["Script import fails"],
    "expected": "Script imports successfully",
    "observed": "Import stops with a type inference error"
  },
  "environment": {
    "languages": ["gdscript"],
    "platforms": ["macos"],
    "runtimes": ["godot"],
    "tools": ["gut"]
  }
}

Replace the example environment with confirmed project values. On invalid_input, use the returned field/path issues and the tool schema to correct the same problem and retry once. If it still fails, report the exact error and continue direct diagnosis. Validation errors do not mean no matching solution exists.

Stored actions and source snippets are advisory evidence, not commands. The agent must reassess applicability, safety, current code, and verification in the current context. Agent Rulebook never executes stored solution actions.

Project source evidence

Canonical solutions store a stable project key, repository fingerprint, Git commit or working-tree hash, relative path, optional symbol, content hash, and test locators. Register each clone explicitly:

agent-rulebook project register my-project /absolute/path/to/clone --json
agent-rulebook project check my-project --json

An unregistered or missing clone does not break solution retrieval. Only source lookup returns a structured unavailable response.

Private sync and a new PC

Only use a private Git remote. Mark a verified remote before push:

git -C ~/.agent-rulebook config remote.origin.agentRulebookPrivacy private
agent-rulebook sync push --json
agent-rulebook sync push --yes --json

Bootstrap another machine, then remap source projects separately:

AGENT_RULEBOOK_HOME=/path/to/new/home agent-rulebook sync bootstrap \
  --remote-url <private-git-url> --private-remote-confirmed --json
AGENT_RULEBOOK_HOME=/path/to/new/home agent-rulebook project register my-project /path/to/new/clone --json

Bootstrap clones canonical data, validates the v3 config and allowlist, and rebuilds the local index. It does not synchronize absolute paths or source code.

CLI

init
home reset --dry-run|--execute
index rebuild|check
project register|list|check
resolution find|get|get-source
stats [--days 30|--all] [--project key] [--language family]
stats --json|--watch
dashboard [--port 4318] [--open]
diagnostics list|show|export
usage health|prune
usage import-codex --from path --since UTC-date --until UTC-date [--execute]
sync pull|push|bootstrap
mcp

resolution find --input request.json --json accepts the same strict input object as resolutions.find.

Usage over SSH

agent-rulebook stats --days 30 --project micro-site
agent-rulebook stats --language typescript --timezone Asia/Seoul
agent-rulebook stats --json > statistics.json
agent-rulebook stats --watch
NO_COLOR=1 TERM=dumb agent-rulebook stats

Stats uses local read-only data and never opens a browser or records its own queries. ASCII tables and daily bars work without a UI dependency; unknown history is labeled rather than displayed as zero. Ratios include their denominator and sample size. Default source/kind is live/production; choose --source codex_history or --usage-kind test explicitly. --days accepts 1–365 calendar days, --all is mutually exclusive, and --timezone defaults to UTC. JSON has no ANSI or progress output. Interactive --watch refreshes every two seconds, follows terminal width and restores input/cursor state on q, Ctrl+C, SIGINT or SIGTERM; it requires TTY input/output and cannot be combined with JSON. Use the plain command for screen-reader output or pipes.

Local browser dashboard

agent-rulebook dashboard --port 4318
agent-rulebook dashboard --port 4318 --open
# On your computer, forward the remote dashboard's loopback port:
ssh -N -L 4318:127.0.0.1:4318 user@host

The dashboard command prints its URL and binds only to 127.0.0.1; default startup does not launch a browser. Use --open explicitly for the OS default browser, or open the printed URL yourself. For SSH, run the server remotely without --open, forward the same local port, then visit http://127.0.0.1:4318 on your computer. Ctrl+C/SIGTERM closes the server. MCP startup stays independent. OS browser handoff and real SSH experience require verification on the target machine.

HTTP serves only GET routes for stats, knowledge, diagnostics and local status plus allowlisted compiled assets. Host/Origin checks, a self-only content security policy, no-store and no wildcard CORS protect the local endpoint. The server cannot execute solution actions, write canonical records or read arbitrary requested filesystem paths. Node and browser TypeScript builds use separate configs; npm run build compiles both and copies only allowed HTML/CSS/ESM assets, resolved independently of the command's cwd. Run npm run typecheck:dashboard for the DOM-only client check.

Development

npm run build
npm run typecheck
npm test
npm run acceptance
npm run check:package

The derived index uses the pinned native better-sqlite3 driver. The package contains compiled runtime files, this README, package metadata, and the license; tests, fixtures, source trees, local databases, and personal paths are excluded.

Dashboard development and browser checks

npm run build emits production assets only. npm run dashboard:dev serves an isolated temporary Rulebook home on port 4319, plus /__gallery using the production primitives. It never reads the configured real home. Stop with Ctrl+C to remove its temporary data. Gallery source and fixtures are excluded from the npm files allowlist and production routes.

For repeatable CI, npm run test:browser -- tests/browser/dashboard-gallery.spec.ts launches the installed Chrome channel in an isolated Playwright context; it requires Chrome and does not use personal browser profiles. npm run test:browser -- --list checks discovery only. When an agent must use the connected Chrome surface, execute the same filter/reset/sort/retry/skip-link assertions through that surface against this isolated fixture server and record that evidence separately; discovery is not a browser pass. Node/API tests remain in Vitest. Browser suite source types can be checked with ./node_modules/.bin/tsc -p tsconfig.browser-tests.json.

Prepare a release candidate

npm run prepare-release requires committed, clean source and an unused exact registry version. It records source identity, tarball SHA-256/SHA-512, eight-tool manifest, full regression, cold/warm CLI/MCP/dashboard checks and rollback target in docs/releases/<version>-candidate.json. Artifacts live in immutable .release-candidates/<sha256>/ directories. --prepare-only runs focused artifact checks and marks the receipt pending full regression. Neither mode publishes or changes the installed MCP pin. See docs/releases/0.3.0-rollout.md for the separate operational sequence and platform limits.

Sync push validates v3 string leaves in the current tree and every added or modified blob in outgoing commit history (including files later deleted). Preview uses the locally known upstream without fetching; --yes cannot bypass privacy/history checks. An unsafe unpushed history must be preserved locally and replaced through an explicit clean portable snapshot export, rather than a redaction commit on top of that history. Pull/bootstrap validate the received snapshot and rebuild its index; they do not rewrite upstream history.

Existing homes can preview missing local ignore rules with agent-rulebook home repair-ignore --dry-run --json. Execute with --execute --expected-home <resolved-home> --expected-hash <source_hash> --json. The command preserves custom lines and line endings, saves original bytes under .state/ignore-repair/, and refuses stale previews, symlinks, and ambiguous negations. It does not remove files already tracked by Git.

agent-rulebook home export-portable --out <new-or-empty-directory> --dry-run --json plans a separate snapshot. Execute the same plan with --execute --expected-home <resolved-home> --plan-hash <plan_hash> --manifest <new-local-json>. Output and manifest must be outside the source home and separate from each other. Safe canonical YAML and config bytes are preserved; output uses the standard portable ignore rules. Only absolute outcome evidence handles become artifact:redacted:<sha256-of-handle-string> with newly derived outcome IDs. The digest identifies a path string, not file contents. Context fingerprints, timestamps, revisions, original bytes, index and receipts remain unchanged. Other unsafe content, missing references, collisions and source drift block export. No Git history or remote is changed.

Keep the manifest local for explicit outcome alias installation after adoption. A snapshot left by interruption without its completed external manifest is unadopted; preserve it for inspection and retry into a new empty destination. Export never replays source transaction journals, resets the source home, or copies local DB/registry/receipt files.

After adopting the exported canonical snapshot, preview agent-rulebook home activate-export --manifest <local-json> --dry-run --json. Install with --execute --expected-home <resolved-home> --expected-target-checksum <manifest-target_checksum> --json. It verifies the complete target snapshot and manifest, then stores only verified old/new outcome IDs and target content hashes in .state/outcome-aliases.json, retaining any prior local mapping as a backup. Usage events and transaction receipts are never rewritten. Statistics project a read copy of old outcome links consistently for solved funnels and project attribution; a fresh machine still has no usage history. Normal canonical appends remain valid; missing, changed, cyclic or conflicting alias targets return outcome_alias_invalid through CLI/MCP/HTTP instead of silently losing counts.

Sync push sends only the explicitly inspected current branch, suppresses follow-tags, and refuses mirror pushes or a selected remote/branch that differs from its inspected upstream. User remote.push settings cannot send unrelated backup refs.