errlore 0.1.3__tar.gz → 0.2.0__tar.gz

errlore-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,74 @@
+name: release
+
+# Tag-driven release: push a v* tag -> full test gate -> build sdist+wheel ->
+# publish to PyPI via trusted publishing (OIDC; no long-lived token in CI).
+#
+# One-time PyPI setup (owner): pypi.org -> project errlore -> Publishing ->
+# add GitHub publisher (owner=Ma4etaSS, repo=errlore, workflow=release.yml,
+# environment=pypi). Until that's configured the publish step fails cleanly
+# and the build artifacts are still attached to the GitHub release.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install -e .[dev]
+      - run: ruff check .
+      - run: mypy
+      - run: pytest --cov=errlore --cov-fail-under=80
+
+  build:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install build
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write  # OIDC for PyPI trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create GitHub release with artifacts
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${GITHUB_REF_NAME}" dist/* \
+            --title "${GITHUB_REF_NAME}" \
+            --notes "See CHANGELOG.md for details." || \
+          gh release upload "${GITHUB_REF_NAME}" dist/* --clobber

{errlore-0.1.3 → errlore-0.2.0}/CHANGELOG.md

@@ -5,6 +5,60 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.0] - 2026-07-11 — "The Proof Release"
+
+The headline benchmark is now proven on all three generality axes:
+**seed-robustness** (5 independent runs), **task-generality** (fresh realistic
+convention families), and **model-diversity** (Anthropic + Gemma). Development
+status bumped Alpha → Beta.
+
+### Added
+- **Reproducibility evidence for the error-reduction benchmark**
+  (`benchmarks/results/REPRODUCIBILITY_2026-07-11.md`): the headline A/B is now
+  reproduced across 5 independent runs on claude-haiku-4-5 (two default-seed
+  runs 5 days apart + three fresh RNG seeds). Every run: 66.7–69.8% repeat-error
+  reduction, exact McNemar p between 8.4e-12 and 1.8e-9, knowledge-gap reduction
+  95–100%, capability-gap −12% to 0%. Resolves the prior "single run" caveat in
+  the README.
+- `bench_error_reduction.py` reads `BENCH_RNG_SEED` from the environment so the
+  same task families can be re-drawn with different instances for seed-robustness
+  checks. Also `BENCH_FAMILIES` / `BENCH_SEED_N` / `BENCH_TEST_N` for narrowing a
+  run (e.g. a small cross-family probe on a tight free-tier quota).
+- **Task-generality: two new realistic knowledge-gap families** (`status_code` —
+  an arbitrary internal status enum; `branch_name` — a non-standard git branch
+  convention). On claude-haiku-4-5 both go 100% → 0% (24/24 → 0/24, McNemar
+  p=1.19e-07), confirming the store-and-inject effect isn't specific to the
+  original toy families. Report + raw outputs in `benchmarks/results/`.
+- **Model-diversity: full grid on gemma-4-31b** (Cerebras — a different model
+  family): 66.7% → 20.0% fail (70.0% reduction, McNemar p=2.6e-13),
+  knowledge-gap 83%, capability-gap −20%; branch_name and status_code flip
+  100%→0% here too. One honest wrinkle documented: `csv_order` does not
+  transfer to gemma (12→12) while it flips to 0 on Haiku — lesson-following is
+  itself model-dependent at the margin. `BENCH_MODEL` env override added for
+  running any backend against a specific model.
+
+## [0.1.4] - 2026-07-09
+
+### Added
+- **CLI** (`errlore` console command): `errlore init claude-code` writes the
+  two Claude Code hook scripts and idempotently merges them into your
+  `settings.json` (global or `--project`), preserving existing hooks — a
+  one-command install instead of copy/edit/merge. Plus `errlore stats` and
+  `errlore lessons`.
+- `errlore.integrations.claude_code` — the hook logic (`post_tool_use`,
+  `session_start`) now ships in the package and is tested, so the generated
+  hooks are 3-line shims.
+
+### Changed
+- README: honest A/B framing (the knowledge-gap baseline fails by
+  construction; the result shows the capture-and-re-supply loop works, not
+  that memory teaches skills; single-run-at-temp-0 caveat). Coding-agent-first
+  hero. Security section reworded — the sanitizer is a noise filter on the
+  pattern, not an injection defense. Added a "Scale & limits" section
+  (unbounded injections journal, single-process trust/vector index).
+- Examples no longer hard-code aging frontier model ids; they use
+  `os.getenv(...)` with a small default.
+
 ## [0.1.3] - 2026-07-06
 
 ### Fixed

{errlore-0.1.3 → errlore-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: errlore
-Version: 0.1.3
+Version: 0.2.0
 Summary: Memory for AI agents that learns from failures: lessons, known-issues injection, and per-model trust — embedded, file-based, no server.
 Project-URL: Homepage, https://errlore.com
 Project-URL: Repository, https://github.com/Ma4etaSS/errlore
@@ -10,7 +10,7 @@ Author: Ma4etaSS
 License-Expression: MIT
 License-File: LICENSE
 Keywords: agents,error-learning,lessons,llm,memory,trust
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -52,14 +52,30 @@ Your agent keeps making the same mistakes. errlore fixes that:
   into the prompt for similar future tasks.
 - **Known issues** -- per-model weakness tracking ("gpt-5.5 keeps hallucinating dates in
   extraction tasks") injected as warnings.
-- **Trust** -- Bayesian per-model, per-domain trust weights: know which model to pick
-  for which job, based on observed outcomes.
+- **Trust** *(experimental)* -- Bayesian per-model, per-domain trust weights: a starting
+  point for which model to pick per job, based on observed outcomes. Needs a spread of
+  real outcomes to separate models; shipped, but not yet proven on production traffic.
 - **Closed loop** -- errlore tracks whether an injected lesson actually helped and
   reinforces or decays it automatically.
 
 Embedded, file-based (JSONL), no server, no database, no API keys required.
 Works fully offline. Your data never leaves your machine.
 
+## Who it's for
+
+errlore isn't memory for everything — it's memory for **failures**. It shines
+wherever an agent repeats the *same class* of mistake:
+
+- **Coding agents** (Claude Code, Cursor, SWE agents) that keep re-introducing
+  the same bug or forgetting a project convention across sessions.
+- **Extraction pipelines** (PDFs, invoices, contracts) that hallucinate the
+  same date format, rounding rule, or schema field every week.
+- **Any repeated-failure workflow** where a fix should stick the first time,
+  not be re-discovered on every run.
+
+It fixes what the model doesn't *know* (a convention, a gotcha), not what it
+*can't do* — see the benchmark below.
+
 ## Quickstart (< 5 minutes)
 
 ```bash
@@ -99,11 +115,12 @@ JSONL files and does text matching. LLM calls are yours to make (or not).
 
 ## Does it actually reduce errors?
 
-Yes -- for the class of errors memory can fix. Paired A/B benchmark
-(`benchmarks/bench_error_reduction.py`): the same model (claude-haiku-4-5)
-runs 96 tasks twice, with and without errlore injection. Deterministic
-validators, no LLM judges; raw outputs committed in
-[benchmarks/results/error_reduction/](benchmarks/results/error_reduction/).
+For the class of errors memory can fix — yes, and here's the honest version.
+Paired A/B (`benchmarks/bench_error_reduction.py`): the same model
+(claude-haiku-4-5) runs 96 tasks twice, with and without errlore injection.
+Deterministic validators, no LLM judges; raw outputs committed in
+[benchmarks/results/error_reduction/](benchmarks/results/error_reduction/) so
+you can recompute every number.
 
 | arm | failures | fail rate |
 |-----|----------|-----------|
@@ -114,14 +131,36 @@ Exact McNemar over all 96 pairs: p = 1.8e-09 (49 pairs fixed, 6 broken).
 Split by error class:
 
 - **Knowledge-gap errors** (workspace conventions: date formats, ID
-  normalization, rounding rules, CSV column order): **46/48 -> 0/48, a 100%
-  reduction.** The model didn't know the convention; a lesson told it.
+  normalization, rounding rules, CSV column order): 46/48 -> 0/48. The model
+  can't know a convention it was never told, so arm A fails almost by
+  construction; the result shows errlore **captures the fix once and re-supplies
+  it** on the next similar task, end to end. That store-and-inject loop is the
+  claim — not that memory teaches skills.
 - **Capability-gap errors** (letter counting, string reversal): 17/48 ->
   20/48 -- errlore did **not** help and slightly hurt. Memory fixes what the
   model doesn't know, not what it can't do.
 
-Reproduce: `python benchmarks/bench_error_reduction.py` (needs an Anthropic
-API key; the task families and validators ship in the repo).
+**Reproduced across 5 independent runs** (two on the default seed 5 days apart,
+plus three fresh RNG seeds — different task instances). Every run: overall
+reduction **66.7–69.8%**, exact McNemar **p between 8.4e-12 and 1.8e-9**,
+knowledge-gap reduction **95–100%**, capability-gap **−12% to 0%** (no help).
+**Cross-model:** the same grid on **gemma-4-31b** (a different model family)
+lands at **70.0% reduction** (66.7% → 20.0%, p = 2.6e-13), knowledge-gap 83%,
+capability-gap −20% — same effect, same honest boundary. **Task-generality:**
+two fresh realistic-convention families (an arbitrary internal status enum and
+a non-standard git branch convention) go **100% → 0%** on both models.
+Full table + per-run reports:
+[benchmarks/results/REPRODUCIBILITY_2026-07-11.md](benchmarks/results/REPRODUCIBILITY_2026-07-11.md).
+
+**Caveats, up front:** temperature 0 still leaves LLM output slightly
+non-deterministic, so exact fine-grained counts vary run to run — the large
+knowledge-gap effect is robust across all five runs; the capability-gap delta
+stays within noise. The knowledge-gap task families use conventions the model
+demonstrably can't guess, which is the point — but it means the headline is
+"the loop works," not "90% fewer errors everywhere."
+
+Reproduce: `python benchmarks/bench_error_reduction.py --backend anthropic`
+(needs an Anthropic API key; task families and validators ship in the repo).
 
 ## How it works
 
@@ -146,13 +185,19 @@ Per-model, per-task-type error tracking. When a model has failed on a task
 type before, `inject_for` adds a warning block to the prompt. Separate from
 lessons: lessons are *solutions*, known issues are *warnings*.
 
-### 3. Trust loop
+### 3. Trust loop *(experimental)*
 
 Bayesian per-model weights with adaptive learning rate, cold-start blending,
 entropy enforcement, and temporal decay.  After enough observations, call
 `mem.best_model("code_generation")` to pick the model that historically
 performs best on that domain.
 
+> **Status: experimental.** The engine is tested and works, but discrimination
+> between models only emerges from a *spread* of real outcomes over time — feed
+> it a stream that is mostly successes and every model converges near the cap.
+> Treat `best_model()` as a hint to validate, not a proven router yet. The
+> lesson + known-issue loops above are the proven core (see the A/B benchmark).
+
 ## Semantic retrieval (optional)
 
 By default, errlore finds relevant lessons via word overlap (zero
@@ -167,6 +212,10 @@ pip install errlore[embeddings]   # installs fastembed + numpy
 mem = AgentMemory("./agent_memory", embeddings=True)
 ```
 
+> The embedding model (~120 MB ONNX) is downloaded once on first use, then
+> runs locally with no further network calls. The core (word-overlap) stays
+> fully offline and dependency-free.
+
 ### Benchmark (adversarial paraphrasing)
 
 Tested on 40 lessons with adversarially paraphrased queries
@@ -188,15 +237,37 @@ queries with shared vocabulary, word-overlap works fine.
 errlore is framework-agnostic. It produces a text block; you put it in the
 system prompt.
 
-| Provider   | Example                                              |
-|------------|------------------------------------------------------|
-| OpenAI     | [examples/openai_agent.py](examples/openai_agent.py) |
-| Anthropic  | [examples/anthropic_agent.py](examples/anthropic_agent.py) |
-| LangChain  | [examples/langchain_agent.py](examples/langchain_agent.py) |
+**Claude Code** — one command wires up failure-memory across sessions:
+
+```bash
+errlore init claude-code            # or: --project for this repo only
+```
 
-All examples run offline with `python examples/<name>.py` (mock responses,
+Failed Bash commands become lessons; every new session is briefed on past
+pitfalls. See [examples/claude-code/](examples/claude-code/).
+
+| Provider    | Example                                              |
+|-------------|------------------------------------------------------|
+| Claude Code | [examples/claude-code/](examples/claude-code/) — hooks, `errlore init claude-code` |
+| Open WebUI  | [integrations/openwebui/](integrations/openwebui/) — memory Filter + feedback Action |
+| OpenAI      | [examples/openai_agent.py](examples/openai_agent.py) |
+| Anthropic   | [examples/anthropic_agent.py](examples/anthropic_agent.py) |
+| LangChain   | [examples/langchain_agent.py](examples/langchain_agent.py) |
+
+The SDK examples run offline with `python examples/<name>.py` (mock responses,
 no API keys). Set `use_api=True` to call real models.
 
+### CLI
+
+`pip install errlore` also installs an `errlore` command:
+
+```bash
+errlore init claude-code   # install Claude Code hooks + settings
+errlore stats              # memory stats for a data dir (--data-dir)
+errlore lessons            # list stored lessons
+errlore --version
+```
+
 ## API overview
 
 The main entry point is `AgentMemory`. All other classes are internal --
@@ -210,7 +281,7 @@ you only need them for advanced use.
 | `report_outcome(inj, success)` | Close the loop: reinforce lessons, update trust.|
 | `add_lesson(pattern, solution)` | Add a lesson directly (sanitized).            |
 | `lessons(limit)`              | List all lessons (sorted by confidence).       |
-| `best_model(domain)`          | Model with the highest trust weight.           |
+| `best_model(domain)`          | Model with the highest trust weight *(experimental)*. |
 | `model_penalty(model, task_type)` | Error-history penalty `[0, 1]`.            |
 | `pending_injections()`        | Injections not yet reported.                   |
 | `stats()`                     | Aggregate counts + trust weights.              |
@@ -236,6 +307,49 @@ you only need them for advanced use.
   (filelock), `vectors.npy` (embedding vectors), `vector_meta.json`
   (embedding metadata), `trust.json` (trust engine state).
 
+## Security
+
+A lesson is **trusted prompt content by design** — it is injected into your
+prompts and reaches the model. So:
+
+- **Do not ingest lessons from untrusted sources without review.** Treat lesson
+  capture like a code review, not like user input. A malicious lesson is a
+  prompt-injection vector — and this is the real control, not the sanitizer.
+- **What the sanitizer does (and does not) do.** The lesson *pattern* passes
+  `sanitize_lesson_text`: it strips raw-JSON/code-fence *noise* and caps length
+  so log blobs don't pollute the prompt. It is a noise filter, **not** an
+  injection defense — it does not neutralize natural-language instructions, and
+  the *solution* text is stored as you author it (so it can hold real code).
+  Don't rely on it to make untrusted lessons safe.
+- You control what becomes a lesson (`resolve(..., lesson=...)` /
+  `add_lesson(...)`); nothing is auto-promoted from raw model output.
+
+Report security issues to the address in [SECURITY.md](SECURITY.md).
+
+## Scale & limits (honest)
+
+errlore is built for **one process, thousands of lessons** — a single agent or
+a coding-agent session, not a high-throughput fleet. Know the edges:
+
+- **`injections.jsonl` grows unbounded.** `report_outcome` scans the whole
+  ledger each call, so at very high injection volumes it slows down (roughly
+  linear in total injections). Fine for interactive/agent use; log compaction
+  is the next roadmap item. If you don't need the reinforcement loop, you can
+  ignore `report_outcome` and the file stays small.
+- **Single-process by default.** The lesson/error stores use cross-process file
+  locks and are safe to share, but the **trust engine and the optional vector
+  index are not cross-process safe** — two processes writing `trust.json` /
+  `vectors.npy` concurrently can clobber each other (last-writer-wins). Run one
+  writer, or give each process its own `data_dir`. Multi-agent shared memory is
+  on the roadmap.
+- **Embeddings index rebuild is O(n²) over many adds** — building a fresh index
+  over a large existing lesson store is slow the first time (then incremental).
+- Concurrency is tested across threads; **multi-process** stress is not yet in
+  the suite.
+
+None of these bite at the scale errlore targets today; they're stated so you
+can decide, not discover.
+
 ## Roadmap
 
 - [ ] Log compaction for injections journal

{errlore-0.1.3 → errlore-0.2.0}/README.md

@@ -18,14 +18,30 @@ Your agent keeps making the same mistakes. errlore fixes that:
   into the prompt for similar future tasks.
 - **Known issues** -- per-model weakness tracking ("gpt-5.5 keeps hallucinating dates in
   extraction tasks") injected as warnings.
-- **Trust** -- Bayesian per-model, per-domain trust weights: know which model to pick
-  for which job, based on observed outcomes.
+- **Trust** *(experimental)* -- Bayesian per-model, per-domain trust weights: a starting
+  point for which model to pick per job, based on observed outcomes. Needs a spread of
+  real outcomes to separate models; shipped, but not yet proven on production traffic.
 - **Closed loop** -- errlore tracks whether an injected lesson actually helped and
   reinforces or decays it automatically.
 
 Embedded, file-based (JSONL), no server, no database, no API keys required.
 Works fully offline. Your data never leaves your machine.
 
+## Who it's for
+
+errlore isn't memory for everything — it's memory for **failures**. It shines
+wherever an agent repeats the *same class* of mistake:
+
+- **Coding agents** (Claude Code, Cursor, SWE agents) that keep re-introducing
+  the same bug or forgetting a project convention across sessions.
+- **Extraction pipelines** (PDFs, invoices, contracts) that hallucinate the
+  same date format, rounding rule, or schema field every week.
+- **Any repeated-failure workflow** where a fix should stick the first time,
+  not be re-discovered on every run.
+
+It fixes what the model doesn't *know* (a convention, a gotcha), not what it
+*can't do* — see the benchmark below.
+
 ## Quickstart (< 5 minutes)
 
 ```bash
@@ -65,11 +81,12 @@ JSONL files and does text matching. LLM calls are yours to make (or not).
 
 ## Does it actually reduce errors?
 
-Yes -- for the class of errors memory can fix. Paired A/B benchmark
-(`benchmarks/bench_error_reduction.py`): the same model (claude-haiku-4-5)
-runs 96 tasks twice, with and without errlore injection. Deterministic
-validators, no LLM judges; raw outputs committed in
-[benchmarks/results/error_reduction/](benchmarks/results/error_reduction/).
+For the class of errors memory can fix — yes, and here's the honest version.
+Paired A/B (`benchmarks/bench_error_reduction.py`): the same model
+(claude-haiku-4-5) runs 96 tasks twice, with and without errlore injection.
+Deterministic validators, no LLM judges; raw outputs committed in
+[benchmarks/results/error_reduction/](benchmarks/results/error_reduction/) so
+you can recompute every number.
 
 | arm | failures | fail rate |
 |-----|----------|-----------|
@@ -80,14 +97,36 @@ Exact McNemar over all 96 pairs: p = 1.8e-09 (49 pairs fixed, 6 broken).
 Split by error class:
 
 - **Knowledge-gap errors** (workspace conventions: date formats, ID
-  normalization, rounding rules, CSV column order): **46/48 -> 0/48, a 100%
-  reduction.** The model didn't know the convention; a lesson told it.
+  normalization, rounding rules, CSV column order): 46/48 -> 0/48. The model
+  can't know a convention it was never told, so arm A fails almost by
+  construction; the result shows errlore **captures the fix once and re-supplies
+  it** on the next similar task, end to end. That store-and-inject loop is the
+  claim — not that memory teaches skills.
 - **Capability-gap errors** (letter counting, string reversal): 17/48 ->
   20/48 -- errlore did **not** help and slightly hurt. Memory fixes what the
   model doesn't know, not what it can't do.
 
-Reproduce: `python benchmarks/bench_error_reduction.py` (needs an Anthropic
-API key; the task families and validators ship in the repo).
+**Reproduced across 5 independent runs** (two on the default seed 5 days apart,
+plus three fresh RNG seeds — different task instances). Every run: overall
+reduction **66.7–69.8%**, exact McNemar **p between 8.4e-12 and 1.8e-9**,
+knowledge-gap reduction **95–100%**, capability-gap **−12% to 0%** (no help).
+**Cross-model:** the same grid on **gemma-4-31b** (a different model family)
+lands at **70.0% reduction** (66.7% → 20.0%, p = 2.6e-13), knowledge-gap 83%,
+capability-gap −20% — same effect, same honest boundary. **Task-generality:**
+two fresh realistic-convention families (an arbitrary internal status enum and
+a non-standard git branch convention) go **100% → 0%** on both models.
+Full table + per-run reports:
+[benchmarks/results/REPRODUCIBILITY_2026-07-11.md](benchmarks/results/REPRODUCIBILITY_2026-07-11.md).
+
+**Caveats, up front:** temperature 0 still leaves LLM output slightly
+non-deterministic, so exact fine-grained counts vary run to run — the large
+knowledge-gap effect is robust across all five runs; the capability-gap delta
+stays within noise. The knowledge-gap task families use conventions the model
+demonstrably can't guess, which is the point — but it means the headline is
+"the loop works," not "90% fewer errors everywhere."
+
+Reproduce: `python benchmarks/bench_error_reduction.py --backend anthropic`
+(needs an Anthropic API key; task families and validators ship in the repo).
 
 ## How it works
 
@@ -112,13 +151,19 @@ Per-model, per-task-type error tracking. When a model has failed on a task
 type before, `inject_for` adds a warning block to the prompt. Separate from
 lessons: lessons are *solutions*, known issues are *warnings*.
 
-### 3. Trust loop
+### 3. Trust loop *(experimental)*
 
 Bayesian per-model weights with adaptive learning rate, cold-start blending,
 entropy enforcement, and temporal decay.  After enough observations, call
 `mem.best_model("code_generation")` to pick the model that historically
 performs best on that domain.
 
+> **Status: experimental.** The engine is tested and works, but discrimination
+> between models only emerges from a *spread* of real outcomes over time — feed
+> it a stream that is mostly successes and every model converges near the cap.
+> Treat `best_model()` as a hint to validate, not a proven router yet. The
+> lesson + known-issue loops above are the proven core (see the A/B benchmark).
+
 ## Semantic retrieval (optional)
 
 By default, errlore finds relevant lessons via word overlap (zero
@@ -133,6 +178,10 @@ pip install errlore[embeddings]   # installs fastembed + numpy
 mem = AgentMemory("./agent_memory", embeddings=True)
 ```
 
+> The embedding model (~120 MB ONNX) is downloaded once on first use, then
+> runs locally with no further network calls. The core (word-overlap) stays
+> fully offline and dependency-free.
+
 ### Benchmark (adversarial paraphrasing)
 
 Tested on 40 lessons with adversarially paraphrased queries
@@ -154,15 +203,37 @@ queries with shared vocabulary, word-overlap works fine.
 errlore is framework-agnostic. It produces a text block; you put it in the
 system prompt.
 
-| Provider   | Example                                              |
-|------------|------------------------------------------------------|
-| OpenAI     | [examples/openai_agent.py](examples/openai_agent.py) |
-| Anthropic  | [examples/anthropic_agent.py](examples/anthropic_agent.py) |
-| LangChain  | [examples/langchain_agent.py](examples/langchain_agent.py) |
+**Claude Code** — one command wires up failure-memory across sessions:
+
+```bash
+errlore init claude-code            # or: --project for this repo only
+```
 
-All examples run offline with `python examples/<name>.py` (mock responses,
+Failed Bash commands become lessons; every new session is briefed on past
+pitfalls. See [examples/claude-code/](examples/claude-code/).
+
+| Provider    | Example                                              |
+|-------------|------------------------------------------------------|
+| Claude Code | [examples/claude-code/](examples/claude-code/) — hooks, `errlore init claude-code` |
+| Open WebUI  | [integrations/openwebui/](integrations/openwebui/) — memory Filter + feedback Action |
+| OpenAI      | [examples/openai_agent.py](examples/openai_agent.py) |
+| Anthropic   | [examples/anthropic_agent.py](examples/anthropic_agent.py) |
+| LangChain   | [examples/langchain_agent.py](examples/langchain_agent.py) |
+
+The SDK examples run offline with `python examples/<name>.py` (mock responses,
 no API keys). Set `use_api=True` to call real models.
 
+### CLI
+
+`pip install errlore` also installs an `errlore` command:
+
+```bash
+errlore init claude-code   # install Claude Code hooks + settings
+errlore stats              # memory stats for a data dir (--data-dir)
+errlore lessons            # list stored lessons
+errlore --version
+```
+
 ## API overview
 
 The main entry point is `AgentMemory`. All other classes are internal --
@@ -176,7 +247,7 @@ you only need them for advanced use.
 | `report_outcome(inj, success)` | Close the loop: reinforce lessons, update trust.|
 | `add_lesson(pattern, solution)` | Add a lesson directly (sanitized).            |
 | `lessons(limit)`              | List all lessons (sorted by confidence).       |
-| `best_model(domain)`          | Model with the highest trust weight.           |
+| `best_model(domain)`          | Model with the highest trust weight *(experimental)*. |
 | `model_penalty(model, task_type)` | Error-history penalty `[0, 1]`.            |
 | `pending_injections()`        | Injections not yet reported.                   |
 | `stats()`                     | Aggregate counts + trust weights.              |
@@ -202,6 +273,49 @@ you only need them for advanced use.
   (filelock), `vectors.npy` (embedding vectors), `vector_meta.json`
   (embedding metadata), `trust.json` (trust engine state).
 
+## Security
+
+A lesson is **trusted prompt content by design** — it is injected into your
+prompts and reaches the model. So:
+
+- **Do not ingest lessons from untrusted sources without review.** Treat lesson
+  capture like a code review, not like user input. A malicious lesson is a
+  prompt-injection vector — and this is the real control, not the sanitizer.
+- **What the sanitizer does (and does not) do.** The lesson *pattern* passes
+  `sanitize_lesson_text`: it strips raw-JSON/code-fence *noise* and caps length
+  so log blobs don't pollute the prompt. It is a noise filter, **not** an
+  injection defense — it does not neutralize natural-language instructions, and
+  the *solution* text is stored as you author it (so it can hold real code).
+  Don't rely on it to make untrusted lessons safe.
+- You control what becomes a lesson (`resolve(..., lesson=...)` /
+  `add_lesson(...)`); nothing is auto-promoted from raw model output.
+
+Report security issues to the address in [SECURITY.md](SECURITY.md).
+
+## Scale & limits (honest)
+
+errlore is built for **one process, thousands of lessons** — a single agent or
+a coding-agent session, not a high-throughput fleet. Know the edges:
+
+- **`injections.jsonl` grows unbounded.** `report_outcome` scans the whole
+  ledger each call, so at very high injection volumes it slows down (roughly
+  linear in total injections). Fine for interactive/agent use; log compaction
+  is the next roadmap item. If you don't need the reinforcement loop, you can
+  ignore `report_outcome` and the file stays small.
+- **Single-process by default.** The lesson/error stores use cross-process file
+  locks and are safe to share, but the **trust engine and the optional vector
+  index are not cross-process safe** — two processes writing `trust.json` /
+  `vectors.npy` concurrently can clobber each other (last-writer-wins). Run one
+  writer, or give each process its own `data_dir`. Multi-agent shared memory is
+  on the roadmap.
+- **Embeddings index rebuild is O(n²) over many adds** — building a fresh index
+  over a large existing lesson store is slow the first time (then incremental).
+- Concurrency is tested across threads; **multi-process** stress is not yet in
+  the suite.
+
+None of these bite at the scale errlore targets today; they're stated so you
+can decide, not discover.
+
 ## Roadmap
 
 - [ ] Log compaction for injections journal