chimera-memory 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (74) hide show
  1. chimera_memory-0.1.0/.gitignore +49 -0
  2. chimera_memory-0.1.0/LICENSE +21 -0
  3. chimera_memory-0.1.0/PKG-INFO +303 -0
  4. chimera_memory-0.1.0/README.md +263 -0
  5. chimera_memory-0.1.0/pyproject.toml +35 -0
  6. chimera_memory-0.1.0/reports/m1-4-dogfood-reliability-report.json +121 -0
  7. chimera_memory-0.1.0/reports/m1-4-dogfood-reliability-report.md +115 -0
  8. chimera_memory-0.1.0/src/chimera_memory/__init__.py +55 -0
  9. chimera_memory-0.1.0/src/chimera_memory/_index.py +204 -0
  10. chimera_memory-0.1.0/src/chimera_memory/adapters/__init__.py +1 -0
  11. chimera_memory-0.1.0/src/chimera_memory/adapters/git.py +87 -0
  12. chimera_memory-0.1.0/src/chimera_memory/adapters/manual.py +1 -0
  13. chimera_memory-0.1.0/src/chimera_memory/adapters/pytest_ci.py +87 -0
  14. chimera_memory-0.1.0/src/chimera_memory/append_state.py +159 -0
  15. chimera_memory-0.1.0/src/chimera_memory/cli.py +1402 -0
  16. chimera_memory-0.1.0/src/chimera_memory/data_quality.py +137 -0
  17. chimera_memory-0.1.0/src/chimera_memory/drift.py +101 -0
  18. chimera_memory-0.1.0/src/chimera_memory/errata.py +113 -0
  19. chimera_memory-0.1.0/src/chimera_memory/evidence.py +502 -0
  20. chimera_memory-0.1.0/src/chimera_memory/export.py +207 -0
  21. chimera_memory-0.1.0/src/chimera_memory/integrity.py +333 -0
  22. chimera_memory-0.1.0/src/chimera_memory/ledger.py +441 -0
  23. chimera_memory-0.1.0/src/chimera_memory/m2b_readiness.py +449 -0
  24. chimera_memory-0.1.0/src/chimera_memory/preflight.py +492 -0
  25. chimera_memory-0.1.0/src/chimera_memory/query.py +183 -0
  26. chimera_memory-0.1.0/src/chimera_memory/receipt.py +392 -0
  27. chimera_memory-0.1.0/src/chimera_memory/redaction.py +63 -0
  28. chimera_memory-0.1.0/src/chimera_memory/reliability.py +302 -0
  29. chimera_memory-0.1.0/src/chimera_memory/scoring.py +69 -0
  30. chimera_memory-0.1.0/src/chimera_memory/seal.py +32 -0
  31. chimera_memory-0.1.0/src/chimera_memory/session.py +123 -0
  32. chimera_memory-0.1.0/src/chimera_memory/session_lifecycle.py +293 -0
  33. chimera_memory-0.1.0/src/chimera_memory/storage.py +266 -0
  34. chimera_memory-0.1.0/tests/fixtures/export/contradicted_event_v1.json +62 -0
  35. chimera_memory-0.1.0/tests/fixtures/export/validated_event_v1.json +62 -0
  36. chimera_memory-0.1.0/tests/test_ci_bundle.py +257 -0
  37. chimera_memory-0.1.0/tests/test_ci_receipts.py +172 -0
  38. chimera_memory-0.1.0/tests/test_cli_help.py +68 -0
  39. chimera_memory-0.1.0/tests/test_cli_pytest_wrap.py +191 -0
  40. chimera_memory-0.1.0/tests/test_data_quality.py +192 -0
  41. chimera_memory-0.1.0/tests/test_dogfood_status.py +310 -0
  42. chimera_memory-0.1.0/tests/test_drift_report_cli.py +211 -0
  43. chimera_memory-0.1.0/tests/test_errata.py +273 -0
  44. chimera_memory-0.1.0/tests/test_errata_store_path.py +157 -0
  45. chimera_memory-0.1.0/tests/test_evidence_bundle.py +474 -0
  46. chimera_memory-0.1.0/tests/test_export.py +317 -0
  47. chimera_memory-0.1.0/tests/test_export_contract.py +164 -0
  48. chimera_memory-0.1.0/tests/test_failures_cli.py +274 -0
  49. chimera_memory-0.1.0/tests/test_first_run_ux.py +101 -0
  50. chimera_memory-0.1.0/tests/test_git_adapter.py +126 -0
  51. chimera_memory-0.1.0/tests/test_golden_fixtures.py +164 -0
  52. chimera_memory-0.1.0/tests/test_integrity.py +284 -0
  53. chimera_memory-0.1.0/tests/test_m2b_readiness.py +301 -0
  54. chimera_memory-0.1.0/tests/test_package_skeleton.py +110 -0
  55. chimera_memory-0.1.0/tests/test_preflight.py +358 -0
  56. chimera_memory-0.1.0/tests/test_preflight_git_parsing.py +158 -0
  57. chimera_memory-0.1.0/tests/test_query.py +183 -0
  58. chimera_memory-0.1.0/tests/test_receipt.py +560 -0
  59. chimera_memory-0.1.0/tests/test_record_claim.py +102 -0
  60. chimera_memory-0.1.0/tests/test_redaction.py +214 -0
  61. chimera_memory-0.1.0/tests/test_reliability.py +216 -0
  62. chimera_memory-0.1.0/tests/test_reliability_cli.py +86 -0
  63. chimera_memory-0.1.0/tests/test_reliability_dq_readmodels.py +225 -0
  64. chimera_memory-0.1.0/tests/test_session_cli.py +271 -0
  65. chimera_memory-0.1.0/tests/test_session_lifecycle.py +379 -0
  66. chimera_memory-0.1.0/tests/test_session_model.py +125 -0
  67. chimera_memory-0.1.0/tests/test_session_storage.py +133 -0
  68. chimera_memory-0.1.0/tests/test_settlement_scoring.py +152 -0
  69. chimera_memory-0.1.0/tests/test_storage_performance.py +195 -0
  70. chimera_memory-0.1.0/tests/test_storage_query_report.py +260 -0
  71. chimera_memory-0.1.0/tests/test_storage_state_hardening.py +247 -0
  72. chimera_memory-0.1.0/tests/test_verify_cli.py +81 -0
  73. chimera_memory-0.1.0/tests/test_wrap_generic_command.py +275 -0
  74. chimera_memory-0.1.0/tests/test_wrap_session_link.py +268 -0
@@ -0,0 +1,49 @@
1
+ .DS_Store
2
+ .env
3
+ .env.*
4
+ .venv/
5
+ .venv.*/
6
+ .vscode/
7
+ coverage/
8
+ dist/
9
+ build/
10
+ node_modules/
11
+ .next/
12
+ __pycache__/
13
+ .mypy_cache/
14
+ .pytest_cache/
15
+ .ruff_cache/
16
+ .uv-cache/
17
+ .playwright-cli/
18
+ .local/
19
+ output/
20
+ htmlcov/
21
+ .coverage
22
+ *.tsbuildinfo
23
+ *.pyc
24
+ *.pyo
25
+ *.exitcode
26
+ artifacts/
27
+ docs/generated/
28
+ docs/readiness/generated/
29
+ infra/db/backups/
30
+ *.dump
31
+
32
+ # Research/output corpora — must never be tracked in the product repo
33
+ ovc1/
34
+
35
+ # Understand-Anything generated scratch. Keep config/ignore policy trackable;
36
+ # decide separately whether to commit knowledge-graph.json after review.
37
+ .understand-anything/intermediate/
38
+ .understand-anything/tmp/
39
+ .understand-anything/diff-overlay.json
40
+
41
+ # Local Pi/Codex/Lens/GSD/code-navigation scratch surfaces generated by harness runs.
42
+ .codex/
43
+ .pi-lens/
44
+ .pi/gsd/
45
+ .pi/tmp/
46
+ .cache/cymbal/
47
+
48
+ # Chimera Memory local dogfood store
49
+ .chimera-memory/
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Chimera / ORIAS
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,303 @@
1
+ Metadata-Version: 2.4
2
+ Name: chimera-memory
3
+ Version: 0.1.0
4
+ Summary: Local-first reliability ledger for AI coding-agent work
5
+ License: MIT License
6
+
7
+ Copyright (c) 2026 Chimera / ORIAS
8
+
9
+ Permission is hereby granted, free of charge, to any person obtaining a copy
10
+ of this software and associated documentation files (the "Software"), to deal
11
+ in the Software without restriction, including without limitation the rights
12
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
13
+ copies of the Software, and to permit persons to whom the Software is
14
+ furnished to do so, subject to the following conditions:
15
+
16
+ The above copyright notice and this permission notice shall be included in all
17
+ copies or substantial portions of the Software.
18
+
19
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
20
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
21
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
22
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
23
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
24
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
25
+ SOFTWARE.
26
+ License-File: LICENSE
27
+ Classifier: Development Status :: 3 - Alpha
28
+ Classifier: Intended Audience :: Developers
29
+ Classifier: License :: OSI Approved :: MIT License
30
+ Classifier: Operating System :: MacOS
31
+ Classifier: Operating System :: POSIX :: Linux
32
+ Classifier: Programming Language :: Python :: 3
33
+ Classifier: Programming Language :: Python :: 3.12
34
+ Classifier: Topic :: Software Development :: Quality Assurance
35
+ Classifier: Topic :: Software Development :: Testing
36
+ Requires-Python: >=3.12
37
+ Requires-Dist: chimera-memory-types
38
+ Requires-Dist: filelock>=3.0
39
+ Description-Content-Type: text/markdown
40
+
41
+ # Chimera Memory
42
+
43
+ Local-first reliability ledger for AI coding-agent work.
44
+
45
+ Chimera Memory records what an agent tried, which command checked it, what happened, and what receipt proves it. It runs entirely on your machine.
46
+
47
+ ---
48
+
49
+ ## What it records
50
+
51
+ Each wrapped verification command produces a **claim** with:
52
+
53
+ - `session_id` — which work session it belongs to
54
+ - `agent_id / model_version / harness_id` — who ran it and in what tool
55
+ - `task_type` — what kind of work (`test`, `lint`, `type`, `docs`, …)
56
+ - `VALIDATED` or `CONTRADICTED` — did reality agree with the prediction?
57
+ - `stdout_excerpt / stderr_excerpt` — bounded output witness when available
58
+ - git state at time of claim
59
+
60
+ Sessions, claims, and outcomes are stored in `.chimera-memory/` as append-only JSONL files. Each new claim gets an integrity chain entry in `.chimera-memory/integrity.jsonl`.
61
+
62
+ ---
63
+
64
+ ## Getting started
65
+
66
+ See [docs/strategy/chimera-memory-first-run-quickstart.md](../../docs/strategy/chimera-memory-first-run-quickstart.md) for a step-by-step guide.
67
+
68
+ **Key limitations (v0.6):**
69
+ - M2B drift scoring: not built
70
+ - Model ranking or routing: not built
71
+ - Hosted/cloud sync: not built
72
+ - Evidence write import: dry-run only
73
+ - Windows: not tested
74
+
75
+
76
+
77
+ Run from the repo root:
78
+
79
+ ```bash
80
+ uv run chimera-memory --help
81
+ ```
82
+
83
+ ### Standalone local install (v0.6+)
84
+
85
+ As of v0.6, local wheel builds work outside the monorepo. Build and install:
86
+
87
+ ```bash
88
+ # From the repo root, build local wheels for the two public packages
89
+ uv build packages/chimera-memory-types --out-dir /tmp/cm-dist
90
+ uv build packages/chimera-memory --out-dir /tmp/cm-dist
91
+
92
+ # In any Python 3.12+ environment
93
+ pip install /tmp/cm-dist/*.whl
94
+ chimera-memory --help
95
+ ```
96
+
97
+ Runtime dependencies installed automatically: `pydantic`, `filelock`.
98
+
99
+ **Note:** Public PyPI publishing has not happened yet. This is local packaging readiness only.
100
+ Hosted/cloud sync, team SaaS, and remote substrate writes are not implemented.
101
+ Reliability is not model routing. M2B is not implemented.
102
+
103
+ ---
104
+
105
+ ## Quickstart
106
+
107
+ ```bash
108
+ # 1. Start a session
109
+ uv run chimera-memory session start \
110
+ --branch feat/my-branch \
111
+ --task-label "fix-type-errors" \
112
+ --agent kiro \
113
+ --model claude-sonnet-4.6 \
114
+ --harness-id kiro-cli
115
+
116
+ # 2. Wrap real verification commands
117
+ uv run chimera-memory wrap --task-type type -- \
118
+ uv run mypy packages/chimera-memory/src --ignore-missing-imports
119
+ uv run chimera-memory wrap --task-type test -- \
120
+ uv run pytest packages/chimera-memory/tests -q
121
+ uv run chimera-memory wrap --task-type lint -- \
122
+ uv run ruff check packages/chimera-memory
123
+
124
+ uv run chimera-memory session end --status PASSED
125
+
126
+ # 3. Review
127
+ uv run chimera-memory failures # see what failed, with witness output
128
+ uv run chimera-memory status # dogfood gate progress
129
+ uv run chimera-memory receipt latest --markdown # share-ready proof artifact
130
+ ```
131
+
132
+ The `--` separator is required before non-pytest commands to tell the argument parser where the wrapped command begins.
133
+
134
+ ---
135
+
136
+ ## Common commands
137
+
138
+ ```bash
139
+ chimera-memory session start --branch ... --task-label ... --agent ... --model ... --harness-id ...
140
+ chimera-memory wrap --task-type <type> [-- <command>]
141
+ chimera-memory session end --status PASSED|FAILED|MIXED|INTERRUPTED
142
+ chimera-memory failures [--json]
143
+ chimera-memory status [--json]
144
+ chimera-memory verify [--json]
145
+ chimera-memory receipt latest [--json] [--markdown]
146
+ chimera-memory receipt show <session_id> [--json] [--markdown]
147
+ chimera-memory export --clean-only --output <path>
148
+ chimera-memory session list
149
+ chimera-memory report # raw reliability groups (use status for gate progress)
150
+ ```
151
+
152
+ ---
153
+
154
+ ## Demo: real failure-fix loop
155
+
156
+ During development, `mypy` found a real type error:
157
+
158
+ ```
159
+ chimera_memory/cli.py:164: error: Value of type "object" is not indexable [index]
160
+ ```
161
+
162
+ Chimera Memory recorded the mypy run as `CONTRADICTED`, with the error stored as `stdout_excerpt`. The code was fixed. The same mypy command ran again and settled as `VALIDATED`. A single session receipt showed both runs.
163
+
164
+ ```
165
+ uv run mypy ... [type] → CONTRADICTED
166
+ uv run mypy ... [type] → VALIDATED
167
+ ```
168
+
169
+ This is the core loop: reality contradicted the agent, the fix was applied, and the correction was verified — all in one session, with attribution.
170
+
171
+ ---
172
+
173
+ ## Reliability command
174
+
175
+ ```bash
176
+ chimera-memory reliability
177
+ chimera-memory reliability --json
178
+ ```
179
+
180
+ Read-only. Reports raw validation rates from settled clean claims, grouped by
181
+ agent/model/task. Does not rank models, route work, or make autonomy decisions.
182
+ Failure-quality classification (organic vs synthetic) is not yet stored in
183
+ claim metadata — rates include all CONTRADICTED outcomes.
184
+
185
+ ---
186
+
187
+ ## Bridge pipeline (dry-run only)
188
+
189
+ Export clean evidence events and preview engine ingestion without any writes:
190
+
191
+ ```bash
192
+ # Export settled, attributed claims as JSONL
193
+ uv run chimera-memory export --clean-only --output /tmp/cm-clean-events.jsonl
194
+
195
+ # Validate the export schema
196
+ uv run python -m tools.chimera_memory_ingest_dry_run /tmp/cm-clean-events.jsonl
197
+
198
+ # Map to engine evidence candidates (no database/substrate writes)
199
+ uv run python -m tools.chimera_memory_engine_adapter_dry_run /tmp/cm-clean-events.jsonl
200
+ ```
201
+
202
+ Both bridge tools are dry-run only. `writes_performed` is always `false`.
203
+
204
+ ---
205
+
206
+ ## Two-model evidence (local v0.2)
207
+
208
+ As of v0.2, the store contains evidence from two real AI coding agents:
209
+
210
+ | Agent | Model | Claims | Real failures |
211
+ |---|---|---|---|
212
+ | kiro | claude-sonnet-4.6 | 123 | 2 organic |
213
+ | codebuff | mimo-v2.5-pro | 12 | 2 real |
214
+
215
+ `manual` and `planning-agent` entries also exist for workflow/planning tasks.
216
+
217
+ M2 comparative reliability scoring is not yet built. The data is structurally
218
+ ready for it once codebuff accumulates ≥25 claims with ≥5 organic failures.
219
+
220
+ ---
221
+
222
+ ## Integrity
223
+
224
+ New claims are hash-chained into `.chimera-memory/integrity.jsonl`. Run:
225
+
226
+ ```bash
227
+ uv run chimera-memory verify
228
+ uv run chimera-memory verify --json
229
+ ```
230
+
231
+ Historical records created before the integrity layer was added are reported
232
+ as `LEGACY_UNSIGNED`. This is honest — they are not broken, just unchained.
233
+ `verify` reports `BROKEN` only if a chained record's hash doesn't match or a
234
+ claim was appended without a corresponding integrity entry.
235
+
236
+ **Single-process assumption:** the store is designed for single-process local
237
+ use. Truly concurrent writes from separate processes can race; this is not
238
+ hardened against. Local CLI use is always single-process.
239
+
240
+ ---
241
+
242
+ ## Known invocation gotcha
243
+
244
+ The `mypy` task type wrap must be invoked with only the adapter tool (not the
245
+ importer) to avoid a "source file found twice" error:
246
+
247
+ ```bash
248
+ # Correct — adapter transitively pulls in importer
249
+ uv run chimera-memory wrap --task-type type -- \
250
+ uv run mypy packages/chimera-memory/src \
251
+ tools/chimera_memory_engine_adapter_dry_run.py \
252
+ --ignore-missing-imports
253
+
254
+ # Incorrect — causes "source file found twice" mypy error
255
+ uv run chimera-memory wrap --task-type type -- \
256
+ uv run mypy packages/chimera-memory/src \
257
+ tools/chimera_memory_ingest_dry_run.py \
258
+ tools/chimera_memory_engine_adapter_dry_run.py \
259
+ --ignore-missing-imports
260
+ ```
261
+
262
+ ---
263
+
264
+ ## Release status
265
+
266
+ - **Local wheel proof exists.** The 2-package install (`chimera-memory` + `chimera-memory-types`) works in a fresh venv outside the monorepo.
267
+ - **Public PyPI: not published.** TestPyPI and private registry publishing have not been done.
268
+ - **License decision pending.** No open-source license has been formally assigned yet.
269
+ - **Witness output is redacted by default.** `chimera-memory wrap` redacts secrets (API keys, tokens, passwords, private keys) from captured stdout/stderr before storing. Review receipts before sharing.
270
+ - **Command argument redaction.** The command string in receipts is also redacted for common secret patterns. However, do not pass literal secret values as command arguments — use environment variables instead (e.g. `MY_TOKEN=secret uv run mypy ...`).
271
+
272
+ ## Platform support
273
+
274
+ - **macOS and Linux** are the target platforms. Tested on macOS arm64.
275
+ - **Windows is not supported.** Write-path locking uses `filelock` (cross-platform), but Windows has not been tested end-to-end.
276
+ - **Linux Docker smoke test** is pending (Docker unavailable in current environment).
277
+
278
+ ## What is not built
279
+
280
+ The following are explicitly out of scope for v0.6:
281
+
282
+ - M2B statistical drift/trend analysis (advisory heuristic only)
283
+ - Routing, autonomy decisions, or model ranking
284
+ - Cloud/hosted sync or team sharing
285
+ - Dashboard, GitHub Action, or CI PR comments
286
+ - ORIAS, trading/finance verticals
287
+ - GraphSource/substrate writes
288
+
289
+ ## Current limitations
290
+
291
+ - **M2 drift/model comparison is not fully built.** An advisory drift heuristic exists (`chimera-memory drift`), but statistical M2B drift/trend analysis is not built. `status` shows segment counts, not trends.
292
+ - **Useful reliability patterns require real failure variance.** A store of only `VALIDATED` claims proves capture works, not that any agent is reliable.
293
+ - **The workflow is CLI/manual, not always-on.** You must start sessions and wrap commands explicitly.
294
+ - **Local-first.** Nothing leaves your machine. Data lives in `.chimera-memory/` inside the repo.
295
+ - **Synthetic failures should not be treated as product evidence.** Only naturally occurring failures count.
296
+ - **Single-process writes only.** The integrity chain is not safe for concurrent multi-process writes.
297
+
298
+ ---
299
+
300
+ ## More detail
301
+
302
+ See the full demo quickstart with the failure-fix loop walkthrough:
303
+ [`../../docs/strategy/chimera-memory-demo-quickstart-2026-06-04.md`](../../docs/strategy/chimera-memory-demo-quickstart-2026-06-04.md)
@@ -0,0 +1,263 @@
1
+ # Chimera Memory
2
+
3
+ Local-first reliability ledger for AI coding-agent work.
4
+
5
+ Chimera Memory records what an agent tried, which command checked it, what happened, and what receipt proves it. It runs entirely on your machine.
6
+
7
+ ---
8
+
9
+ ## What it records
10
+
11
+ Each wrapped verification command produces a **claim** with:
12
+
13
+ - `session_id` — which work session it belongs to
14
+ - `agent_id / model_version / harness_id` — who ran it and in what tool
15
+ - `task_type` — what kind of work (`test`, `lint`, `type`, `docs`, …)
16
+ - `VALIDATED` or `CONTRADICTED` — did reality agree with the prediction?
17
+ - `stdout_excerpt / stderr_excerpt` — bounded output witness when available
18
+ - git state at time of claim
19
+
20
+ Sessions, claims, and outcomes are stored in `.chimera-memory/` as append-only JSONL files. Each new claim gets an integrity chain entry in `.chimera-memory/integrity.jsonl`.
21
+
22
+ ---
23
+
24
+ ## Getting started
25
+
26
+ See [docs/strategy/chimera-memory-first-run-quickstart.md](../../docs/strategy/chimera-memory-first-run-quickstart.md) for a step-by-step guide.
27
+
28
+ **Key limitations (v0.6):**
29
+ - M2B drift scoring: not built
30
+ - Model ranking or routing: not built
31
+ - Hosted/cloud sync: not built
32
+ - Evidence write import: dry-run only
33
+ - Windows: not tested
34
+
35
+
36
+
37
+ Run from the repo root:
38
+
39
+ ```bash
40
+ uv run chimera-memory --help
41
+ ```
42
+
43
+ ### Standalone local install (v0.6+)
44
+
45
+ As of v0.6, local wheel builds work outside the monorepo. Build and install:
46
+
47
+ ```bash
48
+ # From the repo root, build local wheels for the two public packages
49
+ uv build packages/chimera-memory-types --out-dir /tmp/cm-dist
50
+ uv build packages/chimera-memory --out-dir /tmp/cm-dist
51
+
52
+ # In any Python 3.12+ environment
53
+ pip install /tmp/cm-dist/*.whl
54
+ chimera-memory --help
55
+ ```
56
+
57
+ Runtime dependencies installed automatically: `pydantic`, `filelock`.
58
+
59
+ **Note:** Public PyPI publishing has not happened yet. This is local packaging readiness only.
60
+ Hosted/cloud sync, team SaaS, and remote substrate writes are not implemented.
61
+ Reliability is not model routing. M2B is not implemented.
62
+
63
+ ---
64
+
65
+ ## Quickstart
66
+
67
+ ```bash
68
+ # 1. Start a session
69
+ uv run chimera-memory session start \
70
+ --branch feat/my-branch \
71
+ --task-label "fix-type-errors" \
72
+ --agent kiro \
73
+ --model claude-sonnet-4.6 \
74
+ --harness-id kiro-cli
75
+
76
+ # 2. Wrap real verification commands
77
+ uv run chimera-memory wrap --task-type type -- \
78
+ uv run mypy packages/chimera-memory/src --ignore-missing-imports
79
+ uv run chimera-memory wrap --task-type test -- \
80
+ uv run pytest packages/chimera-memory/tests -q
81
+ uv run chimera-memory wrap --task-type lint -- \
82
+ uv run ruff check packages/chimera-memory
83
+
84
+ uv run chimera-memory session end --status PASSED
85
+
86
+ # 3. Review
87
+ uv run chimera-memory failures # see what failed, with witness output
88
+ uv run chimera-memory status # dogfood gate progress
89
+ uv run chimera-memory receipt latest --markdown # share-ready proof artifact
90
+ ```
91
+
92
+ The `--` separator is required before non-pytest commands to tell the argument parser where the wrapped command begins.
93
+
94
+ ---
95
+
96
+ ## Common commands
97
+
98
+ ```bash
99
+ chimera-memory session start --branch ... --task-label ... --agent ... --model ... --harness-id ...
100
+ chimera-memory wrap --task-type <type> [-- <command>]
101
+ chimera-memory session end --status PASSED|FAILED|MIXED|INTERRUPTED
102
+ chimera-memory failures [--json]
103
+ chimera-memory status [--json]
104
+ chimera-memory verify [--json]
105
+ chimera-memory receipt latest [--json] [--markdown]
106
+ chimera-memory receipt show <session_id> [--json] [--markdown]
107
+ chimera-memory export --clean-only --output <path>
108
+ chimera-memory session list
109
+ chimera-memory report # raw reliability groups (use status for gate progress)
110
+ ```
111
+
112
+ ---
113
+
114
+ ## Demo: real failure-fix loop
115
+
116
+ During development, `mypy` found a real type error:
117
+
118
+ ```
119
+ chimera_memory/cli.py:164: error: Value of type "object" is not indexable [index]
120
+ ```
121
+
122
+ Chimera Memory recorded the mypy run as `CONTRADICTED`, with the error stored as `stdout_excerpt`. The code was fixed. The same mypy command ran again and settled as `VALIDATED`. A single session receipt showed both runs.
123
+
124
+ ```
125
+ uv run mypy ... [type] → CONTRADICTED
126
+ uv run mypy ... [type] → VALIDATED
127
+ ```
128
+
129
+ This is the core loop: reality contradicted the agent, the fix was applied, and the correction was verified — all in one session, with attribution.
130
+
131
+ ---
132
+
133
+ ## Reliability command
134
+
135
+ ```bash
136
+ chimera-memory reliability
137
+ chimera-memory reliability --json
138
+ ```
139
+
140
+ Read-only. Reports raw validation rates from settled clean claims, grouped by
141
+ agent/model/task. Does not rank models, route work, or make autonomy decisions.
142
+ Failure-quality classification (organic vs synthetic) is not yet stored in
143
+ claim metadata — rates include all CONTRADICTED outcomes.
144
+
145
+ ---
146
+
147
+ ## Bridge pipeline (dry-run only)
148
+
149
+ Export clean evidence events and preview engine ingestion without any writes:
150
+
151
+ ```bash
152
+ # Export settled, attributed claims as JSONL
153
+ uv run chimera-memory export --clean-only --output /tmp/cm-clean-events.jsonl
154
+
155
+ # Validate the export schema
156
+ uv run python -m tools.chimera_memory_ingest_dry_run /tmp/cm-clean-events.jsonl
157
+
158
+ # Map to engine evidence candidates (no database/substrate writes)
159
+ uv run python -m tools.chimera_memory_engine_adapter_dry_run /tmp/cm-clean-events.jsonl
160
+ ```
161
+
162
+ Both bridge tools are dry-run only. `writes_performed` is always `false`.
163
+
164
+ ---
165
+
166
+ ## Two-model evidence (local v0.2)
167
+
168
+ As of v0.2, the store contains evidence from two real AI coding agents:
169
+
170
+ | Agent | Model | Claims | Real failures |
171
+ |---|---|---|---|
172
+ | kiro | claude-sonnet-4.6 | 123 | 2 organic |
173
+ | codebuff | mimo-v2.5-pro | 12 | 2 real |
174
+
175
+ `manual` and `planning-agent` entries also exist for workflow/planning tasks.
176
+
177
+ M2 comparative reliability scoring is not yet built. The data is structurally
178
+ ready for it once codebuff accumulates ≥25 claims with ≥5 organic failures.
179
+
180
+ ---
181
+
182
+ ## Integrity
183
+
184
+ New claims are hash-chained into `.chimera-memory/integrity.jsonl`. Run:
185
+
186
+ ```bash
187
+ uv run chimera-memory verify
188
+ uv run chimera-memory verify --json
189
+ ```
190
+
191
+ Historical records created before the integrity layer was added are reported
192
+ as `LEGACY_UNSIGNED`. This is honest — they are not broken, just unchained.
193
+ `verify` reports `BROKEN` only if a chained record's hash doesn't match or a
194
+ claim was appended without a corresponding integrity entry.
195
+
196
+ **Single-process assumption:** the store is designed for single-process local
197
+ use. Truly concurrent writes from separate processes can race; this is not
198
+ hardened against. Local CLI use is always single-process.
199
+
200
+ ---
201
+
202
+ ## Known invocation gotcha
203
+
204
+ The `mypy` task type wrap must be invoked with only the adapter tool (not the
205
+ importer) to avoid a "source file found twice" error:
206
+
207
+ ```bash
208
+ # Correct — adapter transitively pulls in importer
209
+ uv run chimera-memory wrap --task-type type -- \
210
+ uv run mypy packages/chimera-memory/src \
211
+ tools/chimera_memory_engine_adapter_dry_run.py \
212
+ --ignore-missing-imports
213
+
214
+ # Incorrect — causes "source file found twice" mypy error
215
+ uv run chimera-memory wrap --task-type type -- \
216
+ uv run mypy packages/chimera-memory/src \
217
+ tools/chimera_memory_ingest_dry_run.py \
218
+ tools/chimera_memory_engine_adapter_dry_run.py \
219
+ --ignore-missing-imports
220
+ ```
221
+
222
+ ---
223
+
224
+ ## Release status
225
+
226
+ - **Local wheel proof exists.** The 2-package install (`chimera-memory` + `chimera-memory-types`) works in a fresh venv outside the monorepo.
227
+ - **Public PyPI: not published.** TestPyPI and private registry publishing have not been done.
228
+ - **License decision pending.** No open-source license has been formally assigned yet.
229
+ - **Witness output is redacted by default.** `chimera-memory wrap` redacts secrets (API keys, tokens, passwords, private keys) from captured stdout/stderr before storing. Review receipts before sharing.
230
+ - **Command argument redaction.** The command string in receipts is also redacted for common secret patterns. However, do not pass literal secret values as command arguments — use environment variables instead (e.g. `MY_TOKEN=secret uv run mypy ...`).
231
+
232
+ ## Platform support
233
+
234
+ - **macOS and Linux** are the target platforms. Tested on macOS arm64.
235
+ - **Windows is not supported.** Write-path locking uses `filelock` (cross-platform), but Windows has not been tested end-to-end.
236
+ - **Linux Docker smoke test** is pending (Docker unavailable in current environment).
237
+
238
+ ## What is not built
239
+
240
+ The following are explicitly out of scope for v0.6:
241
+
242
+ - M2B statistical drift/trend analysis (advisory heuristic only)
243
+ - Routing, autonomy decisions, or model ranking
244
+ - Cloud/hosted sync or team sharing
245
+ - Dashboard, GitHub Action, or CI PR comments
246
+ - ORIAS, trading/finance verticals
247
+ - GraphSource/substrate writes
248
+
249
+ ## Current limitations
250
+
251
+ - **M2 drift/model comparison is not fully built.** An advisory drift heuristic exists (`chimera-memory drift`), but statistical M2B drift/trend analysis is not built. `status` shows segment counts, not trends.
252
+ - **Useful reliability patterns require real failure variance.** A store of only `VALIDATED` claims proves capture works, not that any agent is reliable.
253
+ - **The workflow is CLI/manual, not always-on.** You must start sessions and wrap commands explicitly.
254
+ - **Local-first.** Nothing leaves your machine. Data lives in `.chimera-memory/` inside the repo.
255
+ - **Synthetic failures should not be treated as product evidence.** Only naturally occurring failures count.
256
+ - **Single-process writes only.** The integrity chain is not safe for concurrent multi-process writes.
257
+
258
+ ---
259
+
260
+ ## More detail
261
+
262
+ See the full demo quickstart with the failure-fix loop walkthrough:
263
+ [`../../docs/strategy/chimera-memory-demo-quickstart-2026-06-04.md`](../../docs/strategy/chimera-memory-demo-quickstart-2026-06-04.md)
@@ -0,0 +1,35 @@
1
+ [project]
2
+ name = "chimera-memory"
3
+ version = "0.1.0"
4
+ description = "Local-first reliability ledger for AI coding-agent work"
5
+ requires-python = ">=3.12"
6
+ readme = "README.md"
7
+ license = { file = "LICENSE" }
8
+ classifiers = [
9
+ "Development Status :: 3 - Alpha",
10
+ "License :: OSI Approved :: MIT License",
11
+ "Programming Language :: Python :: 3",
12
+ "Programming Language :: Python :: 3.12",
13
+ "Operating System :: MacOS",
14
+ "Operating System :: POSIX :: Linux",
15
+ "Intended Audience :: Developers",
16
+ "Topic :: Software Development :: Testing",
17
+ "Topic :: Software Development :: Quality Assurance",
18
+ ]
19
+ dependencies = [
20
+ "chimera-memory-types",
21
+ "filelock>=3.0",
22
+ ]
23
+
24
+ [project.scripts]
25
+ chimera-memory = "chimera_memory.cli:main"
26
+
27
+ [tool.uv.sources]
28
+ chimera-memory-types = { workspace = true }
29
+
30
+ [build-system]
31
+ requires = ["hatchling"]
32
+ build-backend = "hatchling.build"
33
+
34
+ [tool.hatch.build.targets.wheel]
35
+ packages = ["src/chimera_memory"]