errlore 0.1.2__tar.gz → 0.1.4__tar.gz

{errlore-0.1.2 → errlore-0.1.4}/CHANGELOG.md

@@ -5,6 +5,45 @@ 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.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
+- Read-cache poisoning race in `JSONLWriter.read_all`: an append landing
+  mid-parse cached pre-append records under the post-append mtime/size, so
+  later reads returned stale data and `atomic_update` could silently drop
+  the concurrent record. Now caches only when the file is unchanged across
+  the parse (pre/post stat match). Found by pre-launch adversarial audit;
+  regression test added (Bug 3).
+- Removed dead `JSONLWriter._invalidate_cache`.
+
+### Changed
+- README: added the error-reduction A/B benchmark section (96 paired tasks,
+  63 -> 20 failures, McNemar p=1.8e-09; knowledge-gap 46/48 -> 0/48,
+  capability-gap honestly worse at 17/48 -> 20/48), so the PyPI page shows
+  the headline evidence, not just the retrieval table.
+
 ## [0.1.2] - 2026-07-06
 
 ### Added

{errlore-0.1.2 → errlore-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: errlore
-Version: 0.1.2
+Version: 0.1.4
 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
@@ -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
@@ -91,12 +107,49 @@ mem.report_outcome(inj, success=True)
 print(mem.stats())
 # {'errors_total': 1, 'errors_resolved': 1, 'errors_unresolved': 0,
 #  'lessons_total': 1, 'lessons_applied': 1, 'pending_injections': 0,
-#  'trust': {'gpt-5.5': 0.55}}
+#  'trust': {'gpt-5.5': 0.5522...}}
 ```
 
 No API keys needed. errlore itself never calls any LLM -- it manages local
 JSONL files and does text matching. LLM calls are yours to make (or not).
 
+## Does it actually reduce errors?
+
+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 |
+|-----|----------|-----------|
+| A: plain | 63/96 | 65.6% |
+| B: with errlore | 20/96 | 20.8% |
+
+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. 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.
+
+**Caveats, up front:** this is a single run at temperature 0 (LLM output is
+still slightly non-deterministic, so exact fine-grained counts vary between
+runs — the large knowledge-gap effect is robust; the capability-gap delta is
+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
 
 errlore runs three reinforcement loops around your agent:
@@ -120,13 +173,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
@@ -141,6 +200,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
@@ -162,15 +225,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
+```
+
+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) |
 
-All examples run offline with `python examples/<name>.py` (mock responses,
+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 --
@@ -184,7 +269,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.              |
@@ -210,6 +295,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.4/README.md

@@ -0,0 +1,318 @@
+# errlore
+
+**Memory for AI agents that learns from failures.**
+
+*Stop the second mistake, not just the first.*
+
+![errlore demo: monday failure becomes a lesson, tuesday's prompt gets it injected](https://errlore.com/demo.gif)
+
+[![CI](https://github.com/Ma4etaSS/errlore/actions/workflows/ci.yml/badge.svg)](https://github.com/Ma4etaSS/errlore/actions/workflows/ci.yml)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+Extracted from a 324K LOC production multi-LLM orchestration system, keeping the one part that demonstrably worked: the error-memory loop that made agents stop repeating mistakes.
+
+Your agent keeps making the same mistakes. errlore fixes that:
+
+- **Lessons** -- every resolved failure becomes a lesson; relevant lessons are injected
+  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** *(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
+pip install errlore
+```
+
+```python
+from errlore import AgentMemory
+
+mem = AgentMemory("./agent_memory")
+
+# 1. Agent failed -- record it
+err_id = mem.log_error("gpt-5.5", "extraction", error="hallucinated dates")
+
+# 2. You fixed it -- extract a lesson
+mem.resolve(err_id, "Added date format validation",
+            lesson="For date extraction, demand ISO-8601 and verify against source")
+
+# 3. Next similar task -- lessons + known issues injected automatically
+inj = mem.inject_for("extract dates from contract", model="gpt-5.5",
+                      task_type="extraction")
+prompt = f"Your task: extract dates\n{inj.text}"
+print(prompt)
+
+# 4. Close the loop -- did the lesson help?
+mem.report_outcome(inj, success=True)
+
+# 5. Check stats
+print(mem.stats())
+# {'errors_total': 1, 'errors_resolved': 1, 'errors_unresolved': 0,
+#  'lessons_total': 1, 'lessons_applied': 1, 'pending_injections': 0,
+#  'trust': {'gpt-5.5': 0.5522...}}
+```
+
+No API keys needed. errlore itself never calls any LLM -- it manages local
+JSONL files and does text matching. LLM calls are yours to make (or not).
+
+## Does it actually reduce errors?
+
+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 |
+|-----|----------|-----------|
+| A: plain | 63/96 | 65.6% |
+| B: with errlore | 20/96 | 20.8% |
+
+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. 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.
+
+**Caveats, up front:** this is a single run at temperature 0 (LLM output is
+still slightly non-deterministic, so exact fine-grained counts vary between
+runs — the large knowledge-gap effect is robust; the capability-gap delta is
+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
+
+errlore runs three reinforcement loops around your agent:
+
+### 1. Lesson loop
+
+```
+Agent fails  -->  log_error()  -->  resolve() + lesson
+                                        |
+Agent runs   <--  inject_for() <--------+
+     |
+     +--> report_outcome(success=True)  -->  lesson confidence +0.1
+     +--> report_outcome(success=False) -->  lesson confidence -0.1
+```
+
+Lessons with high confidence surface first. Unused lessons decay over time.
+
+### 2. Known-issue loop
+
+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 *(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
+dependencies). For higher recall on paraphrased queries, enable embedding
+search:
+
+```bash
+pip install errlore[embeddings]   # installs fastembed + numpy
+```
+
+```python
+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
+(`benchmarks/bench_retrieval.py`):
+
+| Metric    | word-overlap | embeddings |
+|-----------|-------------|------------|
+| recall@1  | 0.000       | 0.375      |
+| recall@3  | 0.000       | 0.575      |
+| recall@5  | 0.000       | 0.675      |
+| MRR       | 0.000       | 0.488      |
+
+The gold set is intentionally adversarial (queries share few literal words
+with the lesson text), which is why word-overlap scores zero.  On natural
+queries with shared vocabulary, word-overlap works fine.
+
+## Integrations
+
+errlore is framework-agnostic. It produces a text block; you put it in the
+system prompt.
+
+**Claude Code** — one command wires up failure-memory across sessions:
+
+```bash
+errlore init claude-code            # or: --project for this repo only
+```
+
+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 --
+you only need them for advanced use.
+
+| Method / Property             | Description                                    |
+|-------------------------------|------------------------------------------------|
+| `log_error(model, task_type, error)` | Record an error. Returns error ID.      |
+| `resolve(err_id, resolution, lesson)` | Mark error fixed, extract a lesson.    |
+| `inject_for(task, model)`     | Build prompt injection (lessons + warnings).   |
+| `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 *(experimental)*. |
+| `model_penalty(model, task_type)` | Error-history penalty `[0, 1]`.            |
+| `pending_injections()`        | Injections not yet reported.                   |
+| `stats()`                     | Aggregate counts + trust weights.              |
+| `.trust`                      | Access the underlying `TrustEngine` (or None). |
+
+### Supporting classes (advanced)
+
+| Class             | Purpose                                    |
+|-------------------|--------------------------------------------|
+| `LessonStore`     | Low-level lesson CRUD + search.            |
+| `TrustEngine`     | Bayesian trust weights with persistence.   |
+| `FeedbackSignal`  | Typed quality signal for trust updates.    |
+| `Injection`       | Dataclass returned by `inject_for`.        |
+
+## Data & privacy
+
+- All data is stored in local JSONL files in the directory you specify.
+- Nothing is sent to any server.  errlore itself makes zero network calls.
+- Works fully offline -- no API keys, no accounts, no telemetry.
+- Files: `errors.jsonl`, `lessons.jsonl`, `injections.jsonl`, `trust.json`,
+  `model_accuracy.jsonl`.
+- Sidecar files (auto-managed): `*.idx` (byte-offset index), `*.lock`
+  (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
+- [ ] Async API (`alog_error`, `ainject_for`, etc.)
+- [ ] Multi-agent shared memory (multiple agents, one lesson store)
+- [ ] Lesson clustering and auto-summarization
+- [ ] Dashboard / CLI for browsing lessons and trust weights
+- [ ] Export/import for lesson sharing between projects
+
+## License
+
+MIT

{errlore-0.1.2 → errlore-0.1.4}/examples/anthropic_agent.py

@@ -16,15 +16,15 @@ runs end-to-end without network access.
 
 from __future__ import annotations
 
+import os
 import tempfile
 from pathlib import Path
 
 from errlore import AgentMemory
 
-# Current Claude lineup (2026): claude-fable-5 (most capable),
-# claude-opus-4-8 (recommended default), claude-sonnet-4-6 (speed/cost balance),
-# claude-haiku-4-5 (fastest). Use exact IDs as-is -- no date suffixes.
-MODEL = "claude-opus-4-8"
+# Model is just a label to errlore (it never calls the API itself). Override
+# with your own Claude model id; the default is a small, fast, cheap option.
+MODEL = os.getenv("ANTHROPIC_MODEL", "claude-3-5-haiku-latest")
 
 
 # -- Agent wrapper -----------------------------------------------------------

errlore-0.1.4/examples/claude-code/README.md

@@ -0,0 +1,37 @@
+# errlore + Claude Code
+
+Give your coding agent a memory of its own failures across sessions:
+
+- **PostToolUse hook** — every failed Bash command is logged into errlore.
+  Resolve the ones you fixed (`mem.resolve(err_id, ..., lesson=...)`) or use
+  `mem.add_lesson()` to capture takeaways directly.
+- **SessionStart hook** — each new session begins with a briefing block of
+  relevant lessons and per-tool KNOWN ISSUES, printed into the context.
+
+## Setup (one command)
+
+```bash
+pip install errlore
+errlore init claude-code            # global (~/.claude/settings.json)
+errlore init claude-code --project  # or this repo only (./.claude/settings.json)
+```
+
+That writes the two hook scripts (to `~/.errlore/hooks/`) and merges them into
+your `settings.json` — idempotently, preserving any hooks you already have.
+Restart Claude Code (or open a new session) to pick them up. Options:
+`--data-dir` (where the memory lives, default `~/.errlore/claude-code`) and
+`--hooks-dir`.
+
+Handy afterwards: `errlore stats` and `errlore lessons` to see what it learned.
+
+### Manual setup (if you'd rather wire it yourself)
+
+The scripts in this folder (`errlore_posttooluse.py`, `errlore_sessionstart.py`)
+plus `settings.json.example` show the shape: copy them somewhere stable, fix the
+paths, and merge into `.claude/settings.json`. `export ERRLORE_DATA=...` picks
+the memory dir.
+
+Notes: hook event field names can differ between Claude Code versions —
+the PostToolUse script reads them defensively and never breaks the agent
+loop (exit 0 on anything unexpected). Check `claude --help` / the hooks
+docs for your version if events don't arrive.

{errlore-0.1.2 → errlore-0.1.4}/examples/langchain_agent.py

@@ -19,14 +19,15 @@ The ``if __name__`` block uses a mock instead of a real LLM call.
 
 from __future__ import annotations
 
+import os
 import tempfile
 from pathlib import Path
 
 from errlore import AgentMemory, Injection
 
-# Current OpenAI lineup (2026): gpt-5.5 (frontier, recommended),
-# gpt-5.4-mini / gpt-5.4-nano (lower latency & cost).
-MODEL = "gpt-5.5"
+# Model is just a label to errlore (it never calls the API itself). Override
+# with your own; the default is a small, cheap, widely-available option.
+MODEL = os.getenv("OPENAI_MODEL", "gpt-4o-mini")
 
 
 # -- errlore + LangChain glue ------------------------------------------------