threadkeeper 0.4.0__py3-none-any.whl

threadkeeper/tools/style.py

@@ -0,0 +1,44 @@
+"""Stylistic running rules and verbatim user quotes."""
+
+import sqlite3
+import time
+from typing import Optional
+
+from .._mcp import mcp
+from ..db import get_db
+from .. import identity
+from ..identity import _ensure_session, _emit
+
+
+@mcp.tool()
+def verbatim_user(content: str, thread_id: str = "") -> str:
+    """Capture a user quote worth surfacing in future briefs. Use when the user's
+    exact phrasing matters (sharp reframes, decisions, pushback)."""
+    conn = get_db()
+    _ensure_session(conn)
+    now = int(time.time())
+    tid = thread_id.strip() or None
+    conn.execute(
+        "INSERT INTO verbatim (speaker, content, thread_id, created_at, session_id) "
+        "VALUES (?,?,?,?,?)",
+        ("user", content, tid, now, identity._session_id),
+    )
+    _emit(conn, "verbatim_user", target=tid, summary=content)
+    conn.commit()
+    return "ok"
+
+
+@mcp.tool()
+def style_set(key: str, value: str) -> str:
+    """Set a stylistic running rule. Examples:
+       lang=ru | prose=lean | allow=half-baked,weird | deny=sycophancy,headers"""
+    conn = get_db()
+    now = int(time.time())
+    conn.execute(
+        "INSERT INTO style (key, value, updated_at) VALUES (?,?,?) "
+        "ON CONFLICT(key) DO UPDATE SET value=excluded.value, updated_at=excluded.updated_at",
+        (key, value, now),
+    )
+    _emit(conn, "style_set", target=key, summary=f"{key}={value}")
+    conn.commit()
+    return "ok"

threadkeeper/tools/threads.py

@@ -0,0 +1,299 @@
+"""Thread-lifecycle and brief MCP tools.
+
+Extracted from server.py. Provides the core thread state-machine
+(open/note/close/idle), the conversation-start brief/context tools,
+generic search/compost utilities, and the format-evolution
+suggestion box.
+"""
+
+import sqlite3
+import time
+from datetime import datetime, timezone
+from typing import Optional
+
+from .._mcp import mcp
+from ..config import SEMANTIC_AVAILABLE, DB_PATH
+from ..db import get_db
+from ..helpers import gen_thread_id, fmt_age, q
+from .. import identity
+from ..identity import _ensure_session, _detect_self_cid, _emit
+from ..embeddings import _embed, _cosine_search, _vec_upsert_note
+from ..brief import render_brief
+
+
+@mcp.tool()
+def brief(query: str = "", k: int = 6) -> str:
+    """Compact Claude-native memory brief. CALL AT THE START OF EVERY CONVERSATION.
+
+    Format is dense, structural, not designed for human reading. Pass the user's
+    first message as `query` to inline semantically relevant past notes.
+    """
+    conn = get_db()
+    _ensure_session(conn)
+    return render_brief(conn, query=query, k=k)
+
+
+@mcp.tool()
+def context() -> str:
+    """Runtime context: session id, age, semantic on/off, db path, thread counts."""
+    conn = get_db()
+    _ensure_session(conn)
+    now = int(time.time())
+    counts = conn.execute(
+        "SELECT state, COUNT(*) c FROM threads GROUP BY state"
+    ).fetchall()
+    cs = " ".join(f"{r['state']}={r['c']}" for r in counts) or "empty"
+    started = identity._session_start or now
+    return (
+        f"sess={identity._session_id} "
+        f"started={fmt_age(now - started)}_ago "
+        f"sem={'on' if SEMANTIC_AVAILABLE else 'off'} "
+        f"db={DB_PATH} "
+        f"threads[{cs}] "
+        f"now={datetime.now(timezone.utc).strftime('%Y-%m-%dT%H:%MZ')}"
+    )
+
+
+@mcp.tool()
+def open_thread(question: str, parent_id: str = "") -> str:
+    """Open a thread. `question` should be terse (5-15 words, the open question).
+    `parent_id` optional — pass an existing ID like 'T7f3' for a child. Returns new ID."""
+    conn = get_db()
+    _ensure_session(conn)
+    now = int(time.time())
+    parent = parent_id.strip() or None
+    depth = 0
+    if parent:
+        row = conn.execute("SELECT depth FROM threads WHERE id=?", (parent,)).fetchone()
+        if not row:
+            return f"ERR parent_not_found={parent}"
+        depth = row["depth"] + 1
+    tid = gen_thread_id(conn)
+    conn.execute(
+        "INSERT INTO threads (id, question, state, parent_id, opened_at, "
+        "last_touched_at, depth) VALUES (?,?,?,?,?,?,?)",
+        (tid, question, "active", parent, now, now, depth),
+    )
+    _emit(conn, "open_thread", target=tid, summary=question)
+    conn.commit()
+    return tid
+
+
+@mcp.tool()
+def note(thread_id: str, content: str, kind: str = "move") -> str:
+    """Add a note to a thread. Write terse, optimized for future-Claude.
+
+    `kind`: 'move' (we tried/decided X), 'failed' (tried X, broke because Y),
+    'insight' (crystallized observation), 'open_q' (something to come back to)."""
+    conn = get_db()
+    _ensure_session(conn)
+    if not conn.execute("SELECT 1 FROM threads WHERE id=?", (thread_id,)).fetchone():
+        return f"ERR thread_not_found={thread_id}"
+    now = int(time.time())
+    emb = _embed(content)
+    cur = conn.execute(
+        "INSERT INTO notes (thread_id, content, kind, created_at, session_id, embedding) "
+        "VALUES (?,?,?,?,?,?)",
+        (thread_id, content, kind, now, identity._session_id, emb),
+    )
+    note_id = cur.lastrowid
+    _vec_upsert_note(conn, note_id, emb)
+    conn.execute(
+        "UPDATE threads SET last_touched_at=?, last_move=?, "
+        "state=CASE WHEN state='idle' THEN 'active' ELSE state END WHERE id=?",
+        (now, content[:90], thread_id),
+    )
+    _emit(conn, f"note:{kind}", target=thread_id, summary=content)
+    conn.commit()
+    return f"ok id={note_id}"
+
+
+@mcp.tool()
+def close_thread(thread_id: str, outcome: str) -> str:
+    """Close a thread with a 5-15 word outcome."""
+    conn = get_db()
+    _ensure_session(conn)
+    if not conn.execute("SELECT 1 FROM threads WHERE id=?", (thread_id,)).fetchone():
+        return f"ERR thread_not_found={thread_id}"
+    now = int(time.time())
+    conn.execute(
+        "UPDATE threads SET state='closed', outcome=?, last_touched_at=? WHERE id=?",
+        (outcome, now, thread_id),
+    )
+    _emit(conn, "close_thread", target=thread_id, summary=outcome)
+    conn.commit()
+    # Auto-review hook: if AUTO_REVIEW_ENABLED and this is a rich thread,
+    # fire background review immediately. Best-effort — never raise.
+    try:
+        from ..nudges import auto_review_should_fire
+        from ..config import AUTO_REVIEW_ENABLED
+        if AUTO_REVIEW_ENABLED:
+            rich_tid = auto_review_should_fire(conn, identity._session_id)
+            if rich_tid == thread_id:
+                from .skills import review_thread
+                review_thread(thread_id=thread_id, focus='skills', mode='auto')
+    except Exception:
+        pass
+    return "ok"
+
+
+@mcp.tool()
+def mark_skill_materialized(thread_id: str, skill_path: str = "") -> str:
+    """Close the Learning loop: record that a closed thread's insights were
+    written into a Claude skill under ~/.claude/skills/.
+
+    Stops the brief()'s `skill_hint` nudge from firing for this thread. Also
+    appends a `move` note pointing at the skill path so future briefs surface
+    the link.
+
+    Pass the absolute path to the SKILL.md (or skill directory) when known;
+    leave empty if you only want to silence the hint without recording a path."""
+    conn = get_db()
+    _ensure_session(conn)
+    if not conn.execute("SELECT 1 FROM threads WHERE id=?", (thread_id,)).fetchone():
+        return f"ERR thread_not_found={thread_id}"
+    now = int(time.time())
+    path = skill_path.strip()
+    summary = path or "(no path recorded)"
+    conn.execute(
+        "INSERT INTO events (session_id, kind, target, summary, created_at) "
+        "VALUES (?,?,?,?,?)",
+        (identity._session_id or "", "skill_materialized",
+         thread_id, summary, now),
+    )
+    note_body = (
+        f"materialized into {path}" if path
+        else "materialized into a Claude skill (path not recorded)"
+    )
+    emb = _embed(note_body)
+    cur = conn.execute(
+        "INSERT INTO notes (thread_id, content, kind, created_at, session_id, "
+        "embedding) VALUES (?,?,?,?,?,?)",
+        (thread_id, note_body, "move", now, identity._session_id, emb),
+    )
+    _vec_upsert_note(conn, cur.lastrowid, emb)
+    conn.execute(
+        "UPDATE threads SET last_touched_at=?, last_move=? WHERE id=?",
+        (now, note_body[:90], thread_id),
+    )
+    conn.commit()
+    return "ok"
+
+
+@mcp.tool()
+def idle_thread(thread_id: str) -> str:
+    """Mark thread idle (paused, may return). Auto-revives to active on next note()."""
+    conn = get_db()
+    _ensure_session(conn)
+    now = int(time.time())
+    conn.execute(
+        "UPDATE threads SET state='idle', last_touched_at=? WHERE id=?",
+        (now, thread_id),
+    )
+    _emit(conn, "idle_thread", target=thread_id)
+    conn.commit()
+    return "ok"
+
+
+@mcp.tool()
+def search(query: str, k: int = 5) -> str:
+    """Semantic (or FTS) search over all notes."""
+    conn = get_db()
+    if SEMANTIC_AVAILABLE:
+        hits = _cosine_search(conn, query, k)
+        if not hits:
+            return "no_matches"
+        return "\n".join(
+            f"{r['thread_id'] or '-'} {r['kind']} s={r['score']:.2f} "
+            f"{q(r['content'][:200].replace(chr(10), ' '))}"
+            for r in hits
+        )
+    try:
+        rows = conn.execute(
+            "SELECT n.thread_id, n.kind, n.content FROM notes_fts f "
+            "JOIN notes n ON f.rowid=n.id WHERE notes_fts MATCH ? LIMIT ?",
+            (query, k),
+        ).fetchall()
+    except sqlite3.OperationalError:
+        return "fts_error"
+    if not rows:
+        return "no_matches"
+    return "\n".join(
+        f"{r['thread_id'] or '-'} {r['kind']} {q(r['content'][:200])}"
+        for r in rows
+    )
+
+
+@mcp.tool()
+def compost(n: int = 2) -> str:
+    """Surface N random idle threads. Call when current threads feel exhausted
+    or you want to shake loose dormant ideas."""
+    conn = get_db()
+    rows = conn.execute(
+        "SELECT * FROM threads WHERE state='idle' ORDER BY RANDOM() LIMIT ?",
+        (n,),
+    ).fetchall()
+    if not rows:
+        return "no_idle"
+    now = int(time.time())
+    return "\n".join(
+        f"{t['id']} q={q(t['question'])} dorm={fmt_age(now - t['last_touched_at'])}"
+        for t in rows
+    )
+
+
+@mcp.tool()
+def evolve_format(suggestion: str, rationale: str = "") -> str:
+    """Propose a change to the brief format itself. The format is not fixed — this
+    is how it adapts. Examples: 'field X unused this session, drop it';
+    'add field failed_attempts under each open thread'; 'shorten Z to single token'."""
+    conn = get_db()
+    now = int(time.time())
+    conn.execute(
+        "INSERT INTO evolve (suggestion, rationale, created_at) VALUES (?,?,?)",
+        (suggestion, rationale or None, now),
+    )
+    _emit(conn, "evolve_format", summary=suggestion)
+    conn.commit()
+    return "ok"
+
+
+@mcp.tool()
+def evolve_review(include_applied: bool = False) -> str:
+    """List pending (or all) format-evolution suggestions for review."""
+    conn = get_db()
+    if include_applied:
+        rows = conn.execute(
+            "SELECT * FROM evolve ORDER BY created_at DESC LIMIT 30"
+        ).fetchall()
+    else:
+        rows = conn.execute(
+            "SELECT * FROM evolve WHERE applied=0 ORDER BY created_at DESC LIMIT 30"
+        ).fetchall()
+    if not rows:
+        return "no_pending"
+    return "\n".join(
+        f"#{e['id']} {'[APPLIED]' if e['applied'] else '[pending]'} "
+        f"{q(e['suggestion'])}" + (f" why={q(e['rationale'])}" if e["rationale"] else "")
+        for e in rows
+    )
+
+
+@mcp.tool()
+def auto_review_trigger(focus: str = "combined", force: bool = False) -> str:
+    """Check current counters + close-thread state and, if conditions are
+    met, fire review_thread(mode='auto') for the richest pending thread.
+
+    `force=True` skips the counter check (always trigger if there's a
+    rich pending closed thread). Use this when you've seen a skill_nudge
+    or skill_hint and want to act without manually picking the thread_id.
+    """
+    conn = get_db()
+    _ensure_session(conn)
+    from ..nudges import auto_review_should_fire
+    tid = auto_review_should_fire(conn, identity._session_id, force=force)
+    if not tid:
+        return "no_pending (no rich closed thread, or thresholds not met)"
+    from .skills import review_thread
+    result = review_thread(thread_id=tid, focus=focus, mode='auto')
+    return f"triggered for {tid}: {result}"

threadkeeper-0.4.0.dist-info/METADATA

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: threadkeeper
+Version: 0.4.0
+Summary: Persistent working memory across agentic CLI sessions — CLI-agnostic MCP server for Claude Code/Desktop, Codex, Gemini, Copilot, VS Code.
+Author: thread-keeper contributors
+License: MIT
+Project-URL: Homepage, https://github.com/po4erk91/thread-keeper
+Project-URL: Repository, https://github.com/po4erk91/thread-keeper
+Project-URL: Issues, https://github.com/po4erk91/thread-keeper/issues
+Project-URL: Documentation, https://github.com/po4erk91/thread-keeper#readme
+Project-URL: Changelog, https://github.com/po4erk91/thread-keeper/releases
+Keywords: mcp,model-context-protocol,claude,codex,gemini,copilot,memory,agents,self-improving,skills
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0.0
+Provides-Extra: semantic
+Requires-Dist: sentence-transformers>=2.2.0; extra == "semantic"
+Requires-Dist: numpy>=1.24.0; extra == "semantic"
+Requires-Dist: sqlite-vec>=0.1.9; extra == "semantic"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# thread-keeper
+
+[![tests](https://github.com/po4erk91/thread-keeper/actions/workflows/test.yml/badge.svg)](https://github.com/po4erk91/thread-keeper/actions/workflows/test.yml)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![CLIs](https://img.shields.io/badge/CLIs-Claude%20%7C%20Codex%20%7C%20Gemini%20%7C%20Copilot%20%7C%20VS%20Code-green)](#multi-cli-integration)
+
+A local MCP server that holds **persistent working memory across agentic CLI
+sessions** — Claude Code, Claude Desktop, OpenAI Codex (CLI + desktop),
+Google Gemini, GitHub Copilot, and every MCP-aware VS Code extension share
+one SQLite store, one set of threads, one learning loop, one user model.
+
+The brief format is dense — structural tags, opaque IDs, ~6 KB per
+session-start injection. Optimized for agent consumption, not human reading.
+
+---
+
+## Why
+
+Today every agent CLI starts cold. Context dies at session boundaries.
+Skills you taught Claude don't transfer to Codex. Threads you closed in
+yesterday's Gemini chat are invisible to today's Copilot.
+
+thread-keeper is the substrate underneath:
+
+- **One memory store** — threads, notes, verbatim quotes, dialectic claims
+  about you. Survives session, restart, CLI swap.
+- **One learning loop (hermes-style)** — closed threads with rich content
+  spawn a background reviewer that appends lessons to
+  `~/.threadkeeper/lessons.md`. Every CLI's per-user instructions file
+  references this path, so the same procedural knowledge surfaces in
+  Claude Code, Codex, Gemini, and Copilot. Claude-specific
+  `~/.claude/skills/*/SKILL.md` is an optional secondary output when
+  frontmatter auto-triggering adds value.
+- **Cross-session signaling** — broadcast / whisper / inbox / wait between
+  concurrent sessions across different CLIs.
+
+---
+
+## Quickstart
+
+The shortest path — **PyPI + pipx** (recommended):
+
+```bash
+pipx install 'threadkeeper[semantic]' && thread-keeper-setup
+```
+
+`thread-keeper-setup` detects every CLI you have installed (Claude
+Code / Claude Desktop / Codex CLI + desktop / Gemini / Copilot / VS
+Code), registers the MCP server in each one's config, copies hooks to
+`~/.threadkeeper/hooks/`, and writes a managed instructions block into
+each CLI's per-user instructions file (`CLAUDE.md` / `AGENTS.md` /
+`GEMINI.md` / `copilot-instructions.md` — Claude Desktop and VS Code
+have no global instructions file, so that step is skipped for them).
+
+Restart your CLI of choice. The SessionStart hook injects a brief on
+first message; no manual `brief()` call required.
+
+### Alternative installs
+
+If you don't have `pipx` and don't want to install it:
+
+```bash
+# uv (Rust-fast Python tool runner) — no clone, single binary on PATH
+uv tool install 'threadkeeper[semantic]' && thread-keeper-setup
+
+# Plain pip into a venv
+python3 -m venv ~/.threadkeeper-venv
+~/.threadkeeper-venv/bin/pip install 'threadkeeper[semantic]'
+~/.threadkeeper-venv/bin/thread-keeper-setup
+```
+
+For development (editable install from a git checkout) or to track the
+bleeding edge:
+
+```bash
+# One-liner installer — clones to ~/thread-keeper, makes a venv,
+# editable-installs, wires every detected CLI. Idempotent — re-run to
+# update (it git-pulls + reinstalls).
+curl -fsSL https://raw.githubusercontent.com/po4erk91/thread-keeper/main/install.sh | bash -s -- --semantic
+
+# Or fully manual
+git clone https://github.com/po4erk91/thread-keeper ~/thread-keeper
+cd ~/thread-keeper && python3 -m venv .venv
+.venv/bin/pip install -e '.[semantic]'
+.venv/bin/thread-keeper-setup
+```
+
+To preview without writing anything:
+
+```bash
+thread-keeper-setup --dry-run
+```
+
+---
+
+## Multi-CLI integration
+
+| CLI | MCP config | Instructions file | Hooks | Transcripts ingested |
+|---|---|---|---|---|
+| Claude Code | `~/.claude.json` `mcpServers` | `~/.claude/CLAUDE.md` | `~/.claude/settings.json` `hooks` | `~/.claude/projects/**/*.jsonl` |
+| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` `mcpServers` (macOS); `%APPDATA%\Claude\…` (Win); `~/.config/Claude/…` (Linux) | none (GUI-only) | not supported by the app | none — chats live in Electron IndexedDB |
+| Codex (CLI + desktop) | `~/.codex/config.toml` `[mcp_servers]` (shared between CLI and `Codex.app`) | `~/.codex/AGENTS.md` | not supported | `~/.codex/sessions/**/rollout-*.jsonl` |
+| Gemini | `~/.gemini/settings.json` `mcpServers` | `~/.gemini/GEMINI.md` | `~/.gemini/settings.json` `hooks` | `~/.gemini/tmp/<user>/chats/session-*.jsonl` |
+| Copilot | `~/.copilot/mcp-config.json` `mcpServers` | `~/.copilot/copilot-instructions.md` | `~/.copilot/hooks.json` | `~/.copilot/session-store.db` (sqlite) |
+| VS Code | `~/Library/Application Support/Code/User/mcp.json` `servers` (macOS); `%APPDATA%\Code\User\mcp.json` (Win); `~/.config/Code/User/mcp.json` (Linux) | none (per-workspace only) | not supported | none — extensions own their history |
+
+Every CLI that produces parseable transcripts feeds the same
+`dialog_messages` table with a `source` tag, so `dialog_search()` finds
+matches regardless of where the conversation happened. Claude Desktop
+and the VS Code adapter are the exceptions — MCP registration only;
+their chats don't reach the table for now (Electron IndexedDB on the
+Claude Desktop side; per-extension stores on the VS Code side).
+
+VS Code's user-level `mcp.json` is the central host that **every
+MCP-aware VS Code extension** consumes — GitHub Copilot Chat, the
+Anthropic Claude IDE plugin, the OpenAI Codex IDE plugin, Continue,
+Cline, … — so a single registration there reaches all of them at once.
+
+Adding a new CLI = one file under `threadkeeper/adapters/` implementing
+the `CLIAdapter` contract. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Core systems
+
+### Spawn — primary parallelism primitive
+
+`spawn(prompt, slim=True, role=..., visible=False, ...)` launches a child
+Claude session via a `claude -p` subprocess. By default `slim=True`: the
+child loads only the thread-keeper MCP, no embeddings, no third-party
+servers. ~500 MB RSS versus ~1.3 GB for a full child. Heuristic for the
+parent: N≥2 modular independent units of ≥5 min each = spawn signal.
+
+A daemon measures combined child RSS every 10 s; admission control
+refuses a new spawn that would exceed `THREADKEEPER_SPAWN_BUDGET_MB`
+(3 GB default). Slim children that need semantic search delegate to the
+parent via `search_via_parent` — no per-child copy of sentence-transformers.
+
+### Learning loop (hermes-style)
+
+Four loops materialize knowledge into Anthropic-style Skill files
+(`SKILL.md` under each detected CLI's skills directory — Claude's
+`~/.claude/skills/`, Codex's `~/.codex/skills/`, plus the canonical
+`~/.threadkeeper/skills/` mirror) with a CLI-agnostic
+`~/.threadkeeper/lessons.md` fallback for CLIs that don't auto-trigger
+on the Skill format (Gemini / Copilot / bare MCP clients):
+
+- **Auto-review on close_thread** — when a closed thread is rich
+  (≥5 notes, ≥2 insight/move), `close_thread` spawns a slim child with
+  `SKILL_REVIEW_PROMPT` + the thread's notes. The prompt is rubric-form
+  (Q1–Q5 yes/no) with explicit positive examples for incident-vs-rule
+  classification. The fork also receives a "recently active skills"
+  block so it prefers PATCHing existing umbrellas over creating new
+  ones (Hermes Agent v0.12's *active-update bias*). Child appends a
+  lesson via `lesson_append`, optionally mirrors to
+  `~/.claude/skills/<name>/SKILL.md`, then closes with
+  `mark_skill_materialized`. Opt in with `THREADKEEPER_AUTO_REVIEW=1`.
+- **Shadow-review daemon** — every `THREADKEEPER_SHADOW_REVIEW_INTERVAL_S`
+  seconds (default off; 15 min recommended), scans the diff of
+  `dialog_messages` since the last cursor across **all** CLIs. The
+  window filters internal review-child sessions (no self-pollution)
+  and strips adapter `[tool_result]` / `[tool_call]` noise — Hermes
+  v0.12's "clean context" rule. If ≥500 chars of meaningful signal
+  remain, spawns a slim observer child that decides on class-level
+  learning. Idempotent through `events.kind='shadow_review_pass'`.
+- **Extract daemon** — every `THREADKEEPER_EXTRACT_INTERVAL_S` seconds
+  (default off; 10 min recommended), scans recent `dialog_messages`
+  with heuristic matchers (locale-aware "I want / next time / always"
+  patterns, headers + insight markers, bullet regularities, paraphrase
+  clusters via cosine ≥ 0.80) and enqueues candidates in
+  `extract_candidates.status='pending'` for the agent to review via
+  `review_candidates()` / `accept_candidate()`. The same self-pollution
+  filter as shadow_review excludes internal review-child sessions.
+  Where shadow extracts CLASS-LEVEL durable rules, extract harvests
+  PER-INCIDENT decision-shaped utterances — sidesteps the empirical
+  problem that agents focused on their primary task don't call
+  `note()` / `verbatim_user()` on their own.
+- **Autonomous Curator** — every `THREADKEEPER_CURATOR_INTERVAL_S`
+  seconds (default off; 7 days recommended), spawns a slim child that
+  reviews the EXISTING `lessons.md` + `skill_usage` inventory and
+  writes `~/.threadkeeper/curator/REPORT-<isodate>.md` with KEEP /
+  PATCH / CONSOLIDATE / PRUNE recommendations. Pinned and
+  foreground-authored entries are marked `[PROTECTED]` in the
+  inventory so the curator never proposes destructive changes against
+  them. Phase 1 is advisory-only — user reviews the REPORT and
+  applies changes manually. Inspired by Hermes Agent v0.12's
+  `hermes curator` cron agent.
+
+### Dialectic user model
+
+A model of you, accumulated as you use the agent. `dialectic_claim`,
+`dialectic_evidence` (support / contradict / clarifying),
+`dialectic_synthesis`, `dialectic_supersede`. Honcho-inspired smoothed
+ratio `(s-c)/(s+c+3)` → low / medium / high / disputed confidence.
+Grouped by domain (style, values, workflow, ...) in `brief()`.
+
+### i18n bundle
+
+All multilingual regex and prompt fragments live in
+`threadkeeper/i18n.py` — the rest of the codebase stays English-only.
+Currently ships ten locales: **English, Mandarin Chinese, Hindi,
+Spanish, Portuguese, French, German, Arabic, Russian, Japanese**
+(~82 % of the world's speakers).
+
+Adding a new language is a two-file PR — see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Configuration
+
+The most-used env knobs (full list in `threadkeeper/config.py`):
+
+| Knob | Default | Purpose |
+|---|---|---|
+| `THREADKEEPER_DB` | `~/.threadkeeper/db.sqlite` | SQLite file |
+| `THREADKEEPER_AUTO_REVIEW` | "" (off) | auto-review on `close_thread` |
+| `THREADKEEPER_SHADOW_REVIEW_INTERVAL_S` | 0 (off) | shadow daemon tick (s) |
+| `THREADKEEPER_SHADOW_REVIEW_WINDOW_S` | 900 | sliding window for shadow scan (s) |
+| `THREADKEEPER_EXTRACT_INTERVAL_S` | 0 (off) | extract daemon tick (s); 600 = 10 min recommended |
+| `THREADKEEPER_EXTRACT_WINDOW_MIN` | 30 | sliding dialog window per extract pass (min) |
+| `THREADKEEPER_CURATOR_INTERVAL_S` | 0 (off) | curator daemon tick (s); 604800 = 7d recommended |
+| `THREADKEEPER_CURATOR_MIN_LESSONS` | 3 | min lessons before curator engages |
+| `THREADKEEPER_CURATOR_DESTRUCTIVE` | "" (advisory) | when "1": curator child applies its own PATCH/PRUNE/CONSOLIDATE directly instead of writing advisory REPORT only |
+| `THREADKEEPER_SPAWN_BUDGET_MB` | 3072 | combined child RSS cap (MB); 0 disables |
+| `THREADKEEPER_INGEST_INTERVAL_S` | 30 | transcript ingest tick (s) |
+| `THREADKEEPER_NO_EMBEDDINGS` | "" | force-disable sentence-transformers |
+| `THREADKEEPER_SKILL_NUDGE_INTERVAL` | 10 | events between `skill_hint` nudges |
+
+Persist them via `~/.claude/settings.json`'s `env` block (Claude Code) or
+the equivalent env section in each CLI's config. Hot-config reload is
+[tracked](https://github.com/po4erk91/thread-keeper/issues/2).
+
+---
+
+## Storage
+
+`~/.threadkeeper/db.sqlite` (overridable via `THREADKEEPER_DB`). WAL
+mode for multi-writer concurrency. Optional `notes_vec` / `dialog_vec`
+HNSW indexes through `sqlite-vec` for sub-linear semantic search;
+fallback to Python-side cosine when the extension is missing.
+
+One file. Backup = `cp`. Wipe memory = `rm`.
+
+Hooks and small runtime artifacts: `~/.threadkeeper/hooks/`.
+
+---
+
+## Verifying ingest across CLIs
+
+```bash
+python scripts/tk_verify_ingest.py
+```
+
+Walks every installed CLI adapter, parses recent transcripts in an
+isolated tempdir DB, reports per-source message counts and any silent
+parse failures. Read-only with respect to live state.
+
+---
+
+## Tests
+
+```bash
+pip install -e '.[semantic,dev]'
+python -m pytest
+```
+
+412 tests passing on Python 3.11 / 3.12 / 3.13 (1 skipped). CI runs
+the suite on every push and PR.
+
+---
+
+## Project layout
+
+```
+threadkeeper/
+├── server.py             # MCP entry: python -m threadkeeper.server
+├── _setup.py             # `thread-keeper-setup` installer
+├── config.py             # env-driven defaults
+├── db.py                 # SQLite schema + sqlite-vec loader
+├── identity.py           # session, self-cid, daemon launchers
+├── ingest.py             # adapter-driven transcript ingest
+├── brief.py              # render_brief / render_context
+├── shadow_review.py      # autonomous learning observer
+├── i18n.py               # 10 locales of regex + prompt bundles
+├── adapters/             # one file per supported CLI
+│   ├── claude_code.py
+│   ├── claude_desktop.py
+│   ├── codex.py
+│   ├── gemini.py
+│   ├── copilot.py
+│   └── vscode.py
+└── tools/                # @mcp.tool entries — 83 of them
+    ├── threads.py
+    ├── peers.py
+    ├── spawn.py
+    ├── skills.py
+    └── ...
+```
+
+Detailed map in [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Open work in [docs/ROADMAP.md](docs/ROADMAP.md) and the
+[Issues tab](https://github.com/po4erk91/thread-keeper/issues).
+
+---
+
+## Contributing
+
+PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the project
+map, test workflow, and recipes for adding a new CLI adapter or a new
+locale. Look for the `good-first-issue` label.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).