threadkeeper 0.20.0__tar.gz → 0.21.0__tar.gz

{threadkeeper-0.20.0/threadkeeper.egg-info → threadkeeper-0.21.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: threadkeeper
-Version: 0.20.0
+Version: 0.21.0
 Summary: Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server.
 Author: thread-keeper contributors
 License: MIT
@@ -972,8 +972,12 @@ recovery snapshot right before its first mutating evaluator.
 its token cost); the evaluator then judges currency from local evidence only.
 A batch that holds no skills never gets a researcher: the fixed research topics
 only concern skills, so its evaluator starts at once.
-Each report path is then
-authorized in the existing parent-authored `curator_pass` event;
+Curator pass and snapshot values are explicit, per-child launch data rather
+than temporary server-process environment. Ordinary foreground and daemon
+spawns strip stale inherited values. The private launcher binds each task,
+child identity, pass, batch, phase, role, origin, and exact
+report/research destination before launch; a watchdog retry restores only that
+recorded data.
 `curator_report_write` records its SHA-256 in `curator_report_provenance`.
 This makes the report directory an untrusted transport: a stray or forged
 `REPORT-*.md` file cannot acquire the provenance needed by the applier.
@@ -1055,6 +1059,18 @@ within an 8-second budget per call; a call that runs out falls back to the
 lexical ranking and the next call resumes. Each line shows the lesson's summary. Without a query a session
 would only ever see the newest few lessons, whatever the task.
 
+**Lesson index.** Agents rarely search lessons on their own, so every lesson
+write also refreshes `lesson-index.md` next to `lessons.md`
+(`~/.threadkeeper/lesson-index.md` by default), a sorted list of all lesson
+titles (about 35 000 characters for 550 lessons). The managed
+instructions import it (`@~/.threadkeeper/lesson-index.md`), so a CLI that
+supports imports, such as Claude Code, loads every title with its instructions;
+other CLIs are told to read the file at session start. Each title is the rule,
+and the agent opens the ones that apply with `lesson_get`. On 160 real user
+prompts an agent that saw only this index opened 65-70% of the lessons judged
+relevant, and 51-59% of its picks were relevant. Injecting the lessons whose
+embedding is closest to the prompt reached 25% recall at 12% precision.
+
 Lesson access is tracked the same way skill access is: `lesson_list` increments
 `lesson_usage.view_count` for displayed rows and `lesson_get` increments
 `lesson_usage.use_count` for the returned lesson. Only foreground reads count:
@@ -1448,6 +1464,13 @@ claim and its evidence but closes the old valid-time interval at the new claim's
 slice; `dialectic_review(as_of=...)` and
 `dialectic_synthesis(include_history=True)` expose past validity intervals.
 
+**Durable-preference drift pilot.** Run
+`python -m threadkeeper.dialectic_drift_eval --json` to replay the fixed,
+anonymized durable-change / task-exception / ambiguity / poisoning corpus. It
+reports supersession precision and recall, false durable-flip and clarification
+rates, poisoning containment, cited memory IDs, and counterfactuals. The pilot
+is read-only and does not change the live supersession policy.
+
 **Source-based evidence discount.** Each evidence row's effective weight
 is `base_weight × discount(WRITE_ORIGIN)`. Foreground (direct user / human
 signal) = 1.0. shadow_review / background_review / candidate_review /
@@ -2251,6 +2274,12 @@ It reports these headline groups over a fixed ground-truth set:
 - **retrieval latency** — mean / p50 / p95 / max wall-clock milliseconds. With
   `--semantic`, the backend is reported as `hybrid`, because dense candidates
   augment rather than replace FTS.
+- **forgetting lifecycle** — the bundled mutation fixture writes a fact,
+  corrects it twice, supersedes its dialectic claim, consolidates duplicate
+  verbatim evidence, forgets the old source, and reopens the store in a new
+  process. It reports a separate score for thread notes, verbatim memory,
+  dialectic claims, and lessons or skills.
+
 - **outcome classification** — retrieval failure, reasoning failure,
   stale-memory use, removed-memory use, and privacy-policy violation.
 
@@ -2286,6 +2315,13 @@ retrieved context, or replayed answer is written to stdout, artifacts, or the
 repository. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the corpus
 contract and migration-gate interpretation.
 
+The lifecycle score gives current evidence `+1` and subtracts `0.5` for every
+obsolete or invalidated fact that the same retrieval path returns. A current
+fact alongside stale evidence therefore does not receive full credit. The
+post-forgetting and post-restart stages must score `1.0` in both deterministic
+FTS and hybrid variants; the JSON report names the lifecycle stage and memory
+class for any release-gate failure.
+
 ## Evaluating learning-loop decision quality
 
 `verify_ingest` answers *"did we capture the data?"*. The decision-quality

{threadkeeper-0.20.0 → threadkeeper-0.21.0}/README.md

@@ -925,8 +925,12 @@ recovery snapshot right before its first mutating evaluator.
 its token cost); the evaluator then judges currency from local evidence only.
 A batch that holds no skills never gets a researcher: the fixed research topics
 only concern skills, so its evaluator starts at once.
-Each report path is then
-authorized in the existing parent-authored `curator_pass` event;
+Curator pass and snapshot values are explicit, per-child launch data rather
+than temporary server-process environment. Ordinary foreground and daemon
+spawns strip stale inherited values. The private launcher binds each task,
+child identity, pass, batch, phase, role, origin, and exact
+report/research destination before launch; a watchdog retry restores only that
+recorded data.
 `curator_report_write` records its SHA-256 in `curator_report_provenance`.
 This makes the report directory an untrusted transport: a stray or forged
 `REPORT-*.md` file cannot acquire the provenance needed by the applier.
@@ -1008,6 +1012,18 @@ within an 8-second budget per call; a call that runs out falls back to the
 lexical ranking and the next call resumes. Each line shows the lesson's summary. Without a query a session
 would only ever see the newest few lessons, whatever the task.
 
+**Lesson index.** Agents rarely search lessons on their own, so every lesson
+write also refreshes `lesson-index.md` next to `lessons.md`
+(`~/.threadkeeper/lesson-index.md` by default), a sorted list of all lesson
+titles (about 35 000 characters for 550 lessons). The managed
+instructions import it (`@~/.threadkeeper/lesson-index.md`), so a CLI that
+supports imports, such as Claude Code, loads every title with its instructions;
+other CLIs are told to read the file at session start. Each title is the rule,
+and the agent opens the ones that apply with `lesson_get`. On 160 real user
+prompts an agent that saw only this index opened 65-70% of the lessons judged
+relevant, and 51-59% of its picks were relevant. Injecting the lessons whose
+embedding is closest to the prompt reached 25% recall at 12% precision.
+
 Lesson access is tracked the same way skill access is: `lesson_list` increments
 `lesson_usage.view_count` for displayed rows and `lesson_get` increments
 `lesson_usage.use_count` for the returned lesson. Only foreground reads count:
@@ -1401,6 +1417,13 @@ claim and its evidence but closes the old valid-time interval at the new claim's
 slice; `dialectic_review(as_of=...)` and
 `dialectic_synthesis(include_history=True)` expose past validity intervals.
 
+**Durable-preference drift pilot.** Run
+`python -m threadkeeper.dialectic_drift_eval --json` to replay the fixed,
+anonymized durable-change / task-exception / ambiguity / poisoning corpus. It
+reports supersession precision and recall, false durable-flip and clarification
+rates, poisoning containment, cited memory IDs, and counterfactuals. The pilot
+is read-only and does not change the live supersession policy.
+
 **Source-based evidence discount.** Each evidence row's effective weight
 is `base_weight × discount(WRITE_ORIGIN)`. Foreground (direct user / human
 signal) = 1.0. shadow_review / background_review / candidate_review /
@@ -2204,6 +2227,12 @@ It reports these headline groups over a fixed ground-truth set:
 - **retrieval latency** — mean / p50 / p95 / max wall-clock milliseconds. With
   `--semantic`, the backend is reported as `hybrid`, because dense candidates
   augment rather than replace FTS.
+- **forgetting lifecycle** — the bundled mutation fixture writes a fact,
+  corrects it twice, supersedes its dialectic claim, consolidates duplicate
+  verbatim evidence, forgets the old source, and reopens the store in a new
+  process. It reports a separate score for thread notes, verbatim memory,
+  dialectic claims, and lessons or skills.
+
 - **outcome classification** — retrieval failure, reasoning failure,
   stale-memory use, removed-memory use, and privacy-policy violation.
 
@@ -2239,6 +2268,13 @@ retrieved context, or replayed answer is written to stdout, artifacts, or the
 repository. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the corpus
 contract and migration-gate interpretation.
 
+The lifecycle score gives current evidence `+1` and subtracts `0.5` for every
+obsolete or invalidated fact that the same retrieval path returns. A current
+fact alongside stale evidence therefore does not receive full credit. The
+post-forgetting and post-restart stages must score `1.0` in both deterministic
+FTS and hybrid variants; the JSON report names the lifecycle stage and memory
+class for any release-gate failure.
+
 ## Evaluating learning-loop decision quality
 
 `verify_ingest` answers *"did we capture the data?"*. The decision-quality

{threadkeeper-0.20.0 → threadkeeper-0.21.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "threadkeeper"
-version = "0.20.0"
+version = "0.21.0"
 description = "Multi-agent shared brain across Claude Code/Desktop, Codex, Antigravity CLI, Copilot, and VS Code. Cross-session memory, self-improving skill loops, inter-agent signaling — one local MCP server."
 requires-python = ">=3.11"
 authors = [{ name = "thread-keeper contributors" }]

threadkeeper-0.21.0/tests/test_brief_hook_size.py

@@ -0,0 +1,69 @@
+"""The SessionStart brief stays under the CLI's hook output limit."""
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from pathlib import Path
+
+HOOK = Path(__file__).resolve().parents[1] / "scripts" / "hooks" / "tk-brief.sh"
+
+
+def _run_hook(tmp_path: Path, context_lines: int) -> str:
+    fake_python = tmp_path / "python"
+    body = "\\n".join(f"rule {i}: " + "x" * 60 for i in range(context_lines))
+    fake_python.write_text(
+        "#!/bin/sh\ncat >/dev/null\n"
+        f"printf 'STATUS\\tthread-keeper: ok\\nCONTEXT\\t{body}\\n'\n",
+        encoding="utf-8",
+    )
+    fake_python.chmod(0o700)
+    env = {
+        "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+        "HOME": str(tmp_path),
+        "THREADKEEPER_PYTHON": str(fake_python),
+    }
+    proc = subprocess.run(
+        ["bash", str(HOOK)], input="{}", capture_output=True, text=True, env=env, timeout=30,
+    )
+    assert proc.returncode == 0, proc.stderr
+    return json.loads(proc.stdout)["hookSpecificOutput"]["additionalContext"]
+
+
+def test_oversized_brief_is_cut_at_a_line_break_under_the_hook_limit(tmp_path):
+    context = _run_hook(tmp_path, context_lines=400)
+
+    assert len(context) <= 9000
+    assert context.endswith("call brief() for the rest]")
+    assert "\nrule 0: " in context
+    kept = context.splitlines()[-2]
+    assert kept.startswith("rule ") and kept.endswith("x" * 60)
+
+
+def test_brief_under_the_limit_is_passed_through_whole(tmp_path):
+    context = _run_hook(tmp_path, context_lines=20)
+
+    assert "rule 19: " in context
+    assert "trimmed" not in context
+
+
+def test_brief_without_line_breaks_is_cut_at_the_limit(tmp_path):
+    fake_python = tmp_path / "python"
+    fake_python.write_text(
+        "#!/bin/sh\ncat >/dev/null\n"
+        "printf 'STATUS\\tok\\nCONTEXT\\t%s\\n' \"$(head -c 20000 /dev/zero | tr '\\0' x)\"\n",
+        encoding="utf-8",
+    )
+    fake_python.chmod(0o700)
+    env = {
+        "PATH": os.environ.get("PATH", "/usr/bin:/bin"),
+        "HOME": str(tmp_path),
+        "THREADKEEPER_PYTHON": str(fake_python),
+    }
+    proc = subprocess.run(
+        ["bash", str(HOOK)], input="{}", capture_output=True, text=True, env=env, timeout=30,
+    )
+
+    context = json.loads(proc.stdout)["hookSpecificOutput"]["additionalContext"]
+    assert 8000 < len(context) <= 9000
+    assert context.endswith("call brief() for the rest]")

{threadkeeper-0.20.0 → threadkeeper-0.21.0}/tests/test_brief_sections.py

@@ -146,6 +146,49 @@ def test_consulted_skills_silent_without_events(mp_with_cid):
     assert "consulted_skills" not in txt
 
 
+def test_consulted_lessons_surface_recall_telemetry_and_keep_brief_sections(
+    mp_with_cid,
+):
+    """A recalled lesson keeps its read telemetry visible without dropping
+    the existing thread, evolve, or user-facing brief sections."""
+    pkg = mp_with_cid(_FAKE_CID)
+    lesson_append = _tool(pkg, "lesson_append")
+    lesson_list = _tool(pkg, "lesson_list")
+    lesson_get = _tool(pkg, "lesson_get")
+    open_thread = _tool(pkg, "open_thread")
+
+    assert lesson_append(
+        title="Recall telemetry", body="Use this lesson for brief coverage.",
+        source="shadow",
+    ).startswith("ok")
+    lesson_list(k=1)
+    assert "Use this lesson for brief coverage." in lesson_get(
+        slug="recall-telemetry"
+    )
+    open_thread(question="keep the open section")
+
+    conn = pkg["db"].get_db()
+    conn.execute(
+        "INSERT INTO evolve (suggestion, rationale, applied, status, created_at) "
+        "VALUES (?, ?, 0, 'promoted', ?)",
+        ("seeded promoted suggestion", "brief coverage", int(time.time())),
+    )
+    conn.commit()
+
+    txt = _brief_text(pkg)
+
+    assert "consulted_lessons" in txt
+    assert "recall-telemetry" in txt
+    assert "viewed×1" in txt
+    assert "used×1" in txt
+    assert "last_recalled=" in txt
+    assert "open" in txt
+    assert "keep the open section" in txt
+    assert "evolve_pending" in txt
+    assert "★ \"seeded promoted suggestion\"" in txt
+    assert "⚠️ user-facing: paraphrase plain." in txt
+
+
 def test_skill_nudge_silent_after_materialization(mp_with_cid, monkeypatch):
     monkeypatch.setenv("THREADKEEPER_SKILL_NUDGE_INTERVAL", "3")
     pkg = mp_with_cid(_FAKE_CID)