Metadata-Version: 2.4
Name: chimera-memory
Version: 0.26.1
Summary: Local-first reliability ledger for AI coding-agent work
Project-URL: Homepage, https://github.com/maclit64-lang/chimera-memory
Project-URL: Source, https://github.com/maclit64-lang/chimera-memory
Project-URL: Issues, https://github.com/maclit64-lang/chimera-memory/issues
Author-email: ORIAS <hello@orias.dev>
License: MIT License
        
        Copyright (c) 2026 Chimera / ORIAS
        
        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.
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: chimera-memory-types<1.0,>=0.26.1
Requires-Dist: filelock>=3.0
Description-Content-Type: text/markdown

# 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

```bash
pip install chimera-memory
```

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

## Try it in 60 seconds

```bash
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:

```bash
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:

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

Compare two runs:

```bash
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:

```bash
chimera-memory hooks install
```

Then before starting a task in Claude Code:

```bash
export CHIMERA_INTENT="fix checkout null dereference"
export CHIMERA_SCOPE_PATH="packages/cart"
export CHIMERA_FALSIFIERS_JSON='[["uv","run","pytest","packages/cart/tests/"]]'
chimera-memory claim lock --auto --json
```

When Claude finishes a turn, the Stop hook automatically settles the claim
and generates `PR_EVIDENCE.md`. See
[docs/examples/claude-hooks-setup.md](../../docs/examples/claude-hooks-setup.md).

## 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:

```json
{
  "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](../../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:

```bash
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](../../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.

```bash
# 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
chimera-memory xray generate --output PR_EVIDENCE.md
```

Example `claim.toml`:

```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](../../docs/examples/claim-locked-coding.md)
and [docs/examples/pr-evidence-example.md](../../docs/examples/pr-evidence-example.md).

## Quickstart (5 commands)

```bash
# 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:

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

Generate a copy-paste session scaffold for your package:

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

Prompt templates for sustained use are in `docs/prompts/` in the [source repo](https://github.com/maclit64-lang/chimera-memory):

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

## Health check

```bash
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:

```bash
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:

```bash
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):

```bash
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:

```bash
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

```bash
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:

```bash
chimera-memory preflight --scope-path src/
```

**`receipt latest` shows "No closed sessions"**

You need to complete a session first:

```bash
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:

```bash
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](LICENSE)
