chimera-memory 0.26.2

Local-first reliability ledger for AI coding-agent work

chimera-memory

Local-first reliability ledger for AI coding-agent work.

Records what an agent tried, which command verified it, what happened, and what receipt proves it. Everything stays on your machine — no cloud, no sync, no account required.

Install

pip install chimera-memory

Requires Python 3.12+. Installs chimera-memory-types, pydantic, and filelock automatically.

macOS note: System python3 may be 3.9. Use python3.12 or uv explicitly:

# With a system Python 3.12:
python3.12 -m venv .venv && source .venv/bin/activate
pip install chimera-memory

# Or with uv:
uv venv --python 3.12 .venv && source .venv/bin/activate
pip install chimera-memory

Try it in 60 seconds

chimera-memory demo

This runs a safe local demo in a temp directory — no project mutation, no network. It shows the full flow: init → wrap → verify → receipt bundle → inspect.

Project check suites

Define your verification commands once, run them repeatedly:

chimera-memory init
chimera-memory checks init --preset python
chimera-memory checks run --bundle --output-dir ./run-output

This creates report.md, report.json, and a receipt/ bundle. Inspect the result:

chimera-memory bundle inspect ./run-output/receipt

Compare two runs:

chimera-memory bundle diff ./old-run/receipt ./new-run/receipt

Claude Code hooks (automatic evidence)

Install Chimera hooks for automatic claim-locked evidence in Claude Code sessions:

chimera-memory hooks install

Then create .chimera/hooks.toml in your project root:

[claude_hooks]
auto_lock = true
scope_path = "."          # use "." to start; narrow only when confident

falsifiers = [
  ["python3", "-m", "pytest", "tests/test_my_area.py", "-q"]
]

must_not_break = [
  ["python3", "-m", "pytest", "-q"]
]

When you submit a prompt in Claude Code, the UserPromptSubmit hook derives the intent and auto-locks a claim. When Claude finishes a turn, the Stop hook settles the claim and generates PR_EVIDENCE.md. See docs/examples/claude-hooks-setup.md.

scope_path tip: Start with scope_path = "." so that co-changed tests, docs, and config files are included in scope. Use a narrower path only when your task is strictly limited to one package or directory.

SCOPE_DRIFT: If settlement reports SCOPE_DRIFT, it means your checks passed but some changed files were outside the declared scope_path. This is honest review signal, not a test failure. Common first-run cause: .gitignore or .chimera/hooks.toml changed alongside your code.

Local MCP tools for coding agents

chimera-memory mcp serve starts a local stdio MCP server. MCP-capable agents (Claude, Codex, Cursor, etc.) can call Chimera's claim and X-Ray tools directly:

{
  "mcpServers": {
    "chimera-memory": {
      "command": "chimera-memory",
      "args": ["mcp", "serve", "--allow-write"]
    }
  }
}

Tools: chimera_claim_validate, chimera_claim_lock_auto, chimera_claim_show, chimera_claim_list, chimera_claim_settle (requires --allow-execute), chimera_xray_generate.

See docs/examples/mcp-local-tools.md.

AI PR Evidence / Merge X-Ray

Agent-seam auto-lock (v0.23)

Agents and hooks can create sealed claims without writing a claim.toml file:

CHIMERA_INTENT="fix checkout null dereference" \
CHIMERA_SCOPE_PATH="packages/cart" \
CHIMERA_FALSIFIERS_JSON='[["uv","run","pytest","tests/test_checkout.py::test_empty_cart"]]' \
CHIMERA_MUST_NOT_BREAK_JSON='[["uv","run","pytest","tests/test_cart.py"]]' \
chimera-memory claim lock --auto --json

This is the stable primitive that future MCP/hooks integrations will call. Preview without locking: chimera-memory claim lock --auto --dry-run --json. See docs/examples/agent-seam-auto-lock.md.

Chimera can now produce local PR evidence reports for AI-assisted coding work.

A claim can be locked before edits with an intent, scope, falsifier, and must-not-break checks. After the work, Chimera settles that claim against the pre-committed checks and generates a Merge X-Ray showing which changed files have settled evidence and which remain evidence-dark.

# 1. Lock a claim BEFORE editing (sealed, scope-bound)
chimera-memory claim lock --from-file claim.toml

# 2. Do the work, then settle against the pre-committed checks only
chimera-memory claim settle <claim_id>

# 3. Generate the PR evidence report
#    If your changes are committed on a branch:
chimera-memory xray generate --base main --head HEAD --output PR_EVIDENCE.md

#    If your changes are still uncommitted (working-tree mode):
chimera-memory xray generate --output PR_EVIDENCE.md

Committed vs uncommitted: --base/--head uses git diff between two refs and excludes untracked files — recommended for PR review. Without --base, Chimera reads the current working tree including unstaged changes.

Example claim.toml:

intent = "fix checkout null dereference"
scope_path = "packages/cart"
predicted_outcome = "all pass"

[[falsifiers]]
command = ["pytest", "tests/test_checkout.py::test_empty_cart"]

[[must_not_break]]
command = ["pytest", "tests/test_cart.py"]

The Merge X-Ray (PR_EVIDENCE.md) shows the verdict, settled claims, evidence-dark changes, scope drift, and a reviewer-focus list. It reports settled evidence, not proof of correctness — coverage is path-based ("covered by declared claim scope"), never a guarantee that code is tested or correct. See docs/examples/claim-locked-coding.md and docs/examples/pr-evidence-example.md.

Quickstart (5 commands)

# 1. Initialise the local ledger (also adds .chimera-memory/ to .gitignore)
chimera-memory init

# 2. Start a session
chimera-memory session start \
  --branch feat/my-branch \
  --task-label "fix type errors" \
  --agent kiro \
  --model claude-sonnet-4.6 \
  --harness-id kiro-cli

# 3. Wrap a verification command (test, lint, typecheck, …)
chimera-memory wrap \
  --failure-origin organic_real \
  --scope-path . \
  --verification-scope package \
  -- pytest tests/ -q

# 4. End the session
chimera-memory session end --status PASSED

# 5. View the receipt
chimera-memory receipt latest

Onboard an agent in 90 seconds

Get the full session/wrap/repair-loop protocol for your agent:

chimera-memory agent-guide --agent generic   # or: kiro, codex

Generate a copy-paste session scaffold for your package:

chimera-memory template dogfood --scope-path packages/chimera-memory

Prompt templates for sustained use are in docs/prompts/ in the source repo:

• kiro-dogfood.md — Kiro agent session discipline
• generic-agent-dogfood.md — Any agent
• release-closeout.md — Release closeout checklist

Health check

chimera-memory doctor
chimera-memory doctor --json

doctor is read-only. It checks:

• Is .chimera-memory/ initialized?
• Is .chimera-memory/ in .gitignore?
• Is there an active session?
• Claim count and integrity status
• M2B readiness level

Exit code: 0 = healthy, 1 = warnings (e.g. no active session), 2 = critical (e.g. not initialized).

Is my ledger healthy?

doctor also audits whether the ledger is being used correctly:

chimera-memory doctor        # shows Evidence Hygiene section
chimera-memory doctor --json # machine-readable, includes evidence_hygiene + next_actions

Evidence hygiene checks:

• Scoped claim ratio (claims with --scope-path set)
• Unknown failure_origin count (claims missing classification)
• Repair-loop completeness (loops with same_scope_after_fix)
• Orphaned repair phases (--repair-phase without --repair-loop-id)
• Test/synthetic and invocation-artifact claim counts

If issues are found, doctor prints actionable next steps.

Preflight Intelligence (v0.6)

Before starting work, surface historical failures, repair-loop lessons, and hygiene warnings:

chimera-memory preflight --from-git
chimera-memory preflight --scope-path packages/chimera-memory

Shows:

• Historical failures in the relevant scope (organic_real + controlled_real)
• Repair-loop lessons (what failed, was it fixed?)
• Hygiene warnings (invocation_artifact issues — not product defects)
• Recommended verification commands

Not M2B scoring or model ranking. Advisory only.

CI receipt bundle

Produce a full CI-ready artifact bundle (receipt, failures, reliability, preflight, GitHub summary):

chimera-memory receipt bundle \
  --output-dir ./ci-bundle \
  --include-preflight \
  --from-git

Upload ci-bundle/ as a CI artifact to preserve receipts across runs.

Evidence dry-run

Export claims as a portable evidence bundle and inspect what a merge would do:

chimera-memory evidence bundle --output-dir ./evidence
chimera-memory evidence import ./evidence --dry-run --json

Write-import is not available. Dry-run only.

M2B readiness

chimera-memory m2b-readiness

Shows whether the local ledger has accumulated sufficient repair-loop evidence to consider M2B (model-to-baseline) comparison. This is a local readiness gate, not a scoring system.

Run chimera-memory m2b-readiness --explain to see what evidence is missing before scoring can be trusted.

What is not built

Capability	Status
M2B drift scoring	Not built
Model ranking / routing	Not built
Hosted / cloud sync	Not built
Remote team ledger	Not built
Evidence write-import	Not built (dry-run only)
Dashboard or UI	Not built

Platform support

Platform	Status
macOS	✅ Tested
Linux	✅ Tested (CI and Docker)
Windows	⚠️ Not officially tested in 0.1.x

No intentional Windows lockout is known. If you encounter a Windows-specific issue, please open an issue.

Troubleshooting

preflight --from-git shows source: none

This is expected when the working tree is clean (no modified files). Use --scope-path <dir> to specify a target directory explicitly:

chimera-memory preflight --scope-path src/

receipt latest shows "No closed sessions"

You need to complete a session first:

chimera-memory session start --branch <branch> --task-label <label> --agent <agent> --model <model> --harness-id <id>
# ... run chimera-memory wrap commands ...
chimera-memory session end --status PASSED

m2b-readiness shows BLOCKED

The ledger needs at least 5 genuine organic_real failures followed by fixes to clear the gate. Run real verification cycles — do not manufacture failures.

verify shows LEGACY_UNSIGNED

Claims recorded before the integrity chain was introduced show as LEGACY_UNSIGNED. This is informational. Zero Broken records is the signal that matters.

Security note

chimera-memory wrap records the command string and bounded stdout/stderr. Built-in redaction removes tokens matching common secret patterns. However:

• Do not pass secrets, passwords, or API keys as literal command arguments.
• The .chimera-memory/ directory contains your local ledger. Do not commit it to version control.

Add to .gitignore (done automatically by chimera-memory init):

.chimera-memory/

Test fixture isolation

When writing tests that call chimera-memory wrap as a fixture, set CHIMERA_DQ_NO_WRITE=1 to prevent test runs from writing to the real local ledger:

CHIMERA_DQ_NO_WRITE=1 chimera-memory wrap --failure-origin organic_real -- pytest tests/

The wrapped command runs normally and the exit code is preserved. No claims are written. A notice is printed.

Do not set CHIMERA_DQ_NO_WRITE=1 for real dogfood verification sessions. It is for test fixtures only.

License

MIT — see LICENSE