What can I do if I recognize the merit but barely understand the technical terminology?

Short answer. Give this text to your AI and ask it something like, “I want to have the system described here. What can we do?” Follow the guidance (critically, as usual). Ask the AI to explain the uncertain parts.

Long answer. First, you need an AI subscription and an AI agent client (aka environment, aka harness) that can read and write local files. We cannot recommend exact providers; availability, price, and regulation depend on your region. For the harness, we suggest starting with VS Code or Zed: both are highly configurable and can connect to multiple providers. Prefer a setup that is not limited to one web interface; API-key support or another portable provider connection will leave you more flexible. Then install our memory.instructions.md (in VS Code terminology) and start working.

Session-history instructions and readers

Local session-history instruction

Source: prompts/session-history.instructions.md

---
applyTo: "**"
---

## Local session history

When previous-session context would help, use the local read-only session readers directly:

- VS Code: `scripts/vscode-session-reader.py` (`list`, `tail`, `show`, `search`)
- Zed: `scripts/zed-threads.py` (`list`, `show`, `search`)

List newest sessions first, exclude the current or empty catch-up session, then select the previous substantive session by
exact ID. Redirect a bounded tail or precise search to a scratch file, inspect its byte and line count, and only then load it
into model context. If the result is too large, narrow the range. Corroborate transcript claims against current files, Git
state, and logs. Never load an unbounded database/search result or modify the session store during recovery.

VS Code catch SKILL

Source: prompts/session-catch-vscode.prompt.md

---
name: session-catch-vscode
description: "Restore context from a previous VS Code session using the read-only local session reader."
---

# Session Catch (VS Code)

Recover the relevant tail of a previous VS Code conversation without modifying VS Code's database or session files.

## Prerequisites

- Python 3.10 or newer
- PowerShell 7 (`pwsh`) on Windows, Linux, or macOS
- `vscode-session-reader.py` from this article/repository
- a VS Code workspace containing at least one local chat session

The reader supports normal VS Code and VS Code Insiders user-data locations on Windows, Linux, and macOS. If VS Code uses a
custom `--user-data-dir`, pass that same directory to the reader with `--user-data-dir`.

## Safety model

The reader is structurally read-only: it exposes only `list`, `search`, `show`, and `tail`; opens VS Code's SQLite index in
read-only mode; and never modifies session JSONL. It is safe to use while VS Code is running.

## Procedure

### 1. Locate the previous substantive session

Resolve the reader from this skill's canonical checkout. Allow an explicit environment-variable override for copied or
non-symlinked installations. Fail fast if neither path exists; do not recursively scan the home directory.

```powershell
$reader = $env:VSCODE_SESSION_READER
if ([string]::IsNullOrWhiteSpace($reader)) {
  $liveSkill = Join-Path $HOME ".agents/skills/session-catch-vscode/SKILL.md"
  $skill = Get-Item -LiteralPath $liveSkill -Force -ErrorAction Stop
  if ($skill.LinkType -ne "SymbolicLink") {
    throw "Set VSCODE_SESSION_READER to the full path of vscode-session-reader.py."
  }

  $target = [string]$skill.Target
  if (-not [System.IO.Path]::IsPathRooted($target)) {
    $target = Join-Path $skill.DirectoryName $target
  }

  $canonicalSkill = (Resolve-Path -LiteralPath $target -ErrorAction Stop).Path
  $repo = Split-Path -Parent (Split-Path -Parent $canonicalSkill)
  $reader = Join-Path $repo "scripts/vscode-session-reader.py"
}

if (-not (Test-Path -LiteralPath $reader -PathType Leaf)) {
  throw "VS Code session reader not found at '$reader'. Set VSCODE_SESSION_READER explicitly."
}
```

Set the workspace path explicitly and save the newest-first session list to a scratch file:

```powershell
$workspace = "<WORKSPACE_PATH>"
$outDir = Join-Path $workspace "tmp/session-catch-vscode"
New-Item -ItemType Directory -Path $outDir -Force | Out-Null

$list = Join-Path $outDir "vscode-session-list.txt"
python $reader list --workspace $workspace *> $list
Get-Item -LiteralPath $list | Select-Object FullName, Length
(Get-Content -LiteralPath $list).Count
Get-Content -LiteralPath $list | Select-Object -First 20
```

When using a custom VS Code profile directory, add this argument to each reader call:

```powershell
--user-data-dir "<VS_CODE_USER_DATA_DIR>"
```

Choose the newest previous session that contains the work being resumed. Exclude the current catch-up session, empty `New
Chat` entries, and failed catch-up attempts. Copy the complete UUID from `list --json` when truncated display output is
ambiguous:

```powershell
python $reader list --workspace $workspace --json
```

### 2. Count messages and extract a bounded tail

```powershell
$previousUuid = "<PREVIOUS_SESSION_UUID>"
$meta = Join-Path $outDir "previous-meta.txt"
python $reader tail --uuid $previousUuid --workspace $workspace `
  -n 1 --responses *> $meta
Get-Item -LiteralPath $meta | Select-Object FullName, Length
(Get-Content -LiteralPath $meta).Count

$match = Select-String -LiteralPath $meta `
  -Pattern '^Total user messages: (\d+)$'
$total = [int]$match.Matches[0].Groups[1].Value
$from = [Math]::Max(0, $total - 100)
$to = $total - 1

$thread = Join-Path $outDir "previous-thread.txt"
python $reader show --uuid $previousUuid --workspace $workspace `
  --range $from $to --full --responses *> $thread
Get-Item -LiteralPath $thread | Select-Object FullName, Length
(Get-Content -LiteralPath $thread).Count
```

Inspect byte and line counts before loading the file into model context. If it is unexpectedly large, rerun with the last
50 or 20 user-message positions. `tail` is for counting and overview; bounded `show --full --responses` supplies context.

### 3. Recover persistent working state

Use the transcript together with current durable artifacts:

- project memory or working notes, when the project has them;
- current source files and generated artifacts;
- version-control status and the relevant scoped diff;
- build, test, experiment, or job logs;
- a precise search when a named decision or phrase is missing.

For a targeted search, redirect first and inspect size:

```powershell
$search = Join-Path $outDir "vscode-session-search.txt"
python $reader search --uuid $previousUuid --workspace $workspace `
  --responses --full "<PRECISE_QUERY>" *> $search
Get-Item -LiteralPath $search | Select-Object FullName, Length
(Get-Content -LiteralPath $search).Count
```

The readable transcript intentionally includes user text and textual model responses while omitting raw tool-result payloads.
Recover operational ground truth from files, version control, and logs rather than assuming prose records every side effect.

### 4. Produce the handoff

State:

- which prior session was selected and why;
- the purpose and current state of the work;
- verified results and decisions;
- relevant artifacts and observed disk state;
- unresolved questions;
- the exact next action.

Distinguish transcript claims from state verified in current files, version control, or logs.

Zed catch SKILL

Source: prompts/session-catch-zed.prompt.md

---
name: session-catch-zed
description: "Restore context from a previous Zed session using the read-only local thread reader."
---

# Session Catch (Zed)

Recover the relevant tail of a previous Zed conversation without modifying Zed's database.

## Prerequisites

- Python 3.10 or newer
- PowerShell 7 (`pwsh`) on Windows, Linux, or macOS
- Python package `zstandard` (`python -m pip install zstandard`)
- `zed-threads.py` from this article/repository
- a local Zed installation containing at least one thread

The reader discovers standard Zed database locations on Windows, Linux, and macOS. Set `ZED_THREADS_DB` to the complete
`threads.db` path when using a custom location.

## Safety model

The reader is structurally read-only. It exposes only `list`, `show`, and `search`, opens Zed's local thread database for
reading, and writes nothing unless ordinary shell redirection is used to save its output.

## Procedure

### 1. Locate the previous substantive thread

Set the repository and reader paths explicitly, then save the newest-first thread list to a scratch file:

```powershell
$reader = "<PATH_TO_ZED_THREADS_READER>"
$workspace = "<WORKSPACE_PATH>"
$outDir = Join-Path $workspace "tmp/session-catch-zed"
New-Item -ItemType Directory -Path $outDir -Force | Out-Null

$list = Join-Path $outDir "zed-thread-list.txt"
python $reader list *> $list
Get-Item -LiteralPath $list | Select-Object FullName, Length
(Get-Content -LiteralPath $list).Count
Get-Content -LiteralPath $list | Select-Object -First 20
```

Choose the newest previous thread that contains the work being resumed. Exclude the current catch-up thread, tiny empty
threads, and failed catch-up attempts. Use the selected thread's exact ID prefix in subsequent commands.

### 2. Extract a bounded tail

Write at most the last 100 messages to disk before loading them into model context:

```powershell
$threadId = "<THREAD_ID_PREFIX>"
$thread = Join-Path $outDir "previous-thread.txt"
python $reader show $threadId --tail 100 --full *> $thread
Get-Item -LiteralPath $thread | Select-Object FullName, Length
(Get-Content -LiteralPath $thread).Count
```

Inspect the byte and line counts first. If the output is unexpectedly large, rerun with `--tail 50` or `--tail 20`. Then
read the resulting file as one coherent range. Do not stream an unknown-size database dump or broad search result directly
into model context.

### 3. Recover persistent working state

Use the transcript together with current durable artifacts:

- project memory or working notes, when the project has them;
- current source files and generated artifacts;
- version-control status and the relevant scoped diff;
- build, test, experiment, or job logs;
- a precise thread-local search when a named decision or phrase is missing.

For a targeted search, redirect first and inspect size:

```powershell
$search = Join-Path $outDir "zed-thread-search.txt"
python $reader search "<PRECISE_QUERY>" *> $search
Get-Item -LiteralPath $search | Select-Object FullName, Length
(Get-Content -LiteralPath $search).Count
```

### 4. Produce the handoff

State:

- which prior thread was selected and why;
- the purpose and current state of the work;
- verified results and decisions;
- relevant artifacts and observed disk state;
- unresolved questions;
- the exact next action.

Distinguish transcript claims from state verified in current files, version control, or logs.

Reader source code

(!) The readers rely on undocumented client-history formats and may need updates when those formats change.

VS Code session reader

Source: scripts/vscode-session-reader.py

#!/usr/bin/env python3
"""Read local VS Code chat sessions without modifying VS Code state.

Supported commands: list, search, show, tail.
The reader opens state.vscdb in read-only mode and reads chatSessions/*.jsonl.
"""

from __future__ import annotations

import argparse
import json
import os
import sqlite3
import sys
from datetime import datetime
from pathlib import Path
from typing import Any
from urllib.parse import unquote, urlparse


def configure_streams() -> None:
    for stream in (sys.stdout, sys.stderr):
        reconfigure = getattr(stream, "reconfigure", None)
        if reconfigure is not None:
            reconfigure(encoding="utf-8")


def user_data_roots(explicit: Path | None = None) -> list[Path]:
    if explicit is not None:
        return [explicit / "User"]
    if sys.platform == "win32":
        appdata = Path(os.environ.get("APPDATA", ""))
        return [appdata / "Code" / "User", appdata / "Code - Insiders" / "User"]
    if sys.platform == "darwin":
        base = Path.home() / "Library" / "Application Support"
        return [base / "Code" / "User", base / "Code - Insiders" / "User"]
    config = Path(os.environ.get("XDG_CONFIG_HOME", Path.home() / ".config"))
    return [config / "Code" / "User", config / "Code - Insiders" / "User"]


def folder_uri_to_path(uri: str) -> Path | None:
    parsed = urlparse(uri)
    if parsed.scheme != "file":
        return None
    path = unquote(parsed.path)
    if sys.platform == "win32" and path.startswith("/") and len(path) > 2 and path[2] == ":":
        path = path[1:]
    return Path(path).resolve()


def find_workspace_storage(workspace: Path, user_data_dir: Path | None = None) -> Path | None:
    wanted = workspace.resolve()
    for user_data in user_data_roots(user_data_dir):
        storage_root = user_data / "workspaceStorage"
        if not storage_root.is_dir():
            continue
        for candidate in storage_root.iterdir():
            metadata = candidate / "workspace.json"
            if not metadata.is_file():
                continue
            try:
                folder = json.loads(metadata.read_text(encoding="utf-8")).get("folder", "")
                actual = folder_uri_to_path(folder)
            except (OSError, json.JSONDecodeError, ValueError):
                continue
            if actual == wanted:
                return candidate
    return None


def storage_paths(workspace: Path, user_data_dir: Path | None = None) -> tuple[Path, Path]:
    storage = find_workspace_storage(workspace, user_data_dir)
    if storage is None:
        raise RuntimeError(
            f"No VS Code workspace storage found for {workspace.resolve()}. "
            "Open the folder in VS Code and create at least one chat first."
        )
    database = storage / "state.vscdb"
    sessions = storage / "chatSessions"
    if not database.is_file():
        raise RuntimeError(f"Missing {database}")
    if not sessions.is_dir():
        raise RuntimeError(f"Missing {sessions}")
    return database, sessions


def read_index(database: Path) -> dict[str, Any]:
    uri = database.resolve().as_uri() + "?mode=ro"
    connection = sqlite3.connect(uri, uri=True)
    try:
        row = connection.execute(
            "SELECT value FROM ItemTable WHERE key = ?", ("chat.ChatSessionStore.index",)
        ).fetchone()
    finally:
        connection.close()
    if row is None:
        return {}
    value = row[0].decode("utf-8") if isinstance(row[0], bytes) else row[0]
    return json.loads(value)


def list_sessions(database: Path, sessions_dir: Path) -> list[dict[str, Any]]:
    entries = read_index(database).get("entries", {})
    result = []
    for session_id, metadata in entries.items():
        session_file = sessions_dir / f"{session_id}.jsonl"
        timestamp = metadata.get("lastMessageDate", 0)
        result.append(
            {
                "id": session_id,
                "title": metadata.get("title", "(untitled)"),
                "timestamp": timestamp,
                "date": datetime.fromtimestamp(timestamp / 1000).isoformat(timespec="minutes")
                if timestamp
                else None,
                "exists": session_file.is_file(),
                "size": session_file.stat().st_size if session_file.is_file() else 0,
            }
        )
    result.sort(key=lambda item: item["timestamp"], reverse=True)
    return result


def resolve_session(args: argparse.Namespace, database: Path, sessions_dir: Path) -> dict[str, Any]:
    sessions = list_sessions(database, sessions_dir)
    if args.uuid:
        matches = [item for item in sessions if item["id"] == args.uuid]
    else:
        query = args.session.casefold()
        matches = [item for item in sessions if query in item["title"].casefold()]
    if len(matches) != 1:
        if not matches:
            raise RuntimeError("No matching session")
        choices = "\n".join(f"  {item['date']}  {item['title']}  {item['id']}" for item in matches)
        raise RuntimeError(f"Session selector is ambiguous:\n{choices}")
    if not matches[0]["exists"]:
        raise RuntimeError(f"Session JSONL is missing for {matches[0]['id']}")
    return matches[0]


def reconstruct_session(session_file: Path) -> dict[str, Any]:
    # JSON Lines records are delimited by LF. str.splitlines() also splits on
    # legal JSON string characters such as U+0085 (NEL), corrupting a record.
    lines = session_file.read_text(encoding="utf-8").split("\n")
    if not lines:
        raise RuntimeError(f"Empty session file: {session_file}")
    base = json.loads(lines[0])
    if base.get("kind") != 0 or "v" not in base:
        raise RuntimeError(f"Unsupported initial JSONL record in {session_file}")
    session = base["v"]
    for raw in lines[1:]:
        if not raw.strip():
            continue
        patch = json.loads(raw)
        kind = patch.get("kind")
        keys = patch.get("k", [])
        value = patch.get("v")
        if not keys:
            continue
        parent = session
        traversal = keys if kind == 2 else keys[:-1]
        try:
            for key in traversal:
                parent = parent[key]
        except (KeyError, IndexError, TypeError):
            continue
        if kind == 1:
            try:
                parent[keys[-1]] = value
            except (KeyError, IndexError, TypeError):
                continue
        elif kind == 2 and isinstance(parent, list):
            start = patch.get("i")
            if start is not None:
                del parent[start:]
            if isinstance(value, list):
                parent.extend(value)
        elif kind == 3:
            key = keys[-1]
            if isinstance(parent, dict):
                parent.pop(key, None)
            elif isinstance(parent, list) and isinstance(key, int) and 0 <= key < len(parent):
                del parent[key]
    return session


def response_text(items: list[Any]) -> str:
    parts = []
    for item in items:
        if isinstance(item, dict) and item.get("kind") is None:
            value = item.get("value")
            if isinstance(value, str) and value.strip():
                parts.append(value.strip())
    return "\n".join(parts)


def collect_messages(session_file: Path, responses: bool) -> list[dict[str, Any]]:
    session = reconstruct_session(session_file)
    messages = []
    for index, request in enumerate(session.get("requests", [])):
        timestamp = request.get("timestamp", 0)
        text = request.get("message", {}).get("text", "")
        if text:
            messages.append({"index": index, "timestamp": timestamp, "role": "user", "text": text})
        if responses:
            text = response_text(request.get("response", []))
            if text:
                messages.append(
                    {"index": index, "timestamp": timestamp, "role": "assistant", "text": text}
                )
    return messages


def format_message(message: dict[str, Any], full: bool) -> str:
    timestamp = message["timestamp"]
    when = datetime.fromtimestamp(timestamp / 1000).isoformat(timespec="minutes") if timestamp else "?"
    marker = ">>>" if message["role"] == "assistant" else "   "
    if not full:
        return f"{marker} req[{message['index']}] {when}: {message['text'][:80].replace(chr(10), ' ')}"
    indented = message["text"].replace("\n", "\n      ")
    return f"{marker} req[{message['index']}] {when}:\n      {indented}"


def select_messages(
    messages: list[dict[str, Any]], start: int | None, end: int | None
) -> list[dict[str, Any]]:
    if start is None or end is None:
        return messages
    return [message for message in messages if start <= message["index"] <= end]


def print_messages(messages: list[dict[str, Any]], full: bool, as_json: bool) -> None:
    if as_json:
        print(json.dumps(messages, indent=2, ensure_ascii=False))
        return
    for message in messages:
        print(format_message(message, full))
        if full:
            print()



def parser() -> argparse.ArgumentParser:
    common = argparse.ArgumentParser(add_help=False)
    common.add_argument("--workspace", type=Path, default=Path.cwd())
    common.add_argument("--user-data-dir", type=Path, help="explicit VS Code user-data directory")
    common.add_argument("--json", action="store_true")
    selector = common.add_mutually_exclusive_group()
    selector.add_argument("--session")
    selector.add_argument("--uuid")

    result = argparse.ArgumentParser(description=__doc__)
    commands = result.add_subparsers(dest="command", required=True)
    commands.add_parser("list", parents=[common])

    search = commands.add_parser("search", parents=[common])
    search.add_argument("query")
    search.add_argument("-C", "--context", type=int, default=0)
    search.add_argument("--responses", action="store_true")
    search.add_argument("--full", action="store_true")

    tail = commands.add_parser("tail", parents=[common])
    tail.add_argument("-n", type=int, default=10)
    tail.add_argument("--responses", action="store_true")
    tail.add_argument("--full", action="store_true")

    show = commands.add_parser("show", parents=[common])
    show.add_argument("--range", nargs=2, type=int, metavar=("FROM", "TO"), required=True)
    show.add_argument("--responses", action="store_true")
    show.add_argument("--full", action="store_true")

    return result


def main() -> int:
    configure_streams()
    args = parser().parse_args()
    try:
        database, sessions_dir = storage_paths(args.workspace, args.user_data_dir)
        sessions = list_sessions(database, sessions_dir)
        if args.command == "list":
            if args.json:
                print(json.dumps(sessions, indent=2, ensure_ascii=False))
            else:
                for item in sessions:
                    print(f"{item['date'] or '?':16} {item['size']:>10,}  {item['id'][:12]}  {item['title']}")
            return 0

        if not args.session and not args.uuid:
            raise RuntimeError("Specify exactly one of --session or --uuid")
        session = resolve_session(args, database, sessions_dir)
        session_file = sessions_dir / f"{session['id']}.jsonl"
        responses = getattr(args, "responses", True)
        messages = collect_messages(session_file, responses=responses)

        if args.command == "tail":
            if not args.json:
                total = len({message["index"] for message in messages if message["role"] == "user"})
                print(f"Total user messages: {total}")
            print_messages(messages[-args.n :], args.full, args.json)
        elif args.command == "show":
            print_messages(select_messages(messages, *args.range), args.full, args.json)
        elif args.command == "search":
            matches = [index for index, message in enumerate(messages) if args.query.casefold() in message["text"].casefold()]
            selected = set()
            for index in matches:
                selected.update(range(max(0, index - args.context), min(len(messages), index + args.context + 1)))
            print_messages([messages[index] for index in sorted(selected)], args.full, args.json)
        return 0
    except (OSError, RuntimeError, sqlite3.Error, json.JSONDecodeError) as error:
        print(f"ERROR: {error}", file=sys.stderr)
        return 1


if __name__ == "__main__":
    raise SystemExit(main())

Zed session reader

Source: scripts/zed-threads.py

#!/usr/bin/env python3
"""
zed-threads.py — Zed thread reader for session migration.

Reads threads from Zed's local threads.db,
decompresses zstd JSON blobs, and outputs readable conversation text.

Usage:
    python zed-threads.py list [--limit N]
    python zed-threads.py show <thread_id_prefix> [--tail N] [--full]
    python zed-threads.py search <text> [--limit N]


Thread ID prefix: first 8+ chars of the UUID, enough to be unique.

Environment:
    ZED_THREADS_DB  Override path to threads.db
                    Default: %LOCALAPPDATA%/Zed/threads/threads.db
"""

import argparse
import json
import os
import re
import sqlite3
import sys
import textwrap
from datetime import datetime
from pathlib import Path

# Force UTF-8 stdout on Windows
if sys.platform == "win32":
    sys.stdout.reconfigure(encoding="utf-8", errors="replace")
    sys.stderr.reconfigure(encoding="utf-8", errors="replace")

try:
    import zstandard as zstd
except ImportError:
    print("ERROR: pip install zstandard", file=sys.stderr)
    sys.exit(1)


def get_db_path() -> Path:
    env = os.environ.get("ZED_THREADS_DB")
    if env:
        return Path(env)
    local = os.environ.get("LOCALAPPDATA", "")
    if local:
        return Path(local) / "Zed" / "threads" / "threads.db"
    # Linux/Mac fallback
    home = Path.home()
    for candidate in [
        home / ".local" / "share" / "zed" / "threads" / "threads.db",
        home / "Library" / "Application Support" / "Zed" / "threads" / "threads.db",
    ]:
        if candidate.exists():
            return candidate
    print("ERROR: Cannot find threads.db. Set ZED_THREADS_DB.", file=sys.stderr)
    sys.exit(1)


def connect(db_path: Path) -> sqlite3.Connection:
    if not db_path.exists():
        print(f"ERROR: {db_path} not found", file=sys.stderr)
        sys.exit(1)
    return sqlite3.connect(db_path.resolve().as_uri() + "?mode=ro", uri=True)


def decompress(data: bytes, data_type: str) -> dict:
    if data_type == "zstd":
        decompressor = zstd.ZstdDecompressor()
        # Some frames lack content size in header; use streaming
        reader = decompressor.stream_reader(data)
        raw = reader.read()
        reader.close()
    else:
        raw = data
    return json.loads(raw)


def format_timestamp(ts: str | None) -> str:
    if not ts:
        return "?"
    try:
        # Zed uses RFC 3339 with nanoseconds
        # Truncate to microseconds for Python
        ts_clean = re.sub(r"(\.\d{6})\d+", r"\1", ts)
        dt = datetime.fromisoformat(ts_clean)
        return dt.strftime("%Y-%m-%d %H:%M")
    except Exception:
        return ts[:16] if len(ts) > 16 else ts


def format_size(n: int) -> str:
    if n < 1024:
        return f"{n}B"
    elif n < 1024 * 1024:
        return f"{n / 1024:.1f}KB"
    else:
        return f"{n / (1024 * 1024):.1f}MB"


def resolve_thread_id(conn: sqlite3.Connection, prefix: str) -> str:
    """Resolve a thread ID prefix to a full ID. Exits if ambiguous or not found."""
    cur = conn.cursor()
    cur.execute("SELECT id FROM threads WHERE id LIKE ?", (prefix + "%",))
    matches = cur.fetchall()
    if len(matches) == 0:
        print(f"ERROR: No thread matching '{prefix}'", file=sys.stderr)
        sys.exit(1)
    if len(matches) > 1:
        print(f"ERROR: Ambiguous prefix '{prefix}', matches:", file=sys.stderr)
        for m in matches:
            print(f"  {m[0]}", file=sys.stderr)
        sys.exit(1)
    return matches[0][0]


# ─── Commands ───────────────────────────────────────────────────────


def cmd_list(args):
    conn = connect(get_db_path())
    cur = conn.cursor()
    cur.execute(
        "SELECT id, summary, created_at, updated_at, data_type, length(data), folder_paths "
        "FROM threads ORDER BY updated_at DESC LIMIT ?",
        (args.limit,),
    )
    rows = cur.fetchall()
    if not rows:
        print("No threads found.")
        return

    print(f"{'ID':12s}  {'Size':>8s}  {'Updated':16s}  {'Summary'}")
    print("─" * 80)
    for tid, summary, created, updated, dtype, size, folders in rows:
        print(
            f"{tid[:12]}  {format_size(size):>8s}  "
            f"{format_timestamp(updated):16s}  {summary[:50]}"
        )
    conn.close()


def extract_content_parts(content_list: list) -> str:
    """Extract bounded readable text from Zed's content segment array."""
    parts = []
    for seg in content_list:
        if isinstance(seg, str):
            parts.append(seg)
        elif isinstance(seg, dict):
            # Zed uses PascalCase variant tags: {"Text": "..."}, {"Thinking": {...}}, etc.
            if "Text" in seg:
                parts.append(seg["Text"])
            elif "text" in seg:
                parts.append(seg["text"])
            elif "Thinking" in seg:
                t = seg["Thinking"]
                text = t.get("text", "") if isinstance(t, dict) else str(t)
                if text:
                    parts.append(
                        f"[thinking: {text[:200]}...]"
                        if len(text) > 200
                        else f"[thinking: {text}]"
                    )
            elif "ToolUse" in seg:
                tu = seg["ToolUse"]
                name = tu.get("name", "?") if isinstance(tu, dict) else "?"
                inp = tu.get("input", {}) if isinstance(tu, dict) else {}
                if isinstance(inp, dict):
                    keys = list(inp.keys())
                    parts.append(f"[tool: {name}({', '.join(keys[:5])})]")
                else:
                    parts.append(f"[tool: {name}]")
            elif "ToolResult" in seg:
                tr = seg["ToolResult"]
                content = tr.get("content", "") if isinstance(tr, dict) else str(tr)
                if isinstance(content, list):
                    # Tool result content is often [{"Text": "..."}]
                    text_parts = []
                    for item in content:
                        if isinstance(item, dict) and "Text" in item:
                            text_parts.append(item["Text"][:200])
                        elif isinstance(item, str):
                            text_parts.append(item[:200])
                    content = "\n".join(text_parts)
                if isinstance(content, str) and len(content) > 300:
                    content = content[:300] + "..."
                parts.append(f"[result: {content}]")
            elif "Image" in seg:
                parts.append("[image]")
            else:
                # Unknown segment type — show keys
                keys = list(seg.keys())
                parts.append(f"[{keys[0] if keys else '?'}: ...]")
    return "\n".join(p for p in parts if p)


def extract_messages(thread_json: dict) -> list[dict]:
    """Extract messages from thread JSON as role/text/timestamp/id records."""
    messages = []
    raw_messages = thread_json.get("messages", [])

    for msg in raw_messages:
        # Zed format: each message is {"User": {...}}, {"Agent": {...}}, or {"System": {...}}
        if isinstance(msg, dict):
            for role_key in ("User", "Agent", "System", "Assistant"):
                if role_key in msg:
                    inner = msg[role_key]
                    content_raw = inner.get("content", [])
                    if isinstance(content_raw, list):
                        text = extract_content_parts(content_raw)
                    elif isinstance(content_raw, str):
                        text = content_raw
                    else:
                        text = str(content_raw)

                    messages.append(
                        {
                            "role": role_key.lower(),
                            "text": text,
                            "timestamp": inner.get("created_at"),
                            "id": inner.get("id", ""),
                        }
                    )
                    break
            else:
                # Unknown role variant
                keys = list(msg.keys())
                messages.append(
                    {
                        "role": keys[0] if keys else "unknown",
                        "text": "",
                        "timestamp": None,
                    }
                )

    return messages


def cmd_show(args):
    conn = connect(get_db_path())
    thread_id = resolve_thread_id(conn, args.thread_id)
    cur = conn.cursor()
    cur.execute(
        "SELECT summary, data_type, data, created_at, updated_at, folder_paths FROM threads WHERE id = ?",
        (thread_id,),
    )
    row = cur.fetchone()
    if not row:
        print(f"ERROR: Thread {thread_id} not found", file=sys.stderr)
        sys.exit(1)

    summary, data_type, data, created, updated, folders = row


    thread_json = decompress(data, data_type)
    messages = extract_messages(thread_json)

    # Header
    print(f"Thread: {summary}")
    print(f"ID: {thread_id}")
    print(f"Created: {format_timestamp(created)}  Updated: {format_timestamp(updated)}")
    if folders:
        print(f"Workspace: {folders}")
    print(f"Messages: {len(messages)}")
    print("═" * 80)

    # Optionally tail
    if args.tail and args.tail < len(messages):
        messages = messages[-args.tail :]
        print(f"(showing last {args.tail} messages)\n")

    for i, msg in enumerate(messages):
        role = msg["role"].upper()
        ts = ""
        if msg.get("timestamp"):
            ts = f" [{format_timestamp(msg['timestamp'])}]"

        if role == "USER":
            print(f"\n{'─' * 40} USER{ts} {'─' * 35}")
        elif role == "ASSISTANT":
            print(f"\n{'─' * 38} ASSISTANT{ts} {'─' * 32}")
        else:
            print(f"\n{'─' * 38} {role}{ts} {'─' * 32}")

        text = msg["text"].strip()
        if text:
            # Truncate very long messages for overview
            if not args.full and len(text) > 3000:
                print(text[:3000])
                print(
                    f"\n... [{len(text) - 3000} chars truncated, use --full to see all]"
                )
            else:
                print(text)

    conn.close()


def cmd_search(args):
    conn = connect(get_db_path())
    cur = conn.cursor()
    cur.execute(
        "SELECT id, summary, data_type, data, updated_at, length(data) "
        "FROM threads ORDER BY updated_at DESC"
    )
    pattern = re.compile(re.escape(args.text), re.IGNORECASE)
    found = 0

    for tid, summary, data_type, data, updated, size in cur:
        # Search in summary first (cheap)
        if pattern.search(summary or ""):
            print(
                f"{tid[:12]}  {format_size(size):>8s}  {format_timestamp(updated)}  {summary[:60]}"
            )
            found += 1
            if found >= args.limit:
                break
            continue
        # Search in decompressed content
        try:
            thread_json = decompress(data, data_type)
            messages = extract_messages(thread_json)
            for msg in messages:
                if pattern.search(msg["text"]):
                    print(
                        f"{tid[:12]}  {format_size(size):>8s}  {format_timestamp(updated)}  {summary[:60]}"
                    )
                    found += 1
                    break
        except Exception:
            pass
        if found >= args.limit:
            break

    if found == 0:
        print(f"No threads matching '{args.text}'")
    conn.close()



# ─── Main ───────────────────────────────────────────────────────────


def main():
    parser = argparse.ArgumentParser(
        description="Zed thread reader for session migration",
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog=textwrap.dedent("""
        Examples:
          zed-threads.py list
          zed-threads.py list --limit 20
          zed-threads.py show 965cf72c --tail 20

          zed-threads.py search "GigaChat"
        """),
    )
    sub = parser.add_subparsers(dest="command", required=True)

    # list
    p_list = sub.add_parser("list", help="List recent threads")
    p_list.add_argument("--limit", type=int, default=15)

    # show
    p_show = sub.add_parser("show", help="Show thread conversation")
    p_show.add_argument("thread_id", help="Thread ID prefix (8+ chars)")
    p_show.add_argument("--tail", type=int, help="Show only last N messages")

    p_show.add_argument(
        "--full", action="store_true", help="Don't truncate long messages"
    )

    # search
    p_search = sub.add_parser("search", help="Search thread content")
    p_search.add_argument("text", help="Text to search for")
    p_search.add_argument("--limit", type=int, default=10)


    args = parser.parse_args()

    if args.command == "list":
        cmd_list(args)
    elif args.command == "show":
        cmd_show(args)
    elif args.command == "search":
        cmd_search(args)


if __name__ == "__main__":
    main()

Relation to AGENTS.md/CLAUDE.md and the exact loading mechanism

The obvious neighboring mechanism is AGENTS.md/CLAUDE.md [3], [4]. At the mechanical level, it is similar: persist text and load it into a later context. The functional contract is different. Repository instruction files normally carry shared, relatively stable project guidance; our MEMORY/JOURNAL carries user-assistant continuity, changing rationale, corrections, failed approaches, and prompt candidates that may span repositories. A mature rule may be promoted into checked-in AGENTS.md, but the file does not recover the previous session or decide which personal observation should become team policy.

Both VS Code and Zed place AGENTS.md content near the beginning of each request as part of the system prompt [5], [6], [7], [8]. Changes become visible on the next request, but changing that prefix invalidates the server-side KV cache from the first changed token [9]. At current Claude Opus 4.7 API list prices, rebuilding a one-million-token prefix costs USD 5.75 more than reading it from cache.

Claude Code and Codex use a different approach: they snapshot instructions when the session or run starts; Claude Code also reloads them after /compact [3], [10]. Edits do not affect the active conversation until an explicit reload. This avoids accidental cache misses but leaves the session on stale instructions in the meantime.

Neither policy fits changing mid-memory particularly well. This is one reason we prefer an ordinary file loaded deliberately. The contract is unusually portable: every agent system we use can read a file through an ordinary file tool, and that read enters the conversation at the current position rather than rewriting an earlier request prefix. The current session keeps using the copy already present in its conversation. We can edit the durable file without silently changing the active prompt, and the next session reads the current version during its explicit startup procedure. Promotion into always-loaded instructions remains useful for stable rules, but it is a poor default for knowledge that is supposed to evolve while we work.

Meta-lesson: before implementing any AI subsystem, verify the exact behavior of the agent harness (the client/runtime that assembles model requests and mediates context, tools, and persistence). Which files does it discover? When are they read? Where do they enter the request: system/developer instructions, user context, or tool output? Are they snapshotted per session, watched and reloaded per request, or injected only after an explicit action? Which prefix does the provider cache, what invalidates it, and how are cache reads and writes billed? Do not infer these semantics from the filename or from another client implementing the same convention. Otherwise the system can behave surprisingly or produce a surprising bill.

From incidents to precedents

Daily work produces different kinds of reusable precedent. Sometimes we preserve a way to investigate, sometimes a procedure that should improve through recurrence, and sometimes the reason an apparent result must be rejected.

History as architecture documentation

While implementing a feature, I could not integrate it correctly. After several attempts, I asked the AI to inspect Git history: who had made a similar change, when, and exactly which files had changed together? The previous working change exposed an integration contract that neither the current code nor the build documentation made obvious. I then asked the AI to memoize the method—to preserve it as reusable precedent—rather than this one fix:

When adding to a configuration system you do not fully understand, search history for the most distinctive existing entry and inspect the complete change that introduced it. Use that diff to discover the parallel manifests, exports, packaging, localization, or generated files the new entry also requires.

The first use solved one feature-integration problem. The promoted heuristic now applies whenever an unfamiliar integration scatters its real contract across configuration, packaging, generated artifacts, or other companion files.

Repair the procedure, not only the current file

Some build-configuration files kept generated locale lists on lines more than a thousand characters long. A normal structured edit triggered an editor formatter, reflowing the complete file when only one entry was intended to change. Applying another text edit to repair the result risked transforming it again, so we restored the exact committed bytes through Git and changed the procedure rather than merely fixing that file.

The remembered procedure now treats these files as byte-sensitive: make a surgical line insertion outside the formatter, use a fresh shell scope so stale variables cannot affect the operation, then verify the exact line-count delta, the number of matching entries, and the trailing newline. When the problem recurred, the assistant could recover and refine that procedure instead of rediscovering the failure:

corrupted edit
→ exact byte restoration
→ reviewed repair procedure
→ postcondition checks added by recurrence

A workaround becomes cumulative only when the durable procedure changes with what the next execution teaches us.

A 39% regression that was not a regression

A candidate computational GPU kernel appeared to reduce token-generation speed by 39%. We inspected the implementation and reverted it before noticing that two detached workers were saturating the same GPU during the candidate run. The code had changed, but so had the experiment.

The invalid result remained useful because JOURNAL preserved the sequence and MEMORY preserved the corrected rule:

Benchmark conditions include machine load. Before timing, verify detached jobs and GPU/accelerator utilization. A large unexpected regression is first a measurement-validity question. Output-correctness and model-quality checks may remain valid under contention; timing comparisons do not.

The point of MEMORY was not to keep the original conclusion alive. It was to prevent the same invalid comparison from controlling the next decision.

Governance in practice

The formal words are accumulation, curation, and promotion. In practice, the review sounds more like this:

— Memoize that as YOUR judgement =)

— No, that is an editorial contract. I mean, that exact statement is not for the doc. Memoize it separately.

The MEMORY culture changes the current work, not only the next session. Before writing an entry, the assistant may ask:

— Is this global or project-local?

— Is it the intended architecture, a temporary workaround, or a hack we accepted?

— Is it an observation, hypothesis, decision, or preference?

— What is its provenance, and what would make it obsolete?

Answering forces a high-level judgment while the context is still warm. These small interventions form the decision record: they distinguish a reviewed contract from a plausible summary and maintain a shared model of the system.

That is the division of labor. We delegate low-level search, editing, command execution, and repetitive mechanics to AI while retaining purpose, architecture, trade-offs, and ownership. Writing MEMORY is the checkpoint where generated work is lifted back into a human-understood model: what changed, why we accepted it, and what should govern the next decision.

Reference memory instructions, consolidation procedure, and examples

Cross-session memory instructions

# Cross-Session Memory Instructions

At the start of a new session:

1. Read the complete `MEMORY.md`.
2. Read the recent tail of `JOURNAL.md` needed to recover active work.

Use the files for different purposes:

- `JOURNAL.md` records consequential working trajectory: attempts, failures, observations, active state,
  artifact paths, and the next discriminating action. Append while work develops.
- `MEMORY.md` stores reviewed reusable precedent: constraints, rationale, heuristics, preferences, ownership,
  and uncertain but important findings. Revise existing entries instead of appending contradictory layers.

Do not silently convert conversation into precedent. The AI may propose a memory candidate, but consequential
admission, scope, and promotion are reviewed with the operator. Preserve attribution, epistemic status,
relevant date/version, and a pointer to primary evidence when being wrong would matter.

When a memory matures, consider the mechanism that fits its type:

- behavioral rule → instruction or operating contract;
- repeated procedure → script or SKILL, when its contract is worth defining and maintaining;
- deterministic invariant → design, type, schema, assertion, or test;
- local rationale → comment or README;
- professional routing → address book;
- obsolete, contradicted, derivable, or irrelevant material → correct, relocate, or delete.

MEMORY is context and cached precedent, not absolute truth. Current primary artifacts and reproducible
observations can invalidate it. Report contradictions and repair the cache rather than choosing silently.

When memory behavior is surprising, explain which remembered rule or fact influenced the response and cite its
exact entry. Treat the explanation as a hypothesis; verify it against the loaded files and available tool
trace. Diagnose both false negatives (relevant memory was not used) and false positives (irrelevant, stale, or
overgeneralized memory controlled the response), then correct and retry.

MEMORY example

# MEMORY — Example

## Benchmark validity

**Observed 2026-08-11; project: ExampleKernel.** A candidate appeared to regress generation throughput by 39%,
but two detached workers were using the same GPU during the candidate run. The timing comparison was invalid;
correctness checks remained usable.

**Reusable rule:** before comparing timing or throughput, verify detached jobs and GPU/accelerator
utilization. A large unexpected regression is first a measurement-validity question. Record machine load with
every timing cell.

**Primary evidence:** `JOURNAL.example.md`, benchmark log `example-kernel-20260811.log`, commit `0123456`.

JOURNAL example

# JOURNAL — Example

## 2026-08-11 — ExampleKernel comparison

Purpose: determine whether the candidate kernel increases fixed-workload throughput without changing
model-output quality.

The baseline ran on an idle GPU. The candidate reported a 39% generation regression. Before changing code,
checked active jobs and found two detached decomposition workers saturating the same device. The result is
invalid; the magnitude is not plausible for the candidate's small scheduling change.

Completed:

- output-correctness and model-quality checks passed;
- invalid timing artifacts retained for diagnosis;
- candidate revert recorded but should not be interpreted as evidence against the design.

Next action: stop or finish the unrelated workers, restore the candidate, then rerun baseline and candidate
under matched idle conditions with utilization recorded.

Memory consolidation procedure

# Memory Consolidation

Maintain an existing MEMORY/JOURNAL system. A consolidation pass is not a summary of the latest conversation.

## Procedure

1. Read the complete relevant MEMORY files and the JOURNAL ranges needed to recover provenance.
2. Find exact and semantic duplicates, contradictions, stale paths/versions, misplaced project material,
   unresolved claims stated as facts, and procedures or invariants that belong in stronger artifacts.
3. For each candidate, choose explicitly:
   - keep;
   - rewrite;
   - merge;
   - correct;
   - relocate;
   - promote;
   - delete.
4. Preserve meaningful disagreement, attribution, uncertainty, scope, and evidence pointers.
5. Update dependent instructions, scripts, indexes, and references when an entry moves.
6. Review the diff for accidental loss of distinct reasoning and run formatting checks.

The AI may perform search and mechanical editing. A human reviews admissions, semantic merges, corrections,
deletions, and promotion decisions. Automatic consolidation without review can recursively summarize earlier
model output into apparent authority without adding evidence.

A successful pass makes the memory system smaller, more accurate, or easier to act on. Merely appending
today's summary is memoization, not consolidation.

Machine setup

A first machine setup may contain package searches, failed commands, driver conflicts, configuration choices, and verification output. The next machine rarely needs a byte-for-byte replay: the AI can recover the execution, retain decisions that still apply, adapt paths and versions, and avoid failures already paid for. Repeated setups may later justify a reviewed installation script or playbook.

Urgent bug

An urgent integration fix once depended on testing an unpublished upstream package inside a larger application. A previous session had already discovered the non-obvious mechanics: replacing the compiled library was insufficient because the runtime loaded a separate bundled artifact, and the build could rematerialize the installed package. We recovered that concrete execution, adapted the package locations, copied the source, compiled library, and runtime bundle, verified hashes and a load-bearing marker, restarted the bundler, and continued debugging.

Pausing to design abstract-fix-abstract-bug.SKILL would not have improved the fix. With one or two examples, the resulting “abstraction” may amount to:

Find a pull request with a similar bug and apply it while adjusting the file paths.

That adds almost no capability over reconstructing the concrete prior execution. Fix the bug, preserve the new sample, and generalize later if recurrence reveals a real contract.

Workflow reconstruction prompt

The complete prompt is included from its canonical source file.

Reconstruct-workflow SKILL

Source: prompts/reconstruct-workflow.prompt.md

---
name: reconstruct-workflow
description: "Recover and reuse a previously performed workflow from MEMORY, JOURNAL, session history, files, and logs; use when: remember we did something like this, recover old pipeline, rerun prior procedure, or extract a shareable script or SKILL."
---

# Reconstruct Workflow

Recover a useful earlier procedure that was not formalized when first performed.
The common case is informal: the operator remembers that we did something similar, while the exact sessions, commands, or
rationale are fuzzy. The value of this SKILL is tool-driven archaeology and evidence aggregation—not the abstract idea of
promotion, which ordinary memory management and `create-skill` already cover.

## When to use

- “Remember, we did something like this?”
- A previous repair, experiment, setup, or command sequence may solve the current problem.
- We remember the rationale but not the mechanics, or the mechanics but not why they had that shape.
- A recovered workflow may now deserve a shareable script, SKILL, or runbook.

## Evidence layers

- **MEMORY:** rationale, constraints, reusable lessons, and likely vocabulary.
- **JOURNAL:** approximate episode, date, machine, failures, filenames, logs, and search terms.
- **Session history:** exact dialogue, commands, tool calls, outputs, edits, and corrections.
- **Current files and logs:** what survives now and whether the old procedure still applies.

These layers are fallible and complementary. Even ideal history can recover only the performed pipeline and the decisions
explicitly discussed at the time. It does not determine the future abstraction: name, invocation trigger, supported scope,
inputs, outputs, safety boundary, generality, or maintenance contract. Those are design decisions for the present use case,
not facts latent in the transcript. Do not invent them—or missing rationale—from a surviving command or final artifact.

## Procedure

### 1. Collect anchors already in context

Start from the present request and the MEMORY/JOURNAL material already loaded. Extract a few distinctive anchors:

- filename, symbol, command, error, person, machine, date, project, or unusual phrase;
- the old purpose and the current purpose;
- any recorded artifact or log path.

Do not design a reconstruction schema before searching. Usually one good literal is enough.

### 2. Check the actual session history

Use the editor-appropriate read-only history tool:

- VS Code: `vscode-session-reader.py list/search/show/tail`
- Zed: `zed-threads.py list/search/show`

Search the most distinctive literal first. If it matches several sessions, use date/project/title and the JOURNAL episode
to identify the relevant session or sequence of sessions. Prefer exact session IDs after discovery.

Check session history by default even when MEMORY/JOURNAL appear sufficient. They are curated secondary sources; the raw
history records actual prior usage and lets us test whether the reconstructed workflow matches what happened. Skip history
only when the operator explicitly forbids it, the source is unavailable, or the retrieval cost is clearly disproportionate to the
current consequence; state the omission.

Redirect potentially large output to a scratch file, inspect byte and line count, then read only a bounded coherent range.
Do not load raw session databases or unbounded tool output into model context.

### 3. Read outward only as needed

Inspect the surrounding turns and recover:

- what we were trying to do;
- the exact mechanics that mattered;
- failures and corrections;
- environment assumptions;
- observed completion checks.

If the first range answers the current question, stop. Expand to more turns, tool traces, or another linked session only
when a concrete gap remains.

### 4. Check current reality

Before reuse, inspect the current source, scripts, configuration, Git state, logs, tool versions, paths, and machine state
relevant to the recovered workflow. Separate still-valid rationale from stale mechanics.

Historical commands are evidence, not present authorization. Recovered SSH, destructive, credential, external-write,
commit, push, or publication actions retain their normal current permission boundaries.

### 5. Use the result at the requested level

Choose the smallest useful result:

- answer a factual question from the recovered evidence;
- rerun or adapt the procedure when currently authorized;
- borrow one technique without recreating the whole pipeline;
- restore a lost artifact;
- update MEMORY only when reconstruction changes reusable understanding;
- append JOURNAL only when reconstruction changes active state or records a consequential discovery;
- present the recovered information for discussion; only after its purpose, scope, interface, and remaining uncertainty
  are agreed should a separate `create-skill` invocation—or script/runbook edit—perform promotion.

Do not manufacture a new named artifact merely because reconstruction succeeded. This SKILL stops at evidence-backed
reconstruction and discussion; it never creates another SKILL automatically. Conversely, shareability alone can justify a
later, explicit promotion even when the private workflow already works without a SKILL.

## Completion checks

The reconstruction is complete when:

1. the relevant historical evidence chain is identified; a workflow may span several sessions;
2. current purpose, old rationale, and exact mechanics are distinguishable;
3. consequential claims point to session/file/log evidence or are marked uncertain;
4. current-environment differences have been checked;
5. the requested result is delivered or one concrete missing fact is reported.

## Privacy

Do not promote unrelated private conversation details into MEMORY, documentation, scripts, or SKILLs merely because they
appeared in the recovered session. Preserve operational purpose, evidence, constraints, and decisions.

A repeated key became a scoped RDP hypothesis

On an intermittent train connection, one intended keypress produced AIIIIIIII.... “Linux input bug” was a plausible first description, but the system logs showed a narrower chain: GRD stayed alive; transport resets and failed reconnects occurred; GDM failed several handovers; and a later successful session coincided with a GLib reference-count assertion. The Fleet note therefore preserves separate fields in prose: observed symptom, Windows-RDP negative control, exact timestamps/logs, current key-up/cleanup hypothesis, and what a controlled reproduction must distinguish. The source chain did not merely support the first claim; it changed its scope.

The review bot was right

A CI review bot suggested a TypeScript constraint that infers an object type while rejecting extra keys, even when ordinary excess-property checking no longer helps:

type Rectangle = { width: number; height: number };
type NoExtraKeys<T, Shape> = Exclude<keyof T, keyof Shape> extends never ? unknown : never;

function draw<T extends Rectangle & NoExtraKeys<T, Rectangle>>(value: T): void {}

draw({ width: 10, height: 20 });
// @ts-expect-error: depth is not part of Rectangle
draw({ width: 10, height: 20, depth: 30 });

Both Sasha and Drinkins rejected T extends ... NoExtraKeys<T, ...> as illegally circular. A minimal compiler probe proved the bot right: TypeScript infers T, then checks the constraint. Our objection came from a real neighboring restriction: TypeScript rejects some immediately circular constraints and recursive conditional types [16], [17]. But this deferred key check has compiled since TypeScript 2.8, the first release that could express it.

Without provenance, consolidation could turn the episode into “we found a cleaner TypeScript pattern.” The code would be right, but the system would learn the wrong lesson: our judgment produced the improvement. The actual chain was: the bot proposed it; both Sasha and Drinkins objected; the compiler settled the question; the accepted design follows the bot. Correct provenance of errors matters because future calibration depends on knowing which source failed and which source supplied the correction.

Provenance template

Provenance template

# Provenance Template

Use only the fields that materially affect interpretation. Provenance is an additional information dimension,
not a mandatory ceremony.

```text
Statement:
Origin: person / AI / code / experiment / document
Epistemic type: report / observation / inference / hypothesis / decision / preference
Scope and conditions:
Date or version:
Primary reference: path + symbol + commit, URL + section, session range, log, or artifact hash
What would invalidate or supersede it:
```

## Example

```text
Statement: Intermittent transport stalls may leave a remote key in repeated state.
Origin: observed during one Linux GRD session; mechanism proposed by the AI
Epistemic type: observation + unverified hypothesis
Scope and conditions: mstsc → system GRD over an unstable train connection
Date or version: 2026-08-21; record exact GRD/FreeRDP versions before publication
Primary reference: GRD journal around 19:40–19:44; Fleet/P620/README.md
Would invalidate: reproduction in a local editor without RDP, or evidence that the client generated repeated
key events
```

PEERS loading rule and artificial directory

Loading and routing rule

Read PEERS.md on demand for attribution, communication, ownership,
expertise, reviewer selection, or deciding whom to involve.
Use it as routing and provenance data, not as authority about a person.
Preserve whether an entry records formal ownership, observed expertise,
a report, a contribution, or a reviewer convention.
Current evidence may supersede it; update PEERS.md when it does.
**Keep a phonebook, not a dossier.** Respect people's privacy.

Artificial PEERS directory

# PEERS — Artificial Example

This example uses generated mock data to respect our real peers' privacy.

- **Rafael White** — rendering engineer. Aliases/accounts: `rafwhite`, `rwhite`,
  `rafael.white@example.invalid`. Owns the desktop compositor integration. Reported intermittent frame pacing
  on build 2041; treat this as Rafael's report until reproduced. Request review on compositor or
  frame-scheduling changes; PR identity may appear as `rwhite`.

- **Ada Gross** — telemetry engineer. Aliases/accounts: `adag`, `ada-gross`, `ada.gross@example.invalid`.
  Expertise: event schemas and correlation identifiers; not the owner of the rendering path. Consult on
  telemetry contract changes; review identity may appear as `adag`.

Bootstrap before optimizing

An elaborate memory architecture is complex; a bootstrap is not. Sasha started from Dany’s working MEMORY prompt, copied it, used it, and revised it until the two systems diverged. The process resembles copying a working Linux installation when no installer exists: the copy provides enough continuity to boot; later use determines what the system becomes.

This post offers the same kind of seed. The embedded prompts are not a finished universal architecture or a sanitized claim to reproduce Drinkins. They are a bootable starting state that readers can copy, operate, criticize, and evolve. An abstract idea and a reviewable running contract have different activation costs.

Without a small continuity mechanism, the assistant repeatedly forgets why a larger knowledge base was designed, which alternatives failed, and what the next experiment should test. It makes no sense to discuss an AI knowledge base with a goldfish. To design an evolving memory system with AI, first give the AI enough memory to continue designing it.

Minimal operating contract

Minimal operating contract

# Minimal Operating Contract — Example

This is a starting prior, not an ideal finished personality. Revise it through real work.

## Roles and authority

The AI investigates, proposes, executes authorized operations, and preserves useful working context. The
engineer owns the purpose, architecture, consequential judgments, external communication, and final artifact.

## Action boundary

- “Investigate,” “review,” or a question → read and explain; do not modify code.
- “Implement,” “fix,” or “do it” → edit and verify; do not commit or publish.
- Commit, push, deployment, publication, destructive actions, credential use, and cross-machine operations
  require explicit current authorization.

## Evidence

Distinguish observation, inference, hypothesis, decision, and preference. When precision matters, return to
code, logs, experiments, or primary documentation. Preserve attribution and scope rather than converting
reports or AI suggestions into facts.

## Persistence

Use JOURNAL for active trajectory and MEMORY for reviewed reusable precedent. Propose prompt candidates in
MEMORY first; promote them only when a stronger artifact buys independent testing, deterministic enforcement,
repeated execution, narrower loading, or shareability.

## Communication

Be direct. Report contradictions and uncertainty. End when the substantive answer ends. Preserve the
engineer's voice in shared prose; propose stylistic changes rather than silently normalizing it.

Selected clauses from our working contract

Purpose before implementation. State what the change is for before optimizing code or tests.

Correctness over speed. If unsure, inspect the file, run the probe, or return to the primary source.

**“I don't know” is sometimes the best answer.** Do not replace missing evidence with a plausible reconstruction.

Investigate means read and explain. Implement means edit and verify. Commit and publication require explicit authority.

Use the actual consumer as the specification. A producer that runs successfully may still achieve nothing.

Exact quotations require exact sources. If verification fails, mark uncertainty rather than completing from memory.

Preserve attribution: Sasha observed; Drinkins proposed; evidence established; we decided.

JOURNAL records what we did. MEMORY records what we agreed should govern future work.

The answer is the ending. Silence follows substance.