Add plexer subsystem, container test infra, and last-resort opencode box backend

- Plexer: always-active terminal multiplexing. NativePlexerController/ TmuxPlexerController share one interface, chosen by which env var is already set (TAI_PLEXER_SOCKET vs TMUX_PANE); NativePlexerBackend is the pty.fork()-based wrapper (raw mode, SIGWINCH resize forwarding, a Unix-socket control protocol, continuous session logging, a Ctrl+A prefix key distinct from tmux's own Ctrl+B). Auto-wraps new interactive shells via a .bashrc hook mirroring the existing command-not-found install pattern, gated on $TMUX/$TAI_PLEXER_ACTIVE/ a $HOME/.tai-no-plexer bypass. New plexer_send/read/type/status tools, env-gated on a detected controller. - tests/container.py + docker-compose.yml + tests/docker/Dockerfile: a disposable podman/docker image for the tests that must never touch a real machine (installing the plexer hook into a real ~/.bashrc, a live tmux session). Required suite (test_seal.py, test_tai.py, tests/plexer.py, tests/bashrc.py) gates the result; tests/rag.py runs as best-effort since its real-LLM dependency can't be satisfied inside a disposable container with no nested engine. - tests/bashrc.py: real end-to-end hook install + bash -i auto-wrap, anti-recursion, tmux-active skip, non-interactive skip, a live TmuxPlexerController test, and an install/uninstall round-trip. - tests/plexer.py: NativePlexerBackend under a real pty, plus a dedicated robustness pass (file permissions, >64KB payload framing, a malformed control request, a genuine self-deadlock fix in the write-to-child path). - tai_test.py: the shared async process-driving framework (pipe/pty transport, group-wide kill-and-reap, a StdinBridge for --interactive) both test files build on. - ChatClient last-resort backend: when there's no local opencode CLI but the sandbox box is already running, install opencode into it (official Node tarball, not apt -- apt's nodejs/npm pull in webpack/babel/jest as transitive deps) and route through it instead of giving up. Only reachable after the first retry round already failed everything else; never creates the box itself. TmuxPlexerController.status() fixed to use `list-panes` instead of `display-message -p`, which silently fell back to the default pane instead of erroring against a dead target. - Fix 4 pre-existing test_tai.py bugs surfaced by running it in a clean environment for the first time: two stale mock signatures (subprocess.run's stdout= kwarg, Chat.complete's deadline= kwarg), one $TMUX-dependent catalog assertion, one tty-dependent color assertion. - research/: a sourced research archive (Source Dossier/Citation Card/Conclusion tiers) backing the above design decisions, with its own audit.py consistency checker. - .gitignore: fix a blanket *.md rule that was about to silently drop the entire research/ archive from version control; add __pycache__/ and the one-off debug transcript this session started from. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-10-10 04:36:05 +02:00
parent f078ab4731
commit 9dbd1fe667
247 changed files with 11187 additions and 26 deletions
@@ -0,0 +1,9 @@
+#!/bin/sh
+# PostToolUse hook, matcher: WebSearch.
+# Guardrail against silently skipping this project's research-archiving rule
+# (AGENTS.md "Research Rule" / research/README.md) — it happened once already,
+# so this fires on every WebSearch call rather than relying on memory.
+# Never blocks (no "decision" field) and does not inspect stdin: the reminder
+# is the same every time, so there is nothing to parse.
+jq -n --arg msg "Research archiving reminder: this WebSearch result must be archived under research/<subject>/ per AGENTS.md's Research Rule before this task is considered done. See research/README.md for the Source Dossier / Source Citation Card format, and research/INDEX.md to check whether an existing subject already covers this topic. There is no \"this one does not count\" exception (research/README.md section 4) -- that exact rationalization is what caused this rule to be skipped once already." \
+  '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'
@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "WebSearch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/research-reminder.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
@@ -9,6 +9,7 @@
 # HTML scratch files
 *.html
 *.md
+!research/**/*.md

 # Backup files
 *.bak
@@ -19,3 +20,12 @@
 # OS artifacts
 .DS_Store
 Thumbs.db
+
+# Integration test run logs (tai_test.py / tests/*.py artifacts)
+tests/logs/
+
+# Python bytecode cache
+__pycache__/
+
+# Stray pasted debug transcripts
+tmux-scrollback-skill-issue.txt
@@ -4,8 +4,14 @@

 - Use plain `import` and `from` statements in Python files.
 - Use the `.py` extension for Python source and test files.
- Keep source and test files at the repository top level.
- Name test files `test_*.py`.
+- Keep source files at the repository top level.
+- There are two kinds of test, in two different places, on purpose — see "Testing" below for the full split. In short: unit tests are top-level `test_*.py`; integration tests are `tests/<topic>.py` (no `test_` prefix) built on `tai_test.py`.
+
+## Testing
+
+**Unit tests**: `test_tai.py`, `test_seal.py`, at the repository top level, named `test_*.py`, `unittest`-based, import `tai.py` as a module directly, no subprocess, fast. `python3 test_tai.py` / `python3 test_seal.py`, or a single test via `python3 -m unittest test_tai.SomeClass.test_method`.
+
+**Integration tests**: `tests/<topic>.py` (e.g. `tests/rag.py`), deliberately *not* named `test_*.py` and *not* at the top level, so the two kinds are never confused. These drive the real `tai.py` binary as a subprocess (one-shot or REPL) and check actual CLI behavior, using `tai_test.py` (the framework, at the repository root) as the one and only base to build on — never a one-off `subprocess`/`asyncio` harness per file. **They must exercise a real LLM call through the real binary — never a mocked model or a database write standing in for what the agent would have done; the resulting flakiness from a free, rotating backend is accepted, not engineered away.** Full conventions, that rule's full rationale, the required isolation rule (always a throwaway `TAI_HOME`), and why verification must check vault state rather than scrape CLI rendering, are in `tests/README.md` — read it before adding a new one. Run with `python3 tests/<topic>.py` (`--filter`, `--interactive`, `--timeout` all supported).

 ## Agent Overview

@@ -73,4 +79,10 @@
 - Keep code maintainable
 - Document decisions
 - Version control changes
- Collaborate effectively
+- Collaborate effectively
+
+## Research Rule
+
+All external research conducted for this project (web searches, reading documentation to settle a design question, competitive/prior-art analysis) is archived under `research/`, maintained under the auspices of the **Molodetz Institute — Research & Retrieval Division**. The full specification — folder layout, the three required document types (Source Dossier, Source Citation Card, Conclusion Document), required metadata, and the quality bar — lives in `research/README.md`; `research/INDEX.md` is the living registry and statistics page. Read `research/README.md` in full before writing into this archive.
+
+The binding rule, in short: **a research task is not done until it is written into `research/`.** Every source actually consulted gets its own document (Tier 1 if read and synthesized, Tier 2 if only seen in a result listing — never skipped, never inflated past what's actually known), every decision the research produced gets its own Conclusion document in that subject's `conclusions/` folder, and `research/INDEX.md` gets updated in the same pass. Check `research/INDEX.md` for an existing subject before opening a new one.
@@ -10,11 +10,20 @@ Nothing here is decorative. Every mechanism below exists because something speci

 ## Requirements

- Python 3.10 or newer, no third-party packages.
+- Python **3.6 or newer** (yes, really — see below), no third-party packages.
+- Any CPU word size. 32-bit is fine. Very well tested, fuck me.
 - Optional: `podman` or `docker` for the sandbox and Telegram voice notes.
 - Optional: `tmux` for terminal content capture and full-history export.
 - Optional: `git` only if you install a skill straight from a git URL — every other skill/install path is pure stdlib.

+### Why 3.6, specifically
+
+There is deliberate, load-bearing Python 3.6 backward compatibility baked into `tai.py`, for a sick situation retoor does not want to talk about. Concretely: `subprocess` calls stick to `universal_newlines` plus explicit `PIPE`s instead of the `text`/`capture_output` kwargs (3.7+ only), and `datetime.fromisoformat` — also 3.7+ — is never called directly; everything routes through a hand-rolled `_fromisoformat()` backport (native when available, a regex-plus-`strptime` fallback when not, `Z`/offset-aware either way). No walrus operator, no `match` statements, no PEP 604 `X | Y` type hints, nowhere in the file — not because nobody thought of it, but because every single one of them would quietly break the 3.6 floor. Don't introduce one.
+
+### Why 32-bit doesn't matter
+
+The whole thing is pure stdlib Python with zero `ctypes`, zero hand-packed `struct` pointer trickery, and zero code that assumes a 64-bit word anywhere. SQLite, `subprocess`, `urllib`, `socket`/`ssl` for the voice protocol — none of it cares about your CPU's register width. If it runs on your architecture's Python at all, it runs correctly, full stop.
+
 ## Quick start

    ./tai.py
@@ -0,0 +1,17 @@
+services:
+  tai-test:
+    build:
+      context: .
+      dockerfile: tests/docker/Dockerfile
+    command: ["python3", "tests/container.py", "--inside"]
+    # No volumes, no network restrictions, no persistence on purpose: this
+    # service exists to run the container-only test suite (see
+    # tests/container.py and tests/bashrc.py) inside a throwaway environment
+    # that it is safe to install a real ~/.bashrc hook into and start a real
+    # tmux session in. `docker compose run --rm tai-test` or
+    # `podman compose run --rm tai-test` both work; tests/container.py
+    # itself drives plain build/run directly (via tai.container_engine(),
+    # the same podman-then-docker detection the project's own sandbox
+    # feature already uses) so the automated path never depends on which
+    # compose implementation, if any, happens to be installed -- this file
+    # is for a human who wants to run the same thing by hand.
@@ -0,0 +1,41 @@
+# Research Archive Index
+
+**Molodetz Institute — Research & Retrieval Division.** This is the living registry of every subject in `research/`. It is updated in the same pass as any new research, per the standing rule in `README.md` §4. Never edit a subject's documents without also updating its row here.
+
+## Global statistics
+
+| Metric | Value |
+|---|---|
+| Subjects | 4 |
+| Total source documents | 225 |
+| — Tier 1 (Source Dossier, independently analyzed) | 84 |
+| — Tier 2 (Source Citation Card, listed only) | 141 |
+| Total conclusion documents | 4 |
+| Archive opened | 2026-10-09 |
+| Last updated | 2026-10-09 |
+
+## Subjects
+
+| Subject | Sources (T1 / T2) | Conclusions | Opened | Last updated | Driving task |
+|---|---|---|---|---|---|
+| [`sqlite-rag-hybrid-search`](sqlite-rag-hybrid-search/) | 32 (10 / 22) | 1 | 2026-10-09 | 2026-10-09 | Designing tmux-log export + chunked retrieval; settled on BM25-only, no vector DB |
+| [`agent-memory-recency-tracking`](agent-memory-recency-tracking/) | 63 (16 / 47) | 1 | 2026-10-09 | 2026-10-09 | Designing an LRU-style last-used/use-count tracker for vault records and chunks |
+| [`async-pty-process-testing`](async-pty-process-testing/) | 59 (20 / 39) | 1 | 2026-10-09 | 2026-10-09 | Designing tai_test.py (pty vs. pipes, non-blocking stdin, process-group cleanup, test-framework shape) — backfilled after it was initially skipped, see activity log |
+| [`shell-multiplexer-auto-attach`](shell-multiplexer-auto-attach/) | 71 (38 / 33) | 1 | 2026-10-09 | 2026-10-09 | Designing a tai-managed terminal multiplexer + bashrc auto-attach: tmux-as-substrate recommendation, interactive-vs-automation shell detection |
+
+## Recent activity log
+
+| Date | Subject | Event |
+|---|---|---|
+| 2026-10-09 | — | Archive created: specification (`README.md`), index (this file), and both subjects above backfilled from the day's research in full, per explicit instruction to retroactively capture every source consulted that day. |
+| 2026-10-09 | `sqlite-rag-hybrid-search` | 32 sources (10 Tier 1 / 22 Tier 2) + 1 conclusion recorded (the conclusion: pure SQLite FTS5/BM25 chunked search, deliberately no embeddings/vector DB — see `conclusions/`). Counts verified directly against the written files, not taken from the authoring agent's self-report. |
+| 2026-10-09 | — | Spec change: `Tier` split into its own standalone metadata row (`1` / `2` / `N/A`) instead of a parenthetical inside `Document type`, so it's directly filterable. All 97 existing documents across both subjects backfilled to match in the same pass; counts re-verified afterward (unchanged: 26 Tier 1, 69 Tier 2, 2 Conclusions). |
+| 2026-10-09 | `agent-memory-recency-tracking` | 63 sources (16 Tier 1 / 47 Tier 2) + 1 conclusion recorded (the conclusion: `last_used`/`use_count` tracking proposal for records and chunks, throttled-write pattern, no eviction policy yet — see `conclusions/`). One source (`glama-code-index-mcp-bm25-hybrid.md`) was promoted from the originally-planned Tier 2 to Tier 1 by the authoring agent mid-task because it contained specific attributable numeric findings — exactly the judgment call §3 of `README.md` calls for, logged here rather than silently absorbed. Counts verified directly against the written files. |
+| 2026-10-09 | `async-pty-process-testing` | New subject, opened as a correction: the eight `WebSearch` calls behind `tai_test.py`'s design (pty vs. pipes, non-blocking stdin, process-group cleanup, test-framework patterns) were initially skipped from the archive under the reasoning "informal engineering reference, not a design decision" — a silent, unilateral exception to the Research Rule, and wrong (see `README.md` §4's added "no exception, ever" paragraph). Backfilled: 59 sources (20 Tier 1 / 39 Tier 2) + 1 conclusion (`conclusions/tai-test-framework-design.md`). Counts verified directly against the written files via `research/audit.py`, not taken from the authoring agent's self-report alone. A `PostToolUse`/`WebSearch` hook (`.claude/settings.json`) was also added the same day specifically to stop this from recurring. |
+| 2026-10-09 | `shell-multiplexer-auto-attach` | 71 sources (38 Tier 1 / 33 Tier 2) + 1 conclusion recorded (the conclusion: build on tmux as a substrate rather than a from-scratch multiplexer; reliable human-vs-automation shell detection has no single solution, only a combination of weaker signals plus a safety-file escape hatch). Counts verified directly against the written files via `research/audit.py`. Hook fired correctly for all 8 underlying WebSearch calls during this task. |
+
+## How to use this index
+
+- Before starting new research, search this table for an existing subject before opening a new one (see `README.md` §2, "one subject, one home").
+- Every subject folder is self-contained: its sources live flat inside it, its conclusions live in its `conclusions/` subfolder.
+- Tier 1 vs Tier 2 is a statement about how deeply a source was actually read, not about its importance — see `README.md` §3 for the exact distinction.
@@ -0,0 +1,205 @@
+# The tai Research Archive
+
+**Maintained under the auspices of the Molodetz Institute — Research & Retrieval Division.**
+
+This directory is a permanent, append-only archive of every piece of external research conducted in support of the `tai` project. It is not a scratch pad. It is not a cache. Once a document lands here it is never deleted and never silently rewritten — it is corrected forward, with a changelog entry, the way a real research institute corrects the record.
+
+This file is the specification. Every document under `research/` must conform to it exactly. If a future research session cannot make a source or a conclusion fit this specification, the specification gets amended first (with a changelog entry below), and only then does the document get written — the rule is never quietly bent for one entry.
+
+## 1. Why this exists
+
+Research happens, gets used for one decision, and then evaporates — the next person (or the next session of the same agent) re-derives it from scratch or, worse, never finds out it was already settled. This archive exists so that:
+
+- every external claim this project's design relies on has a traceable source, a date, and an honest confidence level;
+- a conclusion (a decision actually made because of research) is recorded separately from the raw source material that informed it, so "what we found" and "what we decided" never get smeared into one document that's impossible to audit later;
+- the next person — human or model — can answer "have we already looked into this?" by reading an index instead of repeating a web search.
+
+## 2. Directory layout
+
+```
+research/
+  README.md                         <- this specification (the only file allowed at the root besides INDEX.md)
+  INDEX.md                          <- the living registry of every subject, every document, and archive-wide statistics
+  <subject-slug>/
+    <source-slug>.md                <- one file per external source consulted for this subject
+    conclusions/
+      <conclusion-slug>.md          <- one file per distinct conclusion/decision drawn from this subject's sources
+```
+
+**Subject** is a research topic, not a single query — "sqlite-rag-hybrid-search" or "agent-memory-recency-tracking", not "search query #4". A new research task that is clearly a continuation of an existing subject adds documents into that subject's existing folder; it does not fork a near-duplicate subject. When genuinely unsure whether something is a new subject or a continuation, prefer the existing subject — subject sprawl is a worse failure mode than a slightly-too-broad subject.
+
+**Slugs** are lowercase, hyphen-separated, ASCII, no stop words beyond what's needed for uniqueness, derived from the source's domain plus a short topic fragment (e.g. `mem0-introducing-memory-decay.md`, `arxiv-2310-08560-memgpt.md` for a numbered arXiv paper — the arXiv id goes in the slug verbatim, hyphenated, because it's the only stable identifier a paper has). Two different pages on the same domain get distinguishing fragments, never `-2`, `-3` suffixes — a suffix number tells a future reader nothing about what's inside the file.
+
+## 3. The three document types
+
+There are exactly three kinds of document in this archive. Nothing else is permitted at the file level; a new need gets solved by extending one of these three, with a changelog entry here, not by inventing a fourth ad hoc.
+
+### 3.1 Source Dossier (Tier 1 — independently analyzed)
+
+Used when the source was actually read and synthesized in enough depth to state real findings, pros, cons, and a relevance judgment. This is the default, full-weight document. Required sections, in this exact order:
+
+```markdown
+# <Source Title>
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | <subject-slug> |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | <as published> |
+| Source URL | <full URL> |
+| Source publisher / author | <org or person, or "Unknown — not stated"> |
+| Source type | <paper \| blog post \| vendor docs \| forum thread \| repository \| patent \| standard \| other> |
+| Source date (published) | <YYYY-MM-DD, or "Unknown — not stated"> |
+| Date researched | <YYYY-MM-DD> |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | <web search synthesis \| direct page fetch \| both> |
+| Confidence | <High \| Medium \| Low> |
+| Status | <Active \| Superseded \| Disputed> |
+
+## Summary
+
+Two to five sentences. What does this source actually claim. No hedging filler — if the source is thin, the summary says so plainly rather than padding it.
+
+## Key findings
+
+Bullet list of concrete, attributable claims. Each bullet should be something a reader could independently go verify against the source.
+
+## Pros / strengths
+
+What this source gets right, or what makes it a good argument for its position.
+
+## Cons / limitations / caveats
+
+What's missing, unproven, vendor-biased, outdated, or contradicted elsewhere. A Tier 1 dossier with an empty cons section is a red flag that it wasn't read critically — write "none identified, see confidence rating" explicitly if that's genuinely the case, rather than leaving the section out.
+
+## Relevance to tai
+
+Why this mattered to the actual engineering decision at hand. A source can be excellent and still irrelevant; say so if that's the case.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| <YYYY-MM-DD> | Initial dossier created. |
+```
+
+### 3.2 Source Citation Card (Tier 2 — listed, not independently analyzed)
+
+Used for a source that turned up during research (a search result, a related link) but was **not** independently read in enough depth to responsibly claim pros, cons, or specific findings. This tier exists specifically so volume of sources consulted is never achieved by quietly inflating what's actually known about each one — it is better, and more professional, to log a source honestly as "seen, not analyzed" than to fabricate a dossier for it. Required sections:
+
+```markdown
+# <Source Title>
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | <subject-slug> |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | <as published, or as listed by the search aggregator> |
+| Source URL | <full URL> |
+| Source type | <best guess from URL/title> |
+| Date researched | <YYYY-MM-DD> |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+One or two sentences: what search surfaced it, and why it looked potentially relevant to the subject.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| <YYYY-MM-DD> | Logged as consulted-but-not-analyzed. |
+```
+
+A Tier 2 card may later be promoted to a Tier 1 dossier if someone actually reads the source in depth — promotion means rewriting the file to the Tier 1 template and adding a changelog line noting the promotion and its date, never duplicating it as a second file.
+
+### 3.3 Conclusion Document
+
+A conclusion is a decision or a standing judgment the project actually made *because of* research — never just a restatement of one source. It lives in `<subject-slug>/conclusions/` and is written only once the underlying research is done. Required sections:
+
+```markdown
+# Conclusion: <Title>
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | <subject-slug> |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | <YYYY-MM-DD> |
+| Decided by | retoor, advised by tai (agent, Claude Sonnet 5) |
+| Status | <Active \| Superseded by <link> \| Reverted> |
+| Confidence | <High \| Medium \| Low> |
+
+## Question / problem statement
+
+What question was this research actually trying to answer. One paragraph, no padding.
+
+## Conclusion
+
+The actual decision or standing judgment, stated as a plain declarative claim a reader could act on without reading anything else.
+
+## Supporting sources
+
+Linked list of the Tier 1 dossiers (and, where genuinely load-bearing, Tier 2 cards) in this subject that back this conclusion, each with a one-line note on what it contributed.
+
+## Alternatives considered and rejected
+
+What else was on the table, and the specific reason each alternative lost. "We didn't think of it" is a valid entry if true; inventing a more flattering rejection reason is not.
+
+## Risks / open questions
+
+What could make this conclusion wrong later, and what would have to change for it to be revisited.
+
+## Action taken
+
+What actually happened as a result (a feature shipped, a design rule adopted, a decision deferred on purpose). If nothing was built yet, say so explicitly — a conclusion is allowed to be "we now know what to do, we have not done it yet."
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| <YYYY-MM-DD> | Initial conclusion recorded. |
+```
+
+## 4. The standing rule (also stated in `AGENTS.md`)
+
+**Every time research is conducted for this project — a web search, a round of searches, reading documentation to settle a design question — it is written into this archive before the research is considered "done," not as an afterthought.** Concretely, every research task produces:
+
+1. a subject folder (new, or an existing one reused);
+2. one document per source actually consulted, Tier 1 if it was read and synthesized, Tier 2 if it was only seen in a result listing — no source gets skipped just because it turned out to be low-value; a low-value source is itself a finding, recorded honestly;
+3. a conclusion document for every decision the research actually produced, if any was reached;
+4. an updated `INDEX.md` — the subject's row, the global counts, and the "Recent activity" log all get updated in the same pass, never left for later.
+
+A research task that produces no written archive entries did not happen, as far as this project is concerned — if it isn't here, it gets redone and re-verified the next time someone needs it, which is the exact waste this archive exists to prevent.
+
+**There is no "this one doesn't really count" exception, ever.** This rule was broken once already — the research behind `tai_test.py` (eight `WebSearch` calls on pty/asyncio/process-testing patterns) was skipped on the judgment that it was "informal engineering reference, not a design decision," a call made silently and alone, never surfaced to anyone, and wrong. "It's just engineering," "it's too minor," "I'll remember to do it after I finish the actual task" are exactly the thoughts that preceded that miss, not reasons it was fine. If a research task feels like an exception, that is the signal to archive it anyway, not a reason to skip it — and if there's ever real ambiguity about whether something should be archived, that ambiguity gets stated out loud (to the user, or as a visible note in the response) instead of resolved unilaterally and invisibly. A decision nobody can see is a decision nobody can catch.
+
+## 5. Quality bar
+
+- **No fabricated specifics.** A Tier 1 dossier's "Key findings" must be things actually said by the source, not plausible-sounding inferences dressed up as findings. When synthesis, not direct reading, is the basis for a claim (e.g. a web-search tool's own summary of a page), that's still fine for Tier 1 as long as it's a faithful restatement — it only drops to Tier 2 when there isn't enough independent content to responsibly summarize at all.
+- **Confidence ratings are honest, not reassuring.** "Low" confidence on a real finding is more useful to a future reader than "High" confidence dressed up to look thorough.
+- **Dates are never guessed silently.** "Unknown — not stated" is a correct value for a metadata field; a made-up date is not.
+- **Corrections are forward, not silent edits.** If a later research pass finds a dossier was wrong, the file gets updated and the changelog gets a new row explaining what changed and why — the old claim doesn't just vanish from history.
+- **One subject, one home.** Before creating a new subject folder, check `INDEX.md` for an existing one that already covers the topic.
+- **`Tier` is its own metadata field, not text buried in `Document type`.** Every document's metadata table has a standalone `Tier` row (`1`, `2`, or `N/A` for a Conclusion) precisely so tier can be greped/filtered on directly — `grep "^| Tier | 1 |"` — instead of matching a parenthetical inside a longer string. `Document type` states only the document kind (`Source Dossier`, `Source Citation Card`, `Conclusion`); it never repeats the tier.
+
+## 6. Changelog (of this specification itself)
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial specification written, alongside the first two subjects (`sqlite-rag-hybrid-search`, `agent-memory-recency-tracking`) backfilled from the same day's research. |
+| 2026-10-09 | Split `Tier` out into its own metadata field (`1` / `2` / `N/A`) instead of a parenthetical inside `Document type`, so it can be filtered on directly. All existing documents backfilled to match in the same pass. |
@@ -0,0 +1,28 @@
+# Performance of Date-Only vs Date-Time Indexes (forum thread)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Performance of Date-Only vs Date-Time Indexes |
+| Source URL | https://www.access-programmers.co.uk/forums/goto/post?id=1120144 |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "SQLite last_accessed column unix timestamp vs datetime performance indexing"; an MS Access-focused forum discussion on date-index performance, tangential to SQLite specifically but conceptually adjacent. Not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,52 @@
+# 2Q Cache Management Algorithm
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | 2Q Cache Management Algorithm |
+| Source URL | https://arpit.substack.com/p/2q-cache-management-algorithm |
+| Source publisher / author | Arpit (Substack newsletter), explaining Johnson & Shasha's 1994 VLDB paper |
+| Source type | blog post (explainer of a primary paper) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+An accessible explainer of Johnson & Shasha's 1994 "2Q" buffer-replacement algorithm — a constant-overhead, no-tuning alternative to full LRU that influenced real database buffer-pool design, most notably PostgreSQL's.
+
+## Key findings
+
+- 2Q answers whether a constant-overhead-per-access scheme can match LRU/2 page-replacement performance; the 1994 paper's answer is yes, with no tuning required.
+- The design splits the buffer into three structures: a main LRU queue for confirmed-hot pages, a first-in (probationary) queue for newly-seen pages, and a ghost queue that stores only the identifiers of recently-evicted pages (not their data).
+- A page enters the probationary queue on first access; if it's re-referenced while still represented in the ghost queue, it gets promoted into the main queue.
+- This design is specifically scan-resistant: a one-time sequential scan fills and drains the probationary queue without ever polluting the main hot-page queue.
+- Per the source, 2Q's simplicity and effectiveness influenced PostgreSQL's own buffer-management design.
+
+## Pros / strengths
+
+- O(1), constant-overhead-per-access, no tuning parameters — directly addresses the "speed is important" constraint behind this entire research task, as a possible template if tai ever needs a real eviction policy rather than just tracking.
+- Real production lineage (PostgreSQL) gives confidence this isn't just an academic curiosity.
+
+## Cons / limitations / caveats
+
+- 2Q's own main-LRU-queue component is itself expensive to make concurrent under high contention — this is exactly the weakness that `arxiv-2511-21958-clock2q-plus.md` (Clock2Q+) sets out to fix by replacing that component with a CLOCK-style structure.
+- 2Q is an eviction-policy design for buffer pools; tai is not (yet) building eviction at all, only tracking — so 2Q is background context for a possible future phase, not something applicable today.
+
+## Relevance to tai
+
+Background/comparative context only for this research pass — explicitly not part of the current proposal (which is tracking-only, no eviction), but recorded here so a future eviction-policy decision doesn't have to rediscover 2Q as a candidate from scratch.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,53 @@
+# Generative Agents: Interactive Simulacra of Human Behavior
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Generative Agents: Interactive Simulacra of Human Behavior |
+| Source URL | https://arxiv.org/pdf/2304.03442 |
+| Source publisher / author | Park, Joon Sung et al. (Stanford / Google), 2023 |
+| Source type | paper |
+| Source date (published) | 2023-04-07 (arXiv submission) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+This is the original "generative agents" paper that introduced a retrieval-scoring scheme for agent memory combining recency, importance, and relevance into a single retrieval score. It is the foundational reference almost every later agent-memory system (MemGPT, Letta, Mem0, and the smaller forgetting-curve projects) cites or reacts against.
+
+## Key findings
+
+- Recency is modeled as an exponential decay over time since a memory was *last retrieved* (not last created), with a decay factor of 0.995 per sandbox game hour.
+- Importance is an LLM-assigned integer score (1–10 "poignancy" scale) — the paper found that simply asking the model to output an integer score worked well in practice.
+- Relevance is cosine similarity between embedding vectors of the memory text and the current situation's text.
+- The three signals are combined into one retrieval score; sources disagree on the exact combination — some report equal weighting after normalization, others note the released implementation simply uses a weight of 1 for all three.
+- The paper separately introduces "reflection": higher-level, more abstract thoughts generated by the agent, which are themselves injected back into the memory stream and participate in retrieval.
+
+## Pros / strengths
+
+- Recency, importance, and relevance are kept as three independent signals combined only at retrieval time, not pre-collapsed into one opaque score at write time — this is a reusable design principle independent of the specific decay constant chosen.
+- The scheme is simple enough to reimplement and has become the de facto reference point for the whole field, which makes it a useful common vocabulary even where tai's design diverges from it.
+
+## Cons / limitations / caveats
+
+- The importance score depends on an LLM call per memory, which is a real cost this paper does not need to justify for its own research-simulation use case, but which matters for a production system.
+- The exact weighting of the three signals is not consistently reported across secondary sources — the dossier author was not able to confirm the canonical weights straight from the paper text, only from secondary synthesis of it, so treat exact weight numbers as uncertain pending a direct read of the paper's equations.
+- Decay is calibrated to "sandbox game hours" in a simulated environment; the constant (0.995/hour) is not inherently meaningful for tai's real-wall-clock vault usage and would need its own calibration if ever adopted.
+
+## Relevance to tai
+
+This is the primary precedent for keeping recency as an independent, un-collapsed signal rather than baking a final blended score into storage — directly informing the recommendation in this subject's conclusion to store `last_used` and `use_count` as raw signals rather than a single derived priority number.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,51 @@
+# MemGPT: Towards LLMs as Operating Systems
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | MemGPT: Towards LLMs as Operating Systems |
+| Source URL | https://arxiv.org/pdf/2310.08560 |
+| Source publisher / author | Packer, Charles et al., 2023 |
+| Source type | paper |
+| Source date (published) | 2023-10-12 (arXiv submission) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+MemGPT proposes an OS-inspired memory architecture for LLM agents: a bounded in-context "main context" and an external, larger "archival"/"recall" storage, with a queue manager handling overflow. Important for this subject because it is the most commonly cited "LRU-ish" agent memory architecture, and it turns out its actual eviction policy is FIFO, not LRU.
+
+## Key findings
+
+- Eviction policy is queue-based and FIFO, not recency-based: a queue manager controls context overflow via a queue eviction policy.
+- Before an eviction actually happens, the queue manager inserts a system message warning the LLM that eviction is imminent, so the model can proactively save important content to working context or to archival storage first — the eviction decision point is made visible to the model, not hidden.
+- One implementation pattern described in newer benchmark work pairs a bounded main-context FIFO with a FAISS-backed archival recall store — i.e. a vector index sits behind the FIFO-managed front end.
+- Overflow handling in some descriptions is characterized as a "swap": evict, recursively summarize, and store into recall storage, triggered at a fraction of fast-context capacity.
+
+## Pros / strengths
+
+- Makes the overflow/eviction moment an explicit, LLM-visible event rather than a silent background process — directly useful precedent for "don't silently throw memory away."
+- The tiering concept (fast/bounded vs. slow/large) maps cleanly onto database buffer-pool thinking, which is where this subject's CLOCK/2Q research (see `arpit-2q-cache-algorithm.md`, `arxiv-2511-21958-clock2q-plus.md`) becomes relevant as a possible future eviction mechanism if tai ever needs one.
+
+## Cons / limitations / caveats
+
+- FIFO is a simpler policy than LRU and explicitly does not use access recency to decide what gets evicted — so despite being the paper most people reach for when discussing "agent memory eviction," it is not actually a precedent for LRU-style tracking, only for tiered memory in general.
+- The paper predates, and is architecturally distinct from, the current Letta product (see `letta-agent-memory-blog.md`), which has evolved considerably since; details attributed to "MemGPT" in secondary sources sometimes actually describe current Letta behavior instead.
+
+## Relevance to tai
+
+Confirms that even the most prominent "OS-for-LLMs" memory paper does not use LRU for eviction — reinforcing that tai's proposed `last_used`/`use_count` tracking is building a *new* capability for this project, not replicating an established pattern that already has a known-good eviction policy to copy. tai's conclusion deliberately defers the eviction-policy question rather than assuming FIFO or LRU is obviously correct.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,46 @@
+# Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Mem0: Building Production-Ready AI Agents with Scalable Long-Term Memory |
+| Source URL | https://arxiv.org/pdf/2504.19413 |
+| Source publisher / author | Mem0 team (official paper) |
+| Source type | paper |
+| Source date (published) | 2025 (per arXiv id range; exact date unstated in material reviewed) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+The official research paper underlying the Mem0 product, describing its production long-term-memory architecture. This research pass surfaced it mainly as the primary-source counterpart to the Mem0 vendor blog posts (`mem0-introducing-memory-decay.md`, `mem0-memory-eviction-forgetting.md`), rather than extracting independent technical detail from it directly.
+
+## Key findings
+
+- Establishes Mem0 as a scalable long-term-memory layer intended for production agent deployments, which is the context the decay/eviction features documented in the companion blog-post dossiers were built for.
+
+## Pros / strengths
+
+- Being a peer-reviewable paper rather than pure marketing copy, it is a stronger source of record for Mem0's architecture than the blog posts alone, even though this specific research pass did not extract line-level technical detail from it.
+
+## Cons / limitations / caveats
+
+- This research pass's synthesis of this specific paper was thin relative to the blog-post dossiers — the search results centered discussion on the blog posts, not the paper's own equations or benchmarks. A future pass that reads the paper directly should promote or supplement this dossier with the paper's actual decay/scoring formulas if they are more precisely specified there than in the blog posts.
+
+## Relevance to tai
+
+Primary-source backing for the Mem0 precedent cited throughout this subject's conclusion; included at Tier 1 rather than Tier 2 because it is the official paper behind a directly relevant product, even though the specific numeric formulas could not be independently confirmed from it in this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# GATSim: Urban Mobility Simulation with Generative Agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | GATSim: Urban Mobility Simulation with Generative Agents |
+| Source URL | https://arxiv.org/pdf/2506.23306 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper" as an applied follow-up using the generative-agents memory architecture for urban mobility simulation; not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Modeling realistic human behavior using generative agents in a multimodal transport system: Software architecture and Application to Toulouse
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Modeling realistic human behavior using generative agents in a multimodal transport system: Software architecture and Application to Toulouse |
+| Source URL | https://arxiv.org/pdf/2510.19497 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper" as another applied generative-agents simulation (transport modeling in Toulouse); not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,50 @@
+# Clock2Q+: A Simple and Efficient Replacement Algorithm for Metadata Cache in VMware vSAN
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Clock2Q+: A Simple and Efficient Replacement Algorithm for Metadata Cache in VMware vSAN |
+| Source URL | https://arxiv.org/pdf/2511.21958 |
+| Source publisher / author | VMware vSAN team (per title context), 2025 |
+| Source type | paper |
+| Source date (published) | 2025 (per arXiv id; exact date unstated in material reviewed) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+A 2025 paper proposing Clock2Q+, which keeps 2Q's three-queue structure but replaces its expensive main LRU queue with a CLOCK-style reference-bit structure, directly targeting the concurrency/overhead weakness of classic 2Q — and the single strongest primary-source explanation found in this research pass for *why* CLOCK-style tracking is cheap.
+
+## Key findings
+
+- 2Q's main LRU queue has high CPU and memory overhead and is hard to make concurrent, per the paper's own stated motivation.
+- Clock2Q+ replaces that main structure with a CLOCK-style structure: on a hit, the algorithm only sets a reference bit, with no list mutation and no lock-protected reordering on the hot path.
+- The paper also argues the classic design choice (allocating 25% of the cache to the small/probationary FIFO queue, a figure from 1994) is outdated now that caches are far larger than they were 30 years ago, and that shrinking it frees more room for the main structure.
+- Adds a "correlation window" to filter burst-correlated metadata hits, intended to prevent cache pollution while still promoting genuinely hot blocks.
+
+## Pros / strengths
+
+- This is the clearest, most directly-stated primary-source explanation in this entire subject for the general principle behind low-write-overhead recency tracking: a hit only flips a bit instead of mutating a data structure. This principle, not the specific vSAN metadata-cache application, is what's actually relevant to tai.
+- Being a 2025 paper, it's a current, non-dated reference for this specific design pattern.
+
+## Cons / limitations / caveats
+
+- The paper's actual subject is a VMware vSAN metadata cache, a very different workload (block-storage metadata, extremely high access rates) from tai's vault (a local SQLite file with comparatively low concurrent access). The specific tuning (correlation windows, FIFO queue sizing) does not transfer; only the general "reference bit instead of list mutation" principle does.
+
+## Relevance to tai
+
+The clearest primary-source justification, among everything found in this subject, for *why* the throttled/conditional-UPDATE pattern recommended in this subject's conclusion is the right shape of optimization (minimize writes on the hot read path) even though tai's proposal uses a timestamp column and a conditional SQL UPDATE rather than a literal CLOCK reference bit — the underlying principle (don't mutate proportional to every access) is the same one being applied.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,49 @@
+# Evolution of Buffer Management in Database Systems: From Classical Algorithms to Machine Learning and Disaggregated Memory
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Evolution of Buffer Management in Database Systems: From Classical Algorithms to Machine Learning and Disaggregated Memory |
+| Source URL | https://arxiv.org/pdf/2512.22995 |
+| Source publisher / author | Unknown authors (per material reviewed) |
+| Source type | paper (survey) |
+| Source date (published) | 2025 (per arXiv id; exact date unstated in material reviewed) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A 2025 survey of database buffer-management algorithms spanning classical approaches through ML-based and disaggregated-memory techniques. This research pass drew one specific comparative point from it: its coverage of LIRS and its comparison-table characterization of 2Q.
+
+## Key findings
+
+- Describes LIRS (Low Inter-reference Recency Set) as ranking pages by *inter-reference recency* — the gap between successive accesses — rather than by plain recency (time since last access alone).
+- Its comparison table characterizes 2Q as scan-resistant with O(1) complexity, corroborating the `arpit-2q-cache-algorithm.md` dossier from an independent, more academic source.
+
+## Pros / strengths
+
+- As a survey, it situates 2Q and CLOCK-family algorithms within the broader, still-evolving landscape of buffer management (including newer ML-based and disaggregated-memory approaches), which is useful context even though those newer approaches are well beyond anything tai would need.
+- Independent corroboration of 2Q's O(1)/scan-resistant characterization strengthens confidence in that specific claim.
+
+## Cons / limitations / caveats
+
+- This research pass did not extract detail on the survey's ML-based or disaggregated-memory sections — only the classical-algorithms comparison was actually used, so claims about those newer sections cannot responsibly be made from this dossier.
+- LIRS itself (inter-reference recency) is noted but not explored further in this pass — flagged here as a candidate for deeper investigation only if tai ever gets to a real eviction-policy design phase.
+
+## Relevance to tai
+
+Secondary corroboration for the 2Q/CLOCK-family background research; not independently load-bearing for the subject's conclusion, which does not require (or recommend) adopting any specific eviction algorithm yet.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Toward Efficient Agents: Memory, Tool learning, and Planning
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Toward Efficient Agents: Memory, Tool learning, and Planning |
+| Source URL | https://arxiv.org/pdf/2601.14192 |
+| Source type | paper (survey) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper"; a broad survey covering memory among other agent-efficiency topics, not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Crystal-KV: Efficient KV Cache Management for Chain-of-Thought LLMs via Answer-First Principle
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Crystal-KV: Efficient KV Cache Management for Chain-of-Thought LLMs via Answer-First Principle |
+| Source URL | https://arxiv.org/pdf/2601.16986 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LRFU combined recency frequency cache replacement formula least recently frequently used"; the research synthesis noted that newer work applies the LRFU "combined recency and frequency" scoring idea to LLM inference KV-cache management specifically (scoring cache entries by a sum of lambda^(t-t_j) over past hit times) — this paper is the likely source of that specific application, though it was not independently opened to confirm the exact formula variant used.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Entity-Collision: A Stratified Protocol for Attributing Retrieval Lift in Agent Memory
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Entity-Collision: A Stratified Protocol for Attributing Retrieval Lift in Agent Memory |
+| Source URL | https://arxiv.org/pdf/2605.29630 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management"; not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Learning What to Remember: A Cognitively Grounded Multi-Factor Value Model for Agentic Memory
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Learning What to Remember: A Cognitively Grounded Multi-Factor Value Model for Agentic Memory |
+| Source URL | https://arxiv.org/pdf/2606.12945 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper"; title suggests direct relevance to multi-factor memory value scoring (recency+frequency+importance style), a plausible candidate for deeper reading in a future research pass, but not opened or quoted during this one.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Beyond Memory Leaderboards: Evaluating Scientific Memory as Budgeted Context Restoration
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Beyond Memory Leaderboards: Evaluating Scientific Memory as Budgeted Context Restoration |
+| Source URL | https://arxiv.org/pdf/2607.16848 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper" as a related follow-up paper on evaluating agent memory systems; not opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Agentic Context Management: Solving Agent Memory and Cost by Treating Them as Lifecycle and Architecture Problems
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Agentic Context Management: Solving Agent Memory and Cost by Treating Them as Lifecycle and Architecture Problems |
+| Source URL | https://arxiv.org/pdf/2607.21503 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management"; title suggests direct relevance to lifecycle-based memory management, a plausible candidate for deeper reading in a future research pass, but not opened or quoted during this one.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# AgentMemBench: A Systematic Benchmark for Evaluating Long-Term Memory Management Strategies in Conversational AI Agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | AgentMemBench: A Systematic Benchmark for Evaluating Long-Term Memory Management Strategies in Conversational AI Agents |
+| Source URL | https://arxiv.org/pdf/2608.00009 |
+| Source type | paper (benchmark) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management"; the search synthesis noted this benchmark's MemGPT-style adapter uses "a bounded main-context FIFO + FAISS archival recall" — a useful implementation detail — but the dossier for this card was not independently expanded beyond that single attributed detail, which is recorded instead in `arxiv-2310-08560-memgpt.md`'s Tier 1 dossier.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Measure Before You Manage: Evaluating Agent Working Memory in Coding Agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Measure Before You Manage: Evaluating Agent Working Memory in Coding Agents |
+| Source URL | https://arxiv.org/pdf/2608.31057 |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper"; relevant to coding-agent working memory specifically, which overlaps with tai's own domain (a coding agent), but not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# An Improved Adaptive Policy Based on Recency and Frequency (Atlantis Press)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | An Improved Adaptive Policy Based on Recency and Frequency |
+| Source URL | https://www.atlantis-press.com/article/21835.pdf |
+| Source type | paper (conference proceedings, AMEII 2015) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LRFU combined recency frequency cache replacement formula least recently frequently used"; per the search synthesis, this 2015 paper proposes an adaptive variant of LRFU that lets the recency/frequency tradeoff parameter (lambda) adjust dynamically rather than staying fixed, addressing the main criticism of classic LRFU. A second, related paper from the same Atlantis Press proceedings (`https://www.atlantis-press.com/article/21834.pdf`) also surfaced and is treated as the same source family, logged under this one card.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# bm25 (BlackGlory's digital garden — SQLite FTS5 auxiliary function note)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | bm25 (auxiliary function note) |
+| Source URL | https://blackglory.me/notes/sqlite/SQLite3/FTS_Full-Text_Search/FTS5/Querying/Auxiliary_Functions/bm25?variant=en |
+| Source type | other (personal notes/digital garden) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "boost BM25 FTS5 search ranking by recency last accessed hybrid scoring formula" as personal notes on FTS5's `bm25()` auxiliary function; closely related to the sign-convention point recorded at Tier 1 in `sqlite-org-bm25-sign-flip-commit.md`, but this specific note page was not independently opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# lang_datefunc (chiark.greenend.org.uk mirror of SQLite docs)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | lang_datefunc |
+| Source URL | https://www.chiark.greenend.org.uk/doc/sqlite3/lang_datefunc.html |
+| Source type | vendor docs (third-party documentation mirror) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "SQLite last_accessed column unix timestamp vs datetime performance indexing" as a mirror of SQLite's official date-function documentation. Its specific technical point — that an INTEGER value needs the `'unixepoch'` modifier or SQLite's date functions will misread it as a Julian day number — is recorded directly in the `sqlite-forum-timestamp-integer-vs-text.md` Tier 1 dossier, sourced from the broader search synthesis rather than an independent read of this specific mirror page. A second mirror of the same documentation (sao.ru) also surfaced and is treated as the same underlying source.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# SQLite date and time (Coddy.tech docs mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | date and time |
+| Source URL | https://coddy.tech/docs/de/sqlite/date-and-time |
+| Source type | vendor docs (third-party documentation mirror) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "SQLite last_accessed column unix timestamp vs datetime performance indexing"; its content (TEXT/REAL/INTEGER as the three date/time storage representations) is corroborated directly in the `sqlite-forum-timestamp-integer-vs-text.md` Tier 1 dossier, but this specific mirror page was not independently opened. A near-identical English-language and Japanese-language mirror of the same documentation also surfaced elsewhere in this subject's research and is treated as the same underlying source.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Papers We Love — caching archive mirror (code.garrettmills.dev)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Papers We Love — caching directory (git archive mirror) |
+| Source URL | https://code.garrettmills.dev/Archives/papers-we-love_papers-we-love/src/commit/23fff13692fb378bcac40e9ace7b7c1b0ec9f83d/caching |
+| Source type | repository (git mirror) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "approximate LRU algorithm CLOCK 2Q low write overhead cache eviction database" as a mirrored git archive of the Papers We Love caching-papers directory. A second, near-identical commit of the same mirror also surfaced in the same result set and is treated as the same source, not filed separately.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,61 @@
+# Conclusion: Last-Used / Use-Count Tracking Proposal for the tai Vault
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-09 |
+| Decided by | retoor, advised by tai (agent, Claude Sonnet 5) |
+| Status | Active (proposal recorded, not yet implemented) |
+| Confidence | Medium |
+
+## Question / problem statement
+
+retoor asked for a way to track when a vault record (and, by extension, a chunk) was last used, or was recently part of a search result, with an eye toward a future LRU-style prioritization or faster-access mechanism. The explicit instruction was to research this thoroughly first — specifically looking at how agent-memory systems already do this, and at systems/database techniques for doing it cheaply — and to produce a concrete proposal, with building anything explicitly forbidden for this task.
+
+## Conclusion
+
+The recommended design (not yet built) is:
+
+- Add a `last_used INTEGER` column (Unix epoch seconds) to both the `records` and `chunks` tables. This is a deliberate exception to the vault's otherwise-universal ISO-8601 TEXT timestamp convention, justified specifically because this column is compared, sorted, and range-scanned on a hot path in a way the vault's other timestamp columns are not.
+- Add a `use_count INTEGER` column to `chunks`. `records` already has an existing `reads` counter that serves the same purpose, so no duplicate column is needed there.
+- "Used" is triggered by two kinds of event: (a) an explicit `record_read`/`get_record` call, and (b) a record or chunk appearing in `search` results — a chunk hit should also propagate an update to its parent record's `last_used`, since the parent is "the record" in retoor's own framing of the request.
+- Writes must be throttled/conditional, never unconditional on every hit: `UPDATE ... SET last_used = ? WHERE last_used IS NULL OR last_used < ?` with a coalescing window (a starting estimate of roughly one minute), modeled directly on Linux's `relatime` mount option and the real, documented GitLab `last_downloaded_at` production incident.
+- No eviction policy and no search-ranking integration is being built in this phase. This is tracking-substrate only — recording the raw signal so a future, separate decision can use it, matching how both the Generative Agents paper and Mem0's product keep recency as an independent signal rather than baking a final blended formula in at write time.
+
+## Supporting sources
+
+- `arxiv-2304-03442-generative-agents.md` (Tier 1) — the foundational precedent for keeping recency, importance, and relevance as three independent, un-collapsed signals combined only at retrieval time.
+- `arxiv-2310-08560-memgpt.md`, `letta-agent-memory-blog.md` (Tier 1) — establish that even the most prominent "OS-for-LLMs" memory architecture uses FIFO eviction, not LRU, and keeps ranking (recency-aware) separate from eviction/compaction — informing the decision to defer eviction entirely rather than assume a policy.
+- `mem0-introducing-memory-decay.md`, `mem0-memory-eviction-forgetting.md`, `arxiv-2504-19413-mem0-paper.md` (Tier 1) — the closest existing commercial precedent: recency as a soft search-time re-ranking multiplier, not a deletion trigger; and an explicit distinction between decay (ranking), TTL (lifecycle), and deletion APIs (user-visible forgetting) that this proposal deliberately mirrors by staying purely in the "raw signal" category.
+- `arpit-2q-cache-algorithm.md`, `arxiv-2511-21958-clock2q-plus.md`, `arxiv-2512-22995-buffer-management-survey.md` (Tier 1) — background precedent for low-write-overhead recency tracking (2Q, CLOCK), recorded for a *possible future* eviction-policy phase, not used directly in the current tracking-only proposal.
+- `redhat-relatime-drive-access.md`, `gitlab-last-downloaded-at-write-amplification.md` (Tier 1) — the direct justification for the throttled/conditional-UPDATE write pattern: `relatime` is the exact same tradeoff already running on effectively every Linux filesystem read, and the GitLab incident is concrete, quantified, real-world proof that the naive unconditional-update approach causes genuine production problems.
+- `sqlite-forum-timestamp-integer-vs-text.md`, `sqlite-org-bm25-sign-flip-commit.md` (Tier 1) — justify the Unix-epoch-INTEGER column choice and flag the BM25 ranking-direction gotcha for whoever eventually builds the ranking-integration phase.
+- `glama-code-index-mcp-bm25-hybrid.md` (Tier 1) — a concrete, reusable BM25-normalization-and-fusion reference for that same future phase.
+
+## Alternatives considered and rejected
+
+- **Unconditional `UPDATE` on every access.** Rejected outright, per the GitLab incident's own documented production consequences (row-version and index-entry multiplication on a hot read path) — this is the one alternative with direct, quantified evidence against it, not just theoretical concern.
+- **In-memory batched writes flushed periodically** (the `lazytime` approach). Not rejected — deferred as a second-stage optimization, to be built only if the simple throttled-UPDATE approach proves insufficient under real measured load. Recorded explicitly as "not rejected, just not needed yet," not as a worse option.
+- **A single blended LRFU-style score computed and stored at write time**, instead of separate `last_used`/`use_count` columns. Rejected for this phase because collapsing recency and frequency into one opaque number at write time would destroy the ability to use them as independent inputs to whatever ranking or eviction decision gets made later — a decision that has not been made yet. This mirrors the Generative Agents / Mem0 pattern of keeping signals separate until the moment they're actually used.
+- **ISO-8601 TEXT for `last_used`, matching every other timestamp column in the vault.** Considered, since consistency has its own value and was retoor's own suggested fallback ("if it doesn't matter just use the same date format as the other columns"). Rejected specifically for this one column because it is the one column in the whole schema expected to be compared/range-scanned on a genuine hot path, where the SQLite-forum-documented integer advantages (no text parsing, smaller index entries, no timezone ambiguity) are the kind of thing that could plausibly matter — this is the one deliberate inconsistency in the schema, and it is being flagged as such rather than introduced silently.
+
+## Risks / open questions
+
+- The ~one-minute throttle window is an engineering estimate, not a measured value against tai's actual read/search volume — it has not been benchmarked.
+- Whether chunk-level `use_count` should itself decay over time (as in Mem0's or YourMemory's Ebbinghaus-curve approaches) is an open question explicitly deferred to a future decision, not resolved here.
+- Whether a chunk hit should *always* propagate to its parent record's `last_used`, or only under some condition, is a design detail that was decided one way here (always propagate) but not independently stress-tested against real usage patterns.
+
+## Action taken
+
+None yet. retoor's instructions for this research task explicitly forbade building anything — this document records the proposal and its supporting research only. Implementation remains a future decision.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial conclusion recorded. |
@@ -0,0 +1,28 @@
+# LLMs as Operating Systems: Agent Memory (DeepLearning.AI course)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | LLMs as Operating Systems: Agent Memory |
+| Source URL | https://www.deeplearning.ai/courses/llms-as-operating-systems-agent-memory |
+| Source type | vendor docs (course page) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management" as a DeepLearning.AI course page covering the same OS-metaphor memory architecture as MemGPT/Letta; not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# AI Agent Memory Part 2: The Case for Intelligent Forgetting
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | AI Agent Memory Part 2: The Case for Intelligent Forgetting |
+| Source URL | https://dev.to/sudarshangouda/ai-agent-memory-part-2-the-case-for-intelligent-forgetting-4i48 |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "Mem0 memory scoring decay forgetting curve AI agent long term memory"; a independent blog series entry on intelligent forgetting in agent memory, conceptually adjacent to the Mem0/YourMemory Tier 1 dossiers but not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# kindling-provider (docs.rs)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | kindling-provider |
+| Source URL | https://docs.rs/kindling-provider |
+| Source type | repository (Rust crate documentation) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "boost BM25 FTS5 search ranking by recency last accessed hybrid scoring formula" as a Rust crate's documentation page; relevance to the subject was not established — not opened or quoted during this pass, logged for completeness only.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Generative Agents: Human-like AI Behaviors
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Generative Agents: Human-like AI Behaviors |
+| Source URL | https://www.emergentmind.com/topics/generative-agents |
+| Source type | vendor/aggregator topic page |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper" as an EmergentMind topic-overview page on the Generative Agents paper; potentially a useful secondary overview but not opened or quoted during this research pass — the primary paper (`arxiv-2304-03442-generative-agents.md`) was used instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# MemGPT: OS-Inspired Memory Architecture
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | MemGPT: OS-Inspired Memory Architecture |
+| Source URL | https://www.emergentmind.com/topics/memgpt |
+| Source type | vendor/aggregator topic page |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management" as an EmergentMind overview page; the primary MemGPT paper (`arxiv-2310-08560-memgpt.md`) was used as the Tier 1 source instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Frontiers in Psychology — Generative agents article
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | (Frontiers in Psychology journal article, title not individually captured by this research pass) |
+| Source URL | https://www.frontiersin.org/journals/psychology/articles/10.3389/fpsyg.2025.1591618/full |
+| Source type | paper (journal article) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LLM agent memory recency importance relevance retrieval scoring generative agents paper" as a psychology-journal angle on generative agents; not opened or quoted during this pass, and even its own title was not individually captured in the search synthesis.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# YourMemory — Agentic AI memory with Ebbinghaus forgetting curve decay
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | YourMemory: Agentic AI memory with Ebbinghaus forgetting curve decay |
+| Source URL | https://github.com/sachitrafa/YourMemory |
+| Source publisher / author | sachitrafa (GitHub, independent/open-source project) |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+An open-source, smaller competitor project to Mem0 that implements agent memory aging explicitly on an Ebbinghaus forgetting-curve model, rather than Mem0's simpler linear-ish 0.3x–1.5x recency multiplier — and claims a measurable recall improvement over Mem0 on a named benchmark.
+
+## Key findings
+
+- Every memory is described as aging on an Ebbinghaus forgetting curve: stale, unused facts fade; important and frequently-recalled ones persist.
+- The project claims "+16pp better recall than Mem0 on LoCoMo" (a named long-context-memory benchmark).
+
+## Pros / strengths
+
+- Represents a concrete, implemented alternative to Mem0's simpler decay curve, grounded in an actual cognitive-science forgetting model rather than an ad hoc multiplier range — useful as a second data point on "how might decay actually be shaped" if tai ever builds a ranking-integration phase.
+
+## Cons / limitations / caveats
+
+- The "+16pp better recall than Mem0" figure is the competing project's own self-reported claim, on its own chosen benchmark, with no independent verification found during this research pass. It should be treated as a marketing/positioning claim, not a verified result, until independently reproduced.
+- Smaller, less established project than Mem0 or Letta — lower confidence that its described behavior matches real-world production experience at scale.
+
+## Relevance to tai
+
+A second, independent example (alongside Mem0) that agent-memory products are converging on recency-as-decay-curve for ranking rather than for eviction — reinforces, but does not change, the subject's conclusion that tai's current proposal should stop at raw tracking and defer any decay-curve decision.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,51 @@
+# S16 follow-up: three open surfaces of the last_downloaded_at write-amplification argument
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | S16 follow-up: three open surfaces of the last_downloaded_at write-amplification argument |
+| Source URL | https://gitlab.com/gitlab-org/ops/artifact-registry/-/work_items/680 |
+| Source publisher / author | GitLab (internal engineering work item, publicly visible) |
+| Source type | other (production engineering issue tracker entry) |
+| Source date (published) | Unknown — not stated (exact work item date not captured by this research pass) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+A real, named production incident write-up from GitLab's own artifact registry engineering work, documenting the exact failure mode this subject's conclusion is designed to avoid: an unconditional "touch" update on a hot read path causing serious database write amplification — with a concrete, quantified load estimate and GitLab's own fix.
+
+## Key findings
+
+- The `last_downloaded_at` column in question is part of a btree index, so updating it cannot be satisfied by a heap-only-tuple (HOT) update — every bump therefore creates a new row version *and* a new entry in every index the row belongs to.
+- Concrete load estimate given: a 10-layer container image pulled 100 times a minute, with every layer resolving to the same underlying row, works out to roughly 17 row versions per second plus 51 index entries per second on that one row — from what looks like "just incrementing a timestamp."
+- GitLab's actual fix was a throttled update: the write is skipped based on the freshness of the row's own existing timestamp, so repeated reads within the throttle window are no-ops at the database layer.
+- The work item notes one of the two write routes was throttled this way while a second (blob reads, which have no manifest row to check against) was not yet fixed at time of writing — i.e. even GitLab's own fix was partial/in-progress, not a universally complete solution captured in this source.
+
+## Pros / strengths
+
+- This is a real, quantified, named production incident — not a theoretical cache paper — making it the single most concrete evidence in this entire subject that "just add a last_used column and UPDATE it on every read" is a genuine, not hypothetical, performance risk.
+- The fix GitLab actually applied (throttle based on the row's own existing timestamp) is structurally identical to the pattern this subject's conclusion recommends for tai (`UPDATE ... WHERE last_used IS NULL OR last_used < ?`).
+
+## Cons / limitations / caveats
+
+- This is PostgreSQL-specific in its mechanics (HOT updates, btree index versioning) — SQLite (tai's actual database) has different internals, so the exact row-version/index-entry multiplication described here does not transfer number-for-number. The general lesson (indexed, frequently-touched timestamp columns cause real write amplification) does transfer; the specific "17 row versions/sec, 51 index entries/sec" figures are PostgreSQL-specific illustrations, not a universal constant.
+- The source itself documents an incomplete, in-progress fix (one route throttled, one not) — it should not be read as "GitLab solved this cleanly," only as "GitLab hit this problem and applied a partial, same-shaped fix."
+
+## Relevance to tai
+
+This is the primary real-world justification, cited directly in this subject's conclusion, for why tai's `last_used` column must never be updated unconditionally on every read/hit, and for why the recommended fix is a conditional/throttled UPDATE rather than a naive touch-on-every-access implementation.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# claude-memory-mcp — semantic-search.ts (Glama MCP server listing)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | semantic search (claude-memory-mcp) |
+| Source URL | https://glama.ai/mcp/servers/@WhenMoon-afk/claude-memory-mcp/blob/5f8d26e416fc516efffb63d3efffe7d00a7c17cc/src/search/semantic-search.ts |
+| Source type | repository (hosted source blob) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "boost BM25 FTS5 search ranking by recency last accessed hybrid scoring formula" as an MCP memory server's semantic-search implementation file; not opened or quoted during this pass. The specific numeric hybrid-fusion details used in this subject's research came from a different result in the same search, recorded at Tier 1 in `glama-code-index-mcp-bm25-hybrid.md`'s sibling card below.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# BM25 Hybrid Search Implementation Summary (Code-Index-MCP)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | BM25 Hybrid Search Implementation Summary |
+| Source URL | https://glama.ai/mcp/servers/@ViperJuice/Code-Index-MCP/blob/e3183d0106c586aec03535faabe632b4db4d6046/docs/implementation/BM25_HYBRID_SEARCH_IMPLEMENTATION.md |
+| Source publisher / author | ViperJuice (Code-Index-MCP project) |
+| Source type | repository (implementation documentation) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+An implementation-documentation file from an MCP code-indexing server describing how it normalizes raw BM25 scores and fuses them with semantic/vector scores for hybrid search. Promoted to Tier 1 (rather than the plain citation-card treatment of its sibling results in the same search) because the research synthesis attributed specific, concrete numeric details to this exact document, meeting the "independently analyzed" bar the Tier 1/Tier 2 distinction is built on.
+
+## Key findings
+
+- Normalizes raw BM25 rank to a [0,1] scale via a linear, clamped mapping: a raw rank of 0 maps to 1.0 (best), -5 maps to 0.5, and -10-or-worse clamps to 0.0; positive values are clamped to 1.0.
+- Fuses keyword (BM25) and semantic (vector) scores as a weighted linear sum, with stated defaults of 0.3 (keyword) and 0.7 (semantic), configurable via custom weights.
+
+## Pros / strengths
+
+- Gives a concrete, already-implemented example of score normalization for BM25 specifically (not just the sign-convention point from `sqlite-org-bm25-sign-flip-commit.md`, but an actual usable clamp-and-scale formula) — directly reusable reference if tai ever builds a phase that blends `last_used`/`use_count` into search ranking alongside BM25.
+
+## Cons / limitations / caveats
+
+- The specific clamp thresholds (0, -5, -10) are this project's own tuning, calibrated to its own corpus and BM25 configuration — not a universal constant, and not verified against tai's own `fts_docs` table's actual score distribution.
+- This dossier is based on the search tool's synthesis of the document, not a direct fetch and read of the full file — treat the two numeric details above as reliably attributed, but do not assume the rest of the document's content beyond what's stated here.
+
+## Relevance to tai
+
+A candidate reference implementation for a future (explicitly out-of-scope-for-now) phase where `last_used`/`use_count` get blended into tai's existing `bm25(fts_docs)`-based ranking — not used in the current tracking-only proposal, but recorded so that future phase doesn't start from zero.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created (promoted to Tier 1 on authoring, since specific attributable numeric findings were available, rather than filed as a bare Tier 2 citation card). |
@@ -0,0 +1,28 @@
+# gnosis-mcp — SQLite backend (aiosqlite + FTS5 + optional sqlite-vec)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | SQLite backend using aiosqlite + FTS5 + optional sqlite-vec for hybrid search |
+| Source URL | https://glama.ai/mcp/servers/@nicholasglazer/gnosis-mcp/blob/c98bf9ef8f3067a6a63b78e3c3ff9c126d52042c/src/gnosis_mcp/sqlite_backend.py |
+| Source type | repository (hosted source blob) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "boost BM25 FTS5 search ranking by recency last accessed hybrid scoring formula" as another MCP server using an aiosqlite+FTS5+optional-sqlite-vec hybrid backend — architecturally similar in spirit to the `sqlite-rag-hybrid-search` subject's own research, but not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# mcp-memory-service — test_hybrid_search.py (Glama MCP server listing)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | test hybrid search |
+| Source URL | https://glama.ai/mcp/servers/@doobidoo/mcp-memory-service/blob/8f6d4f397e1c5cc9cd94234732635810bb972a4a/tests/storage/test_hybrid_search.py |
+| Source type | repository (test suite file) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "boost BM25 FTS5 search ranking by recency last accessed hybrid scoring formula" as another MCP memory server's hybrid-search test file; not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# MFLRU Replacement (HiPC 2002 poster)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | MFLRU Replacement |
+| Source URL | https://www.hipc.org/hipc2002/2002Posters/MFLRU_Replacement.pdf |
+| Source type | paper (conference poster) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LRFU combined recency frequency cache replacement formula least recently frequently used" as a 2002 HiPC conference poster on an MFLRU (Most-Frequent-Least-Recently-Used, per name inference) replacement scheme; not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,51 @@
+# Agent Memory: How to Build Agents That Learn and Remember
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Agent Memory: How to Build Agents That Learn and Remember |
+| Source URL | https://www.letta.com/blog/agent-memory/ |
+| Source publisher / author | Letta (vendor blog) |
+| Source type | blog post / vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Letta (the company that productized MemGPT's ideas) describes its current tiered memory model: Core (in-context, RAM-analogue), Recall (cache-analogue), Archival (cold-storage analogue), with the model itself responsible for paging decisions through explicit tool calls.
+
+## Key findings
+
+- Tiers are explicitly analogized to a memory hierarchy: Core (RAM) / Recall (cache) / Archival (cold).
+- The LLM itself manages memory autonomously via function calls such as `search_memory` and `add_to_working`, rather than an external, opaque eviction process.
+- Retrieval uses a hybrid of embedding similarity and recency-based scoring — recency plays a role in *ranking* results, but the source material does not tie it to any formal LRU *eviction* rule; eviction and ranking are presented as separate concerns.
+- A separate 2026-dated survey (per the research synthesis) describes newer Letta features: developer-defined memory blocks, automatic compaction of older messages, and experimental "sleep-time" agents that process memory in the background between interactions.
+
+## Pros / strengths
+
+- Clear, current (vendor-maintained) articulation of a three-tier memory hierarchy that other agent-memory systems implicitly reference.
+- Explicitly separates "how do we rank what to retrieve" (recency+embeddings) from "how do we decide what to evict/compact" (the model's own tool calls, or background "sleep-time" compaction) — a clean separation tai's own design should probably preserve.
+
+## Cons / limitations / caveats
+
+- It is vendor marketing content, not an independent technical analysis or paper — claims about Letta's internals should be treated as the vendor's own self-description, not independently verified.
+- "Recency-based scoring" is mentioned without a documented formula; this dossier cannot cite an exact decay function because the source did not state one in the material the search tool returned.
+
+## Relevance to tai
+
+Reinforces the pattern (also seen in MemGPT and Mem0) of keeping ranking and eviction/compaction as separate mechanisms, and of letting recency inform ranking without being the sole driver of deletion — consistent with this subject's conclusion to track `last_used`/`use_count` now while explicitly deferring any eviction or ranking-integration decision.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Letta - LLM Agent Research (notes)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Letta - LLM Agent Research |
+| Source URL | https://lin-guanguo.github.io/llm-memory-research/letta.research/ |
+| Source type | blog post (personal research notes) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management" as an individual researcher's personal notes on Letta; not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Once Upon Atime (LWN.net kernel article)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Once Upon Atime |
+| Source URL | https://lwn.net/Articles/244829 |
+| Source type | other (kernel-development news article) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "Linux relatime lazytime atime update reduce write overhead filesystem technique" as LWN's own historical coverage of the atime/relatime kernel discussion; the Red Hat documentation (`redhat-relatime-drive-access.md`) was used as the Tier 1 source for the actual relatime/lazytime mechanics instead of this article, which was not independently opened.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# Paper Review: Generative Agents: Interactive Simulacra of Human Behavior
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Paper Review: Generative Agents: Interactive Simulacra of Human Behavior |
+| Source URL | https://artgor.medium.com/paper-review-generative-agents-interactive-simulacra-of-human-behavior-cc5f8294b4ac |
+| Source publisher / author | artgor (Medium) |
+| Source type | blog post (secondary review) |
+| Source date (published) | Unknown — not stated; the search tool flagged this piece as roughly 1,150 days old relative to the search date, i.e. a multi-year-old secondary source |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A secondary review/summary of the Generative Agents paper (see `arxiv-2304-03442-generative-agents.md`), useful mainly as corroboration of the recency/importance/relevance retrieval-score structure from an independent reader rather than as a primary source in its own right.
+
+## Key findings
+
+- Corroborates the three-part retrieval score (recency, importance, relevance) and the normalize-then-combine framing.
+- Does not appear to add technical detail beyond the original paper; its value here is as a second, independent restatement that agrees with the primary source.
+
+## Pros / strengths
+
+- Independent confirmation reduces the risk that the primary dossier's synthesis of the original paper was a search-tool misreading.
+
+## Cons / limitations / caveats
+
+- Multi-year-old secondary commentary; the field has moved substantially since (see the Mem0 and MemGPT/Letta dossiers in this same subject), so anything in this review not corroborated by the primary paper or by current vendor documentation should be treated as dated.
+- Adds no new findings beyond the primary source.
+
+## Relevance to tai
+
+Low standalone relevance — included for completeness and cross-checking, not as an independent input to the conclusion in this subject.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Stateful AI Agents: A Deep Dive into Letta (MemGPT) Memory Models
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Stateful AI Agents: A Deep Dive into Letta (MemGPT) Memory Models |
+| Source URL | https://medium.com/@piyush.jhamb4u/stateful-ai-agents-a-deep-dive-into-letta-memgpt-memory-models-a2ffc01a7ea1 |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management" as an independent deep-dive blog post; the Letta vendor blog and MemGPT paper were used as the Tier 1 sources instead of this secondary writeup.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# AI Memory Management: 4 Layers & Production Benchmarks (Mem0)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | AI Memory Management: 4 Layers & Production Benchmarks |
+| Source URL | https://mem0.ai/blog/ai-memory-management-for-llms-and-agents |
+| Source type | blog post / vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "Mem0 memory scoring decay forgetting curve AI agent long term memory" as a broader Mem0 blog post on a "4 layers" memory-management framework; not opened or quoted independently during this pass, with the decay-specific and eviction-specific posts used as Tier 1 sources instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Agent Memory Staleness: How Recency-Aware Ranking Fixes Retrieval Drift (Mem0)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Agent Memory Staleness: How Recency-Aware Ranking Fixes Retrieval Drift |
+| Source URL | https://mem0.ai/library/context-engineering/memory-decay-for-long-running-agents-how-recency-aware-ranking-fixes-retrieval-staleness |
+| Source type | blog post / vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "Mem0 memory scoring decay forgetting curve AI agent long term memory" as a context-engineering-focused Mem0 library article specifically about recency-aware ranking and retrieval staleness — closely related to the decay mechanism covered at Tier 1 in `mem0-introducing-memory-decay.md`, but this specific article was not independently opened during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# How to create AI agents with long-term memory (Mem0)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | How to create AI agents with long-term memory |
+| Source URL | https://mem0.ai/blog/how-to-create-ai-agents-with-long-term-memory |
+| Source type | blog post / vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "Mem0 memory scoring decay forgetting curve AI agent long term memory" as a how-to-oriented blog post; not opened or quoted independently during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,51 @@
+# Introducing Memory Decay in Mem0
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Introducing Memory Decay in Mem0 |
+| Source URL | https://mem0.ai/blog/introducing-memory-decay-in-mem0 |
+| Source publisher / author | Mem0 (vendor blog) |
+| Source type | blog post / vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Mem0's "Memory Decay" feature is a search-time re-ranking multiplier based on recency since last access — not a deletion/forgetting mechanism. It is the closest thing in current commercial agent-memory products to what tai is being asked to build the tracking substrate for.
+
+## Key findings
+
+- Each memory receives a recency-based scaling factor between 0.3x and 1.5x: recently accessed memories get boosted up to 1.5x, idle ones drift down toward a 0.3x floor.
+- Nothing is ever deleted by this mechanism — the 0.3x floor means an idle-but-genuinely-relevant memory can still surface for the right query, just lower in the ranking.
+- Access to a memory resets/raises its decay score — i.e. "used" directly and immediately affects future ranking.
+- Mem0's own A/B test is reported to have moved the correct memory to rank 1 in 3 of 4 test cases, and widened score separation from a ~0.0001 margin to a 0.15+ gap.
+
+## Pros / strengths
+
+- Exactly the "soft re-ranking, not hard eviction" pattern this subject's conclusion recommends tai consider for a *future* phase (explicitly not being built now) — recording this now means the next phase doesn't have to rediscover this precedent.
+- The 0.3x–1.5x framing is simple enough to reason about and reimplement if/when tai decides to build a ranking-integration phase.
+
+## Cons / limitations / caveats
+
+- The "3 of 4 test cases" and "0.15+ gap" figures are vendor-reported, from a vendor's own blog post, on an unstated and likely small sample size — this is marketing evidence, not an independently reproduced benchmark, and should not be treated as a general guarantee.
+- No exact decay formula (e.g. half-life, decay constant) is disclosed in the material available to this research pass — the mechanism's existence and rough behavior are known; its precise math is not.
+
+## Relevance to tai
+
+Directly relevant precedent for a possible future phase of tai's `last_used`/`use_count` work (ranking integration), explicitly out of scope for the current proposal, which is tracking-only. Cited in the subject's conclusion document as the main real-world analogue for "recency as a soft ranking signal, not a deletion trigger."
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# AI Agent Memory Library: Guides & Tutorials (Mem0)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | AI Agent Memory Library: Guides & Tutorials |
+| Source URL | https://mem0.ai/library |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "Mem0 memory scoring decay forgetting curve AI agent long term memory" as Mem0's general guide/tutorial library index page; the specific decay and eviction blog posts were used as Tier 1 sources instead of this general index.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,50 @@
+# Memory eviction and forgetting in AI agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Memory eviction and forgetting in AI agents |
+| Source URL | https://mem0.ai/blog/memory-eviction-and-forgetting-in-ai-agents |
+| Source publisher / author | Mem0 (vendor blog) |
+| Source type | blog post / vendor docs |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+Mem0's broader guidance on eviction/forgetting beyond the Memory Decay feature specifically: it distinguishes soft re-ranking (decay) from real pruning, and recommends TTL policies plus explicit deletion APIs for genuine forgetting, with tiered memory lifetimes by scope.
+
+## Key findings
+
+- Session memory is described as persisting minutes-to-hours and being cleared explicitly; user- and organization-level memory are long-lived by contrast.
+- For episodic data specifically, the guidance is to use timestamps plus explicit TTL policies rather than relying on decay alone.
+- The source explicitly states memory systems need deletion APIs and UX patterns that expose what is remembered — i.e. forgetting should be an observable, intentional operation, not an opaque side effect.
+- Decay (see `mem0-introducing-memory-decay.md`) is characterized here as "decays low-relevance entries over time, freeing up space and attention" — a description, not a documented formula.
+
+## Pros / strengths
+
+- Clearly separates three distinct concerns that are easy to conflate: ranking (decay), lifecycle/expiry (TTL), and user-visible deletion (explicit API) — a useful three-way framework for tai to keep in mind even though only the tracking substrate for the first concern is being built right now.
+
+## Cons / limitations / caveats
+
+- Lacks a documented formula for its own decay mechanism (consistent with the companion decay-announcement post); this source is guidance-level, not implementation-level detail.
+- Vendor content, not independently verified.
+
+## Relevance to tai
+
+Useful for correctly scoping what tai's `last_used`/`use_count` proposal is and is not: it is tracking substrate that could later feed a decay-style ranking signal (per Mem0's own distinction), but it is explicitly not a TTL/expiry mechanism and not a deletion mechanism — those would be separate, later decisions if ever made.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# AI Agent Memory: Complete Guide & Architecture (Mem0)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | AI Agent Memory: Complete Guide & Architecture |
+| Source URL | https://mem0.ai/blog/memory-in-agents-what-why-and-how |
+| Source type | blog post / vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "Mem0 memory scoring decay forgetting curve AI agent long term memory" as a general architecture-overview blog post; not opened or quoted independently during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# 2Q: A Low Overhead High Performance Buffer Management Replacement Algorithm (Papers We Love)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | 2Q: A Low Overhead High Performance Buffer Management Replacement Algorithm |
+| Source URL | https://paperswelove.org/papers/2q-a-low-overhead-high-performance-buffer-manageme-98fa2c32/ |
+| Source type | paper (hosted copy of the original Johnson & Shasha 1994 VLDB paper) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "approximate LRU algorithm CLOCK 2Q low write overhead cache eviction database" as the original primary paper behind the 2Q algorithm already summarized at Tier 1 via `arpit-2q-cache-algorithm.md`'s explainer; this is the primary document itself, logged here rather than promoted to Tier 1 because this research pass worked from the explainer, not a direct read of the original paper's full text.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,51 @@
+# Relatime Drive Access Optimization
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Relatime Drive Access Optimization |
+| Source URL | https://docs.redhat.com/en/documentation/Red_Hat_Enterprise_Linux/7/html/power_management_guide/relatime |
+| Source publisher / author | Red Hat (official product documentation) |
+| Source type | vendor docs |
+| Source date (published) | Unknown — not stated (RHEL 7 era documentation) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Official Red Hat documentation of the Linux `relatime` mount option, which is the single clearest, most battle-tested real-world precedent found in this entire subject for "track last-access time without writing on every single access." `relatime` has been Linux's default mount behavior since kernel 2.6.20.
+
+## Key findings
+
+- The underlying problem: maintaining atime (access time) traditionally requires a write to storage on every read, even when the read itself was satisfied entirely from page cache — turning cheap reads into disk writes purely for bookkeeping.
+- `noatime` disables access-time tracking entirely, but this can break software that depends on it (some mail clients comparing mtime/atime to determine unread status, `tmpwatch`, some backup tools).
+- `relatime` (the default since kernel 2.6.20) is the middle ground: atime is only written to disk if the file has been modified since atime was last updated, OR if the existing atime is older than a threshold (default: one day).
+- `lazytime` goes further: atime/mtime/ctime updates are kept purely in memory and only flushed to disk on a non-time-related change, an explicit `fsync`/`syncfs`/`sync` call, or inode eviction — acceptable under POSIX specifically because there's no crash-durability guarantee for a value without an explicit fsync.
+
+## Pros / strengths
+
+- This is a genuinely load-bearing, decades-battle-tested real-world precedent, not a theoretical cache-algorithm paper — Linux runs this exact tradeoff on essentially every filesystem read on the planet.
+- Gives two distinct, usable patterns at two different levels of aggressiveness: `relatime`'s "write only if stale" rule maps directly onto a conditional SQL `UPDATE ... WHERE last_used < threshold`; `lazytime`'s "batch in memory, flush later" maps onto an in-process batching layer if the simpler approach ever proves insufficient.
+
+## Cons / limitations / caveats
+
+- This is filesystem-level precedent, not database-level — the exact mechanics (inode eviction, fsync semantics) don't transfer literally to a SQLite table, only the *principle* (don't write on every read; write only when stale, or batch in memory) transfers.
+- The one-day default staleness threshold for `relatime` is tuned for filesystem atime semantics and general-purpose workloads; it is not necessarily the right throttle window for tai's `last_used` tracking, which this subject's conclusion separately estimates at roughly one minute as a starting point — that number is this project's own guess, not something `relatime` itself recommends.
+
+## Relevance to tai
+
+This is the primary justification, cited directly in this subject's conclusion, for using a throttled/conditional-UPDATE pattern (`UPDATE ... WHERE last_used IS NULL OR last_used < ?`) instead of an unconditional write on every hit — the exact same engineering tradeoff Linux already made, battle-tested at a far larger scale than tai will ever need.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# rmarcus.info Database Paper Browser — Clock2Q+ entry
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Database Paper Browser (rmarcus.info dbscholar) |
+| Source URL | https://rmarcus.info/dbscholar/papers/hc626719af823404a |
+| Source type | other (paper-browser/aggregator entry) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "approximate LRU algorithm CLOCK 2Q low write overhead cache eviction database" as an entry in Ryan Marcus's personal database-paper browser tool, pointing to Clock2Q+-related material. Two further rmarcus.info paper-browser pages (`https://rmarcus.info/dbscholar/papers/8213` and `https://rmarcus.info/dbscholar/papers/he7c2c6333f9a3929`) also surfaced during the same and related searches and are treated as the same source family — logged under this one card rather than filed separately, since all three are the same aggregator tool pointing at adjacent database-paper-browser entries rather than independently distinct content.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Is there advantage of using Integer in table column created_at? (SitePoint forum)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Is there advantage of using Integer in table column created_at? |
+| Source URL | https://www.sitepoint.com/community/t/is-there-advantage-of-using-integer-in-table-column-created-at/343308 |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "SQLite last_accessed column unix timestamp vs datetime performance indexing" as a directly on-topic forum thread (integer vs. other types for a timestamp column); not opened or quoted independently during this pass beyond what's already captured in the Tier 1 dossier for the primary SQLite forum source.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# SQLite Forum — second datetime-related thread
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | (SQLite Forum thread, title not individually captured) |
+| Source URL | https://sqlite.org/forum/info/5203f28a039a028754fda31591bbfb3c9ca9a949277cb45d789a2f78aecbd52f?t=c |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "SQLite last_accessed column unix timestamp vs datetime performance indexing" as a second, distinct SQLite forum thread from the one used as the Tier 1 source (`sqlite-forum-timestamp-integer-vs-text.md`); not opened or quoted independently during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,50 @@
+# SQLite Forum: INTEGER vs TEXT timestamp storage discussion
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | SQLite Forum post on date/time storage representations |
+| Source URL | https://sqlite.org/forum/forumpost/92d9dbc02808629a?raw |
+| Source publisher / author | SQLite official forum (community post, unnamed individual poster) |
+| Source type | forum thread |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A SQLite community forum discussion on the tradeoffs between storing timestamps as Unix-epoch INTEGER versus ISO-8601 TEXT. Explicitly an opinion/forum post, not a controlled benchmark — the search tool itself flagged this distinction, which this dossier preserves.
+
+## Key findings
+
+- SQLite has no dedicated datetime column type; it natively supports three representations: TEXT (`YYYY-MM-DD HH:MM:SS.SSS`), REAL (Julian day number), and INTEGER (Unix time).
+- The forum poster's argument for integers: faster indexed range queries (`BETWEEN`/`>=`/`<=` directly on the integer index), no text parsing needed, smaller storage footprint than ISO-8601 text.
+- The poster's argument is explicitly their own opinion, not a measured benchmark, per the search synthesis of this thread.
+- Integer Unix timestamps are unambiguous across daylight-saving-time transitions in a way that naive local-time text values are not (a correctness point, separate from the raw-speed point).
+- A counterpoint noted in the broader discussion: ISO-8601 text sorts correctly as a plain string and remains the most human-readable choice; its index entries are simply larger, not functionally broken.
+
+## Pros / strengths
+
+- Directly surfaces both sides of exactly the tradeoff this subject's conclusion needed to resolve (integer vs. text for a `last_used` column), from a venue (SQLite's own community forum) with direct relevant expertise.
+
+## Cons / limitations / caveats
+
+- Self-admittedly opinion-based, not a controlled benchmark — no actual timing numbers were produced in the material reviewed. The practical recommendation this subject reaches (use INTEGER for `last_used` specifically, because it's a hot, comparison-heavy column, while leaving the vault's other timestamp columns as ISO-8601 TEXT) is a judgment call informed by this thread's reasoning, not a number verified against tai's actual workload.
+
+## Relevance to tai
+
+Directly informs the one explicitly-flagged exception in this subject's conclusion: recommending `last_used` be stored as Unix-epoch INTEGER even though every other timestamp column in tai's vault schema is ISO-8601 TEXT, specifically because this column is compared/sorted/range-scanned on the hot path in a way the others generally are not.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# SQLite source history: bm25() sign-convention change
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | SQLite source/commit history entry concerning the bm25() auxiliary function |
+| Source URL | https://sqlite.org/src/info/3ee7b5a9f987c269 |
+| Source publisher / author | SQLite project (official source repository) |
+| Source type | other (source control history entry) |
+| Source date (published) | Unknown — not stated (historical commit; exact date not captured by this research pass) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A SQLite source-history record documenting that the `bm25()` FTS5 auxiliary ranking function's result is multiplied by -1, so that a *lower* (more negative) score means a *better* match — meaning correct usage requires `ORDER BY rank` ascending, not descending, which is the opposite of the intuitive "higher score = better" assumption.
+
+## Key findings
+
+- `bm25()` scores are inverted relative to naive expectation: better matches produce lower (more negative) numbers.
+- Consequently, ranking queries must sort ascending (`ORDER BY rank` with no `DESC`) to get best-matches-first, not descending.
+
+## Pros / strengths
+
+- Primary-source (SQLite's own project history) confirmation of a detail that is easy to get backwards and silently misrank results if assumed rather than checked.
+
+## Cons / limitations / caveats
+
+- This is a narrow, mechanical fact about FTS5's API, not itself evidence about recency tracking or write amplification — it's included here because it surfaced in the same research query about combining BM25 with recency-aware ranking, and is directly relevant to *correctly implementing* any future phase that blends `last_used` into search ranking.
+
+## Relevance to tai
+
+Tai's existing `fts_search()` code already sorts by `bm25(fts_docs)` ascending (confirmed independently in the codebase, not from this source) — this dossier exists so that if/when a future phase blends a recency signal into ranking, whoever implements it does not accidentally assume "higher bm25 score is better" and invert the ranking.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Tarantool Vinyl: throttle tx to ensure compaction keeps up with dumps (patch series)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | vinyl: throttle tx to ensure compaction keeps up with dumps |
+| Source URL | https://lists.tarantool.org/pipermail/tarantool-patches/2019-January/004332.html |
+| Source type | other (mailing-list patch series) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "throttled lazy timestamp update avoid write amplification last_accessed database pattern". This research pass's own synthesis explicitly flagged this result (and two further patch-series revisions in the same thread, v2 and v3, treated here as the same source family) as off-target/tangential: it concerns throttling transactions to keep LSM-tree compaction ahead of memory dumps in Tarantool's Vinyl storage engine, which is a related-but-distinct throttling concern from the specific "don't write a timestamp on every read" pattern this subject needed. Logged honestly as a near-miss rather than omitted or misrepresented as directly on-topic.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (off-target / tangential to this subject). |
@@ -0,0 +1,28 @@
+# USENIX 2001 — Zhou et al., trace analysis section
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | (USENIX 2001 full paper by Zhou et al., "Traces" section) |
+| Source URL | https://static.usenix.org/event/usenix01/full_papers/zhou/zhou_html/node3.html |
+| Source type | paper |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LRFU combined recency frequency cache replacement formula least recently frequently used" as a related-work mention alongside LRFU, FBR, LRU-K, 2Q, and ARC; this specific "Traces" section of a 2001 USENIX paper was not independently opened during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Preventing write amplification during frequent data updates (US Patents 10,037,155 B2 and 11,494,276 B2)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Preventing write amplification during frequent data updates; Reduced write amplification using small-block log |
+| Source URL | https://patents.google.com/patent/US10037155 (related: https://patents.google.com/patent/US11494276B2) |
+| Source type | patent |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "throttled lazy timestamp update avoid write amplification last_accessed database pattern" as two related patents on write-amplification mitigation in storage systems; logged together as one source family since both surfaced from the same query for the same general concern and neither was independently opened. These are storage-device/firmware-level write-amplification patents (a different mechanism, closer to SSD wear-leveling concerns) rather than the database-row-update write amplification this subject's conclusion is actually about — flagged here as adjacent-but-distinct, consistent with this research pass's honesty requirement.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (adjacent concern: storage-level, not row-update-level, write amplification). |
@@ -0,0 +1,28 @@
+# System and method for implementing an adaptive replacement cache policy (US Patent 6,996,676 — the ARC patent)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | System and method for implementing an adaptive replacement cache policy |
+| Source URL | https://image-ppubs.uspto.gov/dirsearch-public/print/downloadPdf/6996676 |
+| Source type | patent |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LRFU combined recency frequency cache replacement formula least recently frequently used" — this is the patent underlying the well-known ARC (Adaptive Replacement Cache) algorithm, notable by name even though this research pass did not open or independently verify its specific claims. Worth flagging for a future deeper pass given ARC's real-world prominence (used in ZFS, among other systems), but out of scope for the current tracking-only proposal.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# System and method for adaptively managing pages in a memory (US Patent 7,167,953)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | System and method for adaptively managing pages in a memory |
+| Source URL | https://image-ppubs.uspto.gov/dirsearch-public/print/downloadPdf/7167953 |
+| Source type | patent |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "LRFU combined recency frequency cache replacement formula least recently frequently used" as a patent in the adaptive-page-replacement space; not opened or quoted during this pass. Patents in this space are logged for completeness but treated with extra caution since patent claims describe legal scope, not necessarily the clearest technical explanation — the LRFU explainer content used for the subject's background research came from academic-paper summaries, not this patent.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Mem0 vs Letta (MemGPT): AI Agent Memory Compared (2026)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Mem0 vs Letta (MemGPT): AI Agent Memory Compared (2026) |
+| Source URL | https://vectorize.io/articles/mem0-vs-letta |
+| Source type | blog post (vendor-adjacent comparison) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "MemGPT Letta memory tiering LRU eviction agent context management" as a direct comparison of the two leading products discussed in this subject's Tier 1 dossiers; a strong candidate for deeper reading in a future pass, but not opened or quoted during this one since the vendor-primary sources were used instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# VLDB 1994 DBLP bibliography listing
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | VLDB '94 proceedings — DBLP bibliography listing |
+| Source URL | https://mail.vldb.org/dblp/db/conf/vldb/vldb94-439.html |
+| Source type | other (bibliography index page) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "approximate LRU algorithm CLOCK 2Q low write overhead cache eviction database" as the DBLP bibliographic record for the VLDB 1994 proceedings containing the original 2Q paper; purely a citation-index page, not opened for content.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# WebmasterWorld PHP forum — datetime index thread
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | (WebmasterWorld PHP forum thread, title not individually captured) |
+| Source URL | https://www.webmasterworld.com/php/3532632.htm |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "SQLite last_accessed column unix timestamp vs datetime performance indexing"; a MySQL-focused (not SQLite) forum thread on the same general timestamp-type question, which the search synthesis noted concluded with "there is no substitute for running your own performance tests." Not opened directly or quoted beyond that one summarized takeaway, which is instead recorded in the `sqlite-forum-timestamp-integer-vs-text.md` Tier 1 dossier.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# DateTime to SQLite (Xojo forum thread)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | agent-memory-recency-tracking |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | DateTime to SQLite |
+| Source URL | https://forum.xojo.com/t/datetime-to-sqlite/42307?page=2 |
+| Source type | forum thread |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the search "SQLite last_accessed column unix timestamp vs datetime performance indexing" as a Xojo-framework-specific forum thread on converting DateTime values for SQLite storage; not opened or quoted during this pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Letta AI Skills: Cancel Async Tasks — agentskills.so
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Letta AI Skills: Cancel Async Tasks |
+| Source URL | https://agentskills.so/skills/letta-ai-skills-cancel-async-tasks |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio create_subprocess_exec start_new_session" search query — a Letta/agent-skills guide on cancelling async tasks (the research synthesis mentioned it recommending `asyncio.shield()` for critical cleanup, but that specific point was not independently re-verified against this exact page). A near-duplicate localized page (https://agentskills.so/zh/skills/letta-ai-skills-cancel-async-tasks) also surfaced and is treated as the same source family.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# Kill a Python subprocess and its children when a timeout is reached
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Kill a Python subprocess and its children when a timeout is reached |
+| Source URL | https://alexandra-zaharia.github.io/posts/kill-subprocess-and-its-children-on-timeout-python/ |
+| Source publisher / author | Alexandra Zaharia (personal blog) |
+| Source type | blog post |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A worked, example-driven blog post covering the same group-signal approach as `iannuccisolutions-timeout-process-group.md`, with an added emphasis on explicitly reaping the process afterward (calling `wait()`/`communicate()` again post-kill) so it doesn't linger as a zombie.
+
+## Key findings
+
+- Confirms the process-group-signal approach (start a new session/group, signal the whole group on timeout) as a working pattern, consistent with other sources in this subject.
+- Adds the specific point that killing a process does not by itself reap it — an explicit `wait()`/`communicate()` call afterward is required, or the dead child remains a zombie entry in the process table until its parent collects its exit status.
+
+## Pros / strengths
+
+- Reinforces, from an independent author, the same group-kill pattern already found elsewhere in this research — converging evidence rather than a single source's opinion.
+- The explicit reaping point is a detail some other sources mention only implicitly.
+
+## Cons / limitations / caveats
+
+- A personal blog post with a worked example, not a formal specification; the exact code shown was not independently re-run or verified against `asyncio`'s API in this research pass.
+
+## Relevance to tai
+
+Reinforced `tai_test.py`'s `ManagedProcess.terminate()` always ending with `await asyncio.wait_for(self.proc.wait(), 5.0)` regardless of which signal actually stopped the process — the comment in the code ("reap so no zombie remains") traces directly to this point.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# All-Hands integration_tests/tests/base — docs.all-hands.dev
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | integration_tests/tests/base |
+| Source URL | https://docs.all-hands.dev/modules/python/evaluation/integration_tests/tests/base |
+| Source type | vendor docs |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "python integration test framework design base class" search query — notably, this is documentation for an *agent evaluation* integration-test base class (an abstract class with a "prepare environment" classmethod and a "verify after the agent performs the task" method), conceptually close to `tai_test.py`'s own purpose of testing an AI agent's CLI. Not individually opened or quoted in this research pass, but worth flagging as a close conceptual match for anyone extending this subject later.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# Redirect Process Output — Baeldung on Linux
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Redirect Process Output |
+| Source URL | https://www.baeldung.com/linux/redirect-process-output |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio tee process output to file and stdout" search query as a general Linux-level (shell `tee`) article on redirecting process output; not individually opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,48 @@
+# CPython bug reports: asyncio.wait_for() timeout does not kill the awaited process
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | bugs.python.org msg233486, and companion msg357930 |
+| Source URL | https://bugs.python.org/msg233486 |
+| Source publisher / author | Python core development bug tracker (bugs.python.org / BPO) |
+| Source type | other (official bug tracker message) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Official CPython bug tracker messages confirming that `asyncio.wait_for()` timing out does not, by itself, terminate the coroutine/process it was waiting on — the awaited operation can continue running in the background after the `TimeoutError` is raised to the caller.
+
+## Key findings
+
+- A bug report describes `wait_for()` timing out while the process it was waiting on continued living in the background — the timeout only stops *waiting*, it does not reach into and stop the underlying operation.
+- This is documented as a known, discussed behavior in CPython's own bug tracker (two related messages), not a one-off misunderstanding.
+
+## Pros / strengths
+
+- Primary-source, from the language's own bug tracker — about as authoritative as a finding in this subject gets.
+- Directly actionable: it tells you precisely what `wait_for()` does *not* do for you, closing a dangerous assumption gap.
+
+## Cons / limitations / caveats
+
+- Only the two referenced messages were reviewed, not the full bug thread's eventual resolution or whether later Python versions changed this behavior.
+
+## Relevance to tai
+
+This is the specific reason `tai_test.py.TestCase.execute()` never treats a caught `asyncio.TimeoutError` (from the `asyncio.wait_for(self.run(), timeout=self.timeout)` wrapping every test) as sufficient cleanup on its own. The `finally` block unconditionally calls `await proc.terminate()` for every spawned process, precisely because this source confirms the timeout itself does nothing to stop the process — only the explicit `terminate()` call (with its own `killpg` escalation and reap) does.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# ChromiumOS chromite lib/tee.py
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | lib/tee.py (chromite) |
+| Source URL | https://cos.googlesource.com/mirrors/cros/chromiumos/chromite/+/HEAD/lib/tee.py |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio tee process output to file and stdout" search query as ChromiumOS's own `tee` implementation in its build tooling; a second, near-identical mirror of the same file at a different ChromiumOS source host also surfaced and is treated as the same source family. Not individually opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,53 @@
+# Conclusion: tai_test.py's Transport, Cleanup, and Framework Design
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Conclusion |
+| Tier | N/A |
+| Date decided | 2026-10-09 |
+| Decided by | retoor, advised by tai (agent, Claude Sonnet 5) |
+| Status | Active |
+| Confidence | High |
+
+## Question / problem statement
+
+How should `tai_test.py` — a reusable integration-test framework for driving `tai.py` both as a one-shot subprocess and as a persistent interactive REPL (including scripting input and detecting turn boundaries) — be built so that it's safe (no leaked zombie processes on timeout, crash, or cancellation) and extensible (a clean base class future tests can subclass), using only the Python standard library, consistent with `tai.py`'s own zero-dependency rule?
+
+## Conclusion
+
+The framework uses two unified transports behind one `asyncio.StreamReader`-based interface: plain `asyncio.create_subprocess_exec` with `PIPE` streams for one-shot calls, and a real pty (stdlib `pty.openpty()`, the slave fd given to the child as stdin/stdout/stderr, the master fd wrapped into a `StreamReader` via `loop.connect_read_pipe`) for anything that needs the child to behave as if a human were typing — because `tai.py`'s own code branches on `sys.stdin.isatty()`. Optional live human stdin passthrough is bridged via `loop.add_reader` + raw `os.read` on the fd (never buffered `sys.stdin`, which blocks), with no background thread, mirroring how the child's own output is already consumed. Every process is started with `start_new_session=True` and torn down through an escalating SIGTERM-then-SIGKILL `os.killpg` call that always finishes with `proc.wait()` to reap it, so a timeout or crash never leaves an orphan. The `TestCase` base class (`setup`/`run`/`verify`/`teardown` hooks, typed exceptions carrying the full transcript) follows the declarative-base-class-plus-override-hooks pattern used by real prior art (CERN's Gaudi, gem5, OpenStack's oslotest) rather than being invented from scratch.
+
+## Supporting sources
+
+- `../ptyprocess-docs.md`, `../pypi-shellous.md`, `../github-agents-issue1-controlling-terminal.md` — established why a real pty (not a pipe) was needed, and the documented, accepted limitation that `tai_test.py`'s pty mode does not call `ioctl(TIOCSCTTY)` and so doesn't guarantee job-control signal semantics.
+- `../github-gist-nonblocking-stdin-os-read.md`, `../python-asyncio-issue499-add-reader-eof.md`, `../glama-mcp-remote-py-stdio-jsonl.md` — the exact techniques `StdinBridge` (raw `os.read` via `add_reader`) and `ManagedProcess`'s pty-mode `StreamReader` wrapping (`loop.connect_read_pipe`) implement.
+- `../pypi-pexpect.md`, `../pyte-terminal-emulator.md`, `../pypi-stitch-pty.md` — the alternatives surveyed and not adopted.
+- `../iannuccisolutions-timeout-process-group.md`, `../python-docs-asyncio-subprocess.md`, `../alexandra-zaharia-kill-subprocess-children-timeout.md`, `../execa-termination-docs.md` — the direct justification for `start_new_session` + `killpg` + always-reap.
+- `../discourse-merge-two-streams.md` — the reason a generic multi-stream-merge utility was deliberately **not** built.
+- `../gaudi-subprocess-base-test.md`, `../gem5-test-infrastructure-commit.md`, `../oslotest-timeout-fixture.md` — the test-framework architecture `TestCase` is modeled on.
+- `../discourse-subprocess-process-gc.md`, `../slingacademy-stop-kill-child-process.md`, `../bpo-wait-for-timeout-leaves-process-alive.md` — confirmation that relying on timeout or garbage collection alone to clean up a process is documented, known-unreliable, which is why `execute()`'s `finally` block always calls `terminate()` explicitly regardless of how the test ended.
+
+## Alternatives considered and rejected
+
+- **pexpect** — rejected because it's a blocking/synchronous library and `tai_test.py` is asyncio-native throughout; mixing a blocking library in would have meant either wrapping every call in a thread executor or accepting blocking the event loop, neither of which fit.
+- **stitch-pty** — rejected as too young/unverified to depend on for core framework plumbing, and as a compiled Rust-backed dependency it would also have violated the project's stdlib-only constraint.
+- **A generic tagged-queue multi-stream-merge utility** — rejected because the Discourse thread's own participants described the resulting async-generator plumbing as hard to maintain, and `tai_test.py`'s actual need (merging stdout+stderr in pipe mode) is fully satisfied by the simpler `stderr=STDOUT` subprocess argument, making the general utility unnecessary complexity.
+- **A background thread for bridging live stdin** — not rejected as wrong, but passed over in favor of `loop.add_reader` + `os.read` specifically so stdin-bridging follows the same no-thread, fd-based pattern as the child's own output handling, rather than mixing two different concurrency models in one framework.
+
+## Risks / open questions
+
+The pty mode does not explicitly call `ioctl(TIOCSCTTY)`, so there is no guarantee the child's session becomes the pty's controlling terminal in the full job-control sense. `isatty()`-based behavior (all that `tai.py`'s own code checks) is unaffected, since that's a property of the fd itself, not of session leadership — but SIGWINCH-based resize forwarding and tty-line-discipline-generated Ctrl-C-as-SIGINT are not guaranteed to work. This is accepted because no test built so far needs either capability; every test built on `tai_test.py` so far only scripts line-based input/output.
+
+## Action taken
+
+Implemented the same day as this research: `tai_test.py` (`ManagedProcess`, `StdinBridge`, `TeeLogger`, `TestCase`, `TestRunner`, `main_cli`) at the repository root, and `tests/rag.py` built on it — both already in use and passing against the real `tai.py` binary.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial conclusion recorded. |
@@ -0,0 +1,28 @@
+# CPython asyncio-subprocess.rst — googlesource/gitea/remotebranch mirrors
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | asyncio-subprocess.rst (llvm.googlesource.com mirror) |
+| Source URL | https://llvm.googlesource.com/third_party/cpython/+/refs/heads/main/Doc/library/asyncio-subprocess.rst |
+| Source type | standard (mirrored stdlib source) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio create_subprocess_exec start_new_session" search query: several near-duplicate mirrors of the same CPython `asyncio-subprocess.rst` documentation source surfaced across different git-hosting forks — several commit-pinned `chromium.googlesource.com` variants, `git.joshthomas.dev`'s mirror of the 3.9 branch, and `remotebranch.eu`'s mirror of the 3.15 branch, in addition to the llvm.googlesource.com one listed above. These are all redundant mirrors of the same stdlib source file already covered at Tier 1 in `python-docs-asyncio-subprocess.md`, not independent sources, logged together as one card.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (redundant mirrors of a Tier 1 source). |
@@ -0,0 +1,28 @@
+# Python 3.9.2 asyncio-subprocess docs (CS UNB mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Subprocesses — Python 3.9.2 documentation (teaching mirror) |
+| Source URL | https://www.cs.unb.ca/~bremner/teaching/cs2613/books/python3-doc/library/asyncio-subprocess.html |
+| Source type | standard (mirrored stdlib documentation) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio subprocess timeout kill process group" search query — a university teaching-site mirror of the same stdlib `asyncio-subprocess` documentation already covered at Tier 1 in `python-docs-asyncio-subprocess.md`. Logged as a redundant mirror.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (mirror of a Tier 1 source). |
@@ -0,0 +1,28 @@
+# python3-pyte — CSAIL Debian package mirror
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | python3-pyte (CSAIL mirror) |
+| Source URL | https://packages-pkgmirror-csail.debian.org/python3-pyte |
+| Source type | repository (package page mirror) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "pexpect pyte vs asyncio pty" search query — a CSAIL mirror of the same `python3-pyte` Debian package page already covered at Tier 1 in `pyte-terminal-emulator.md`. Logged as a redundant mirror, not an independent source.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (mirror of a Tier 1 source). |
@@ -0,0 +1,48 @@
+# Asyncio: How to merge two streams — discuss.python.org
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Asyncio: How to merge two streams |
+| Source URL | https://discuss.python.org/t/asyncio-how-to-merge-two-streams/106616 |
+| Source publisher / author | Python Discourse community |
+| Source type | forum thread |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A Python Discourse thread discussing how to merge two independent asyncio streams (e.g. a subprocess's stdout and stderr) into one consumable sequence. The community-arrived-at pattern is one background task per stream, each pushing tagged chunks into a shared `asyncio.Queue`, with a single consumer draining the queue — but participants in the thread itself described the resulting plumbing as messy and said they were no longer comfortable maintaining it.
+
+## Key findings
+
+- The tagged-queue pattern (one task per stream, push `(stream_name, chunk)` tuples into a shared queue, one consumer loop) is the community's working answer, confirmed to function.
+- Multiple participants in the same thread independently reported the approach grew complex enough to become a maintenance burden, and the thread never converged on one canonical, widely-endorsed implementation.
+- `asyncio`'s own standard pattern naturally supports running several tasks (and even several subprocesses) concurrently via `asyncio.gather`, which the tagged-queue approach builds on top of.
+
+## Pros / strengths
+
+- Honest about the pattern's real-world maintainability cost, not just its mechanical correctness — useful signal for a framework design decision, not just a working snippet.
+
+## Cons / limitations / caveats
+
+- No single reference implementation to point to; "write your own small, well-tested helper" was effectively the thread's own conclusion, which is not a strong endorsement of the pattern as a reusable abstraction.
+
+## Relevance to tai
+
+This is the direct reason `tai_test.py` does **not** implement a generic multi-stream-merge utility. Its actual need — combining a subprocess's stdout and stderr into one stream for pipe-mode tests — is fully satisfied by the much simpler `stderr=asyncio.subprocess.STDOUT` argument to `create_subprocess_exec`, which merges them at the OS/subprocess level before asyncio ever sees two separate streams, sidestepping the complexity this thread describes entirely.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,47 @@
+# Understanding asyncio.subprocess.Process garbage collection — discuss.python.org
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Understanding asyncio.subprocess.Process garbage collection |
+| Source URL | https://discuss.python.org/t/understanding-asyncio-subprocess-process-garbage-collection/105973 |
+| Source publisher / author | Python Discourse community |
+| Source type | forum thread |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+A Discourse thread examining what happens to a still-running `asyncio.subprocess.Process` object when it's garbage collected. The stdlib documentation states the child gets killed as a safety net in that case — but a forum participant reported observing output continuing to appear after the "owning" script had already finished, suggesting this safety net is not reliably instantaneous or complete in practice.
+
+## Key findings
+
+- `asyncio.subprocess.Process`'s own documentation states that if the process object is garbage collected while the process is still running, the child process will be killed — a documented safety net, not an accident of implementation.
+- Despite that documented behavior, a thread participant reported a case where a subprocess's "Step" output kept appearing after the main script had already exited, implying the GC-triggered kill either didn't fire promptly or didn't fully suppress output in that instance.
+
+## Pros / strengths
+
+- A concrete counter-example to "just let Python's GC clean it up" as a cleanup strategy — directly useful as evidence against relying on implicit cleanup.
+
+## Cons / limitations / caveats
+
+- A single forum report of unexpected behavior, not a reproduced, isolated bug report with a minimal test case — the exact conditions that produced it were not independently verified in this research pass.
+
+## Relevance to tai
+
+Reinforced the decision that `tai_test.py.TestCase.execute()` must explicitly call `await proc.terminate()` for every spawned process in its `finally` block, regardless of whether the test passed, failed, or was cancelled — never relying on Python's garbage collector or process-object destruction to clean anything up, consistent with the companion finding in `bpo-wait-for-timeout-leaves-process-alive.md` that a bare timeout alone doesn't guarantee cleanup either.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Your Subprocesses Outlive Your Program. Here's How to Kill Them For Real.
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Your Subprocesses Outlive Your Program. Here's How to Kill Them For Real. |
+| Source URL | https://dispatch-blog.hashnode.dev/your-subprocesses-outlive-your-program-here-s-how-to-kill-them-for-real |
+| Source type | blog post |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio subprocess timeout kill process group" search query — title strongly suggests it covers the exact same ground as the Tier 1 sources in this subject (`iannuccisolutions-timeout-process-group.md` etc.), but it was not individually opened or quoted, so it stays Tier 2.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# asyncio-subprocess docs — locale/version mirrors
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | asyncio subprocess (Russian locale, Python 3.16) |
+| Source URL | https://docs.python.org/ru/3.16/library/asyncio-subprocess.html |
+| Source type | standard (mirrored stdlib documentation) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio merge multiple streams" search query: several locale/version mirrors of the same stdlib `asyncio-subprocess` documentation page (already covered in English at Tier 1 in `python-docs-asyncio-subprocess.md`) all appeared in the same result set — Turkish (https://docs.python.org/tr/3.16/library/asyncio-subprocess.html), Polish (https://docs.python.org/pl/3.16/library/asyncio-subprocess.html), Traditional Chinese for Python 3.7 (https://docs.python.org/zh-tw/3.7/library/asyncio-subprocess.html), and a gitverse.ru mirror of the 3.9 branch's `.rst` source (https://gitverse.ru/githubmirror/cpython/tag/3.9/Doc/library/asyncio-subprocess.rst). These are redundant translations/mirrors of the same source document, not independent sources, logged together as one card.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (redundant locale/version mirrors of a Tier 1 source). |
@@ -0,0 +1,28 @@
+# Python 3.6.1 asyncio-subprocess docs (documentation.help mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | 18.5.6. Subprocess — Python 3.6.1 Documentation |
+| Source URL | https://documentation.help/Python-3.6.1/asyncio-subprocess.html |
+| Source type | standard (mirrored stdlib documentation) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio subprocess timeout kill process group" search query — an older-version (3.6.1) mirror of the same stdlib documentation already covered at Tier 1 (current version) in `python-docs-asyncio-subprocess.md`. Logged as a redundant, older-version mirror.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (older-version mirror of a Tier 1 source). |
@@ -0,0 +1,47 @@
+# execa termination.md — cross-language prior art (Node.js)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | execa — termination documentation |
+| Source URL | https://github.com/sindresorhus/execa/blob/78edcb9f2ba4d52ee3e28a499544b038c1cc3f99/docs/termination.md |
+| Source publisher / author | sindresorhus (execa project, Node.js) |
+| Source type | repository (documentation) |
+| Source date (published) | Unknown — not stated (pinned to a specific commit) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | Medium |
+| Status | Active |
+
+## Summary
+
+execa is a well-regarded Node.js process-execution library, not Python — included here deliberately as cross-language prior art rather than a Python-specific source. Its termination documentation describes the same terminate-then-escalate-to-kill pattern found in the Python-specific sources in this subject, plus an explicit warning against relying on garbage collection for process cleanup.
+
+## Key findings
+
+- execa documents the same two-stage termination approach (a polite signal first, a forceful one after a grace period) as the Python sources in this subject, suggesting this is a language-agnostic, generally-accepted pattern for process lifecycle management rather than a Python-specific idiom.
+- Emphasizes explicit, deliberate process-tree cleanup as a design principle, independent of any particular runtime's garbage collector.
+
+## Pros / strengths
+
+- Cross-language convergence: that an unrelated ecosystem (Node.js) arrives at the same termination pattern independently is a meaningfully stronger signal than one more Python source saying the same thing.
+
+## Cons / limitations / caveats
+
+- Not a Python source at all — none of its specific API details (`execa`'s own function signatures, option names) transfer directly to `tai_test.py`; only the general pattern does. This dossier is explicit about that distinction so it isn't mistaken for Python-specific guidance.
+
+## Relevance to tai
+
+Served as independent, cross-ecosystem confirmation that `tai_test.py`'s terminate-then-kill-then-reap design (see `iannuccisolutions-timeout-process-group.md` and `alexandra-zaharia-kill-subprocess-children-timeout.md`) is sound general practice, not an idiosyncratic Python-only convention.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# Gaudi merge request !1605 — diff view
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Gaudi merge request !1605 (diffs view) |
+| Source URL | https://gaudi.web.cern.ch:8443/gaudi/Gaudi/-/merge_requests/1605/diffs |
+| Source type | repository (merge request diff view) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "python integration test framework design base class" search query — the diff view of the same Gaudi merge request already analyzed at Tier 1 in `gaudi-subprocess-base-test.md`. Logged as a redundant view of the same source rather than an independent one.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed (alternate view of a Tier 1 source). |
@@ -0,0 +1,49 @@
+# CERN Gaudi — SubprocessBaseTest / GaudiExeTest
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Gaudi merge request !1605 (SubprocessBaseTest / GaudiExeTest), and companion doxygen source page |
+| Source URL | https://gitlab.cern.ch/gaudi/Gaudi/-/merge_requests/1605 |
+| Source publisher / author | CERN (Gaudi physics-software framework project) |
+| Source type | repository (merge request + generated source documentation) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+CERN's Gaudi framework (used across large physics experiments) includes a `SubprocessBaseTest` base class and a `GaudiExeTest` subclass for running and verifying subprocess-based tests. Test authors configure tests by setting class attributes (command, environment, timeout, expected return code) rather than writing imperative test logic, with an overridable `preprocessor` hook for customizing output handling. This companion source (`gaudi.web.cern.ch/doxygen/.../_base_test_8py_source.html`) is the generated source documentation for the same base class.
+
+## Key findings
+
+- `SubprocessBaseTest` is explicitly documented as providing "the setup and utility methods for ensuring tests run in a consistent environment" — the test author's job is reduced to declaring configuration, not reimplementing process management per test.
+- Configuration happens through class attributes: command, environment, timeout, and expected return code are all named, documented fields on the test class.
+- Output handling is customizable via an overridable `preprocessor` attribute on `GaudiExeTest`, letting a subclass change how reference-output comparison works without touching the runner itself.
+
+## Pros / strengths
+
+- A mature, battle-tested framework used in large, real scientific-computing codebases — strong evidence this "declarative base class + override hooks" shape scales to many tests written by many different authors over time, which is exactly the goal stated for `tai_test.py` ("a structure that scales and will be allowed [to be] followed").
+
+## Cons / limitations / caveats
+
+- Domain-specific to physics-software testing (comparing program output against reference files); not every detail (e.g. reference-file resolution relative to the test's own location) was adopted, since `tai_test.py`'s tests assert on vault state and search output rather than diffing against golden files.
+- Reviewed via its merge request description and generated source documentation, not a full read of the implementation's actual Python source.
+
+## Relevance to tai
+
+The direct architectural model for `tai_test.py.TestCase`: class-level attributes (`name`, `timeout`, `mode`) instead of constructor boilerplate, and override hooks (`setup`/`run`/`verify`/`teardown`) instead of one monolithic test method — mirroring Gaudi's class-attribute configuration plus its overridable `preprocessor` hook.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,50 @@
+# gem5 test infrastructure — Timer-based timeout + typed exceptions
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | tests: Add test infrastructure as a Python module (commit), and companion helpers.py |
+| Source URL | https://git.sanchayanmaity.net/sanchayanmaity/gem5/commit/f385adc8af744e7f6b78ff9adafd9c3ecf65ce68 |
+| Source publisher / author | gem5 project (computer architecture simulator) |
+| Source type | repository (commit + source file) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+A commit adding Python test infrastructure to the gem5 simulator project, together with its companion `tests/testing/helpers.py`. The helper uses a `threading.Timer` to enforce a timeout on a running subprocess: the timer's callback terminates the child process, then the surrounding code raises a dedicated exception carrying both the captured exit status and the process's output.
+
+## Key findings
+
+- Timeout enforcement pattern: `Timer(timeout, on_timeout_handler)` started before `communicate()`-ing with the process, cancelled afterward if the process finished in time.
+- On timeout, the handler terminates the child and a dedicated exception type is raised carrying the captured status and output together — the caller doesn't have to separately go fetch output after catching a generic timeout error.
+- gem5's newer test framework (noted in the same research pass) further splits each test into a "run" stage and a "verify" stage, where verify units are automatically skipped if their corresponding run stage didn't execute.
+
+## Pros / strengths
+
+- The "exception carries the captured output" design is directly actionable and immediately reusable — it solves the exact problem of "how do you debug a timed-out test" by attaching the evidence to the failure itself rather than requiring separate log inspection.
+- The run/verify stage split is a clean idea for keeping a test's "did it crash" question separate from "did it produce the right result."
+
+## Cons / limitations / caveats
+
+- Uses `threading.Timer`, a synchronous/thread-based mechanism, not `asyncio.wait_for` — `tai_test.py` adapted the *idea* (typed exception carrying output) to an asyncio-native mechanism (`asyncio.wait_for` plus try/except) rather than reusing gem5's thread-based implementation directly.
+- Reviewed via commit metadata and the helper file's described behavior, not gem5's full test suite or its actual usage patterns in practice.
+
+## Relevance to tai
+
+The direct model for `tai_test.py`'s exception hierarchy: `TestTimeout`, `TestCrashed`, and `TestAssertionFailed` all subclass `TaiTestError`, which carries a `transcript` list — so a failing test's exception *is* the debugging evidence, exactly matching gem5's "exception carries status and output" pattern, just built on `asyncio.wait_for`/try-except instead of `threading.Timer`.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# BunkerWeb tests/Test.py
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | Test.py (BunkerWeb) |
+| Source URL | https://gitea.com/palmcoasty/bunkerweb/src/branch/master/tests/Test.py |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "python integration test framework design base class" search query as another real project's custom `Test` base class; not individually opened or quoted — the Tier 1 architectural models used for this subject's conclusion are Gaudi, gem5, and oslotest instead.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# distributedcloud/dccommon/subprocess_cleanup.py — StarlingX distcloud
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | subprocess_cleanup.py (StarlingX distcloud) |
+| Source URL | https://gitea13.opendev.org:3081/starlingx/distcloud/src/commit/6435d6c3572562ff2e8e6b23075b4086d42ac8ae/distributedcloud/dccommon/subprocess_cleanup.py |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio create_subprocess_exec start_new_session" search query as a real project's dedicated subprocess-cleanup module; not individually opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,49 @@
+# sync: interactive launches strip the harness of its controlling terminal (start_new_session=True) · Issue #1 · anntnzrb/agents
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | sync: interactive launches strip the harness of its controlling terminal (start_new_session=True) |
+| Source URL | https://github.com/anntnzrb/agents/issues/1 |
+| Source publisher / author | GitHub user anntnzrb |
+| Source type | repository (issue) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+A GitHub issue documenting a real, encountered bug: a test/automation harness launched an interactive child process with `start_new_session=True`, which left the harness without a controlling terminal and broke window-resize and Ctrl-C handling for the child. The issue includes a small probe script for diagnosing whether a child process actually has a controlling terminal.
+
+## Key findings
+
+- `start_new_session=True` makes the child a new session leader; if that child is then given a pty as stdin/stdout/stderr, whether the pty becomes its *controlling* terminal (in the POSIX job-control sense) is not automatic — the issue describes a concrete case where it did not, breaking SIGWINCH-based resize and tty-line-discipline Ctrl-C-as-SIGINT.
+- The reporter's diagnostic approach: a probe script that checks `os.isatty(0)`, `os.tcgetpgrp(0)`, and whether `/dev/tty` can be opened, to confirm a child process actually has a controlling terminal rather than just an open pty fd.
+
+## Pros / strengths
+
+- A real, lived-through failure report rather than theoretical speculation — exactly the kind of pitfall that's easy to get subtly wrong when combining `start_new_session=True` (needed for safe process-group-wide `killpg` cleanup) with pty-based spawning (needed for `isatty()`-correct interactive behavior).
+- The diagnostic probe script is a concrete, reusable technique for anyone needing to verify controlling-terminal status.
+
+## Cons / limitations / caveats
+
+- A single GitHub issue report, not a kernel/POSIX specification — the exact conditions under which a session leader's first terminal open becomes its controlling terminal can depend on how the fd was obtained (opened directly by the child vs. inherited already-open from the parent), and this issue doesn't fully disambiguate that for the inherited-fd case `tai_test.py` actually uses.
+- No resolution/fix is confirmed as verified in this research pass (the issue's eventual outcome was not reviewed).
+
+## Relevance to tai
+
+Directly shaped `tai_test.py`'s documented, accepted limitation: its pty mode does not explicitly call `ioctl(TIOCSCTTY)`, so controlling-terminal/job-control semantics (SIGWINCH forwarding, Ctrl-C-as-SIGINT from the tty line discipline) are not guaranteed. This was judged acceptable because `tai.py`'s own code only checks `sys.stdin.isatty()` (a property of the fd itself, unaffected by session/controlling-terminal status) and `tai_test.py`'s tests only script line-based input/output, never relying on resize or terminal-generated signals.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,50 @@
+# Non blocking file reader for python asyncio · GitHub Gist
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | Non blocking file reader for python asyncio |
+| Source URL | https://gist.github.com/nilp0inter/5f400b6afb6df7c0b553 |
+| Source publisher / author | GitHub user nilp0inter |
+| Source type | repository (gist) |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+A GitHub gist demonstrating the correct way to read stdin (or any fd) without blocking the asyncio event loop: use `loop.add_reader(fd, callback)` where the callback does a raw `os.read(fd, n)`, never a call through Python's buffered `sys.stdin` object, which blocks regardless of `add_reader`.
+
+## Key findings
+
+- Calling `sys.stdin.read()` inside an `add_reader` callback still blocks, because Python's buffered stdin object waits for more data internally — `add_reader` only tells the event loop the fd is readable, it does not change how a buffered read call behaves.
+- The correct pattern is `os.read(fileno, n)` on the raw file descriptor inside the callback.
+- On EOF (an empty read), the callback should call `loop.remove_reader(fileno)` to stop watching the fd.
+
+## Pros / strengths
+
+- Identifies a genuine, easy-to-make mistake (buffered read inside a non-blocking callback) with a precise fix, backed by a reported working example.
+- The pattern is minimal and requires no third-party dependency — pure stdlib (`os`, `asyncio`).
+
+## Cons / limitations / caveats
+
+- A gist, not an authoritative reference — no discussion of edge cases like partial reads mid-line or how this interacts with terminal raw/cooked mode.
+- Only covers the read side; doesn't address writing back to the child or coordinating with a separate output stream.
+
+## Relevance to tai
+
+This is the exact pattern `tai_test.py`'s `StdinBridge._on_readable()` implements: `os.read(self._fd, 4096)` inside an `add_reader` callback, buffering until a newline, and calling `self.stop()` (which internally calls `loop.remove_reader`) on an empty read. Using `sys.stdin.read()` instead would have silently reintroduced blocking behavior that defeats the entire point of the non-blocking design.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# h0lley/nonBlockingStdin — GitHub
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | nonBlockingStdin |
+| Source URL | https://github.com/h0lley/nonBlockingStdin |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio non-blocking stdin read" search query as a small repository dedicated to exactly this problem; not individually opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,49 @@
+# mcp-remote-py stdio_jsonl.py — stdin bridged via loop.connect_read_pipe
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Dossier |
+| Tier | 1 |
+| Source title | mcp_remote_py/stdio_jsonl.py |
+| Source URL | https://glama.ai/mcp/servers/@elphinsnow/mcp-remote-py/blob/8ea9ac8b79f7ad844362b51b53f354834c9f5828/mcp_remote_py/stdio_jsonl.py |
+| Source publisher / author | GitHub user elphinsnow (mcp-remote-py project), via glama.ai mirror |
+| Source type | repository |
+| Source date (published) | Unknown — not stated |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | web search synthesis |
+| Confidence | High |
+| Status | Active |
+
+## Summary
+
+Source code from an MCP (Model Context Protocol) server implementation showing a Unix-only, thread-free pattern for bridging real stdin into asyncio: build an `asyncio.StreamReader` plus a `StreamReaderProtocol`, then call `loop.connect_read_pipe(lambda: protocol, sys.stdin.buffer)`. On Windows, the same codebase falls back to a blocking-readline-in-a-thread approach instead.
+
+## Key findings
+
+- `loop.connect_read_pipe(protocol_factory, pipe)` is the mechanism that turns an arbitrary readable file object into a proper `asyncio.StreamReader`-backed stream, integrated with the event loop's own backpressure and scheduling — not just a raw `add_reader` callback.
+- This technique is explicitly Unix-only in the source reviewed; the same project uses a different (thread-based) strategy on Windows, acknowledging the platform split rather than pretending one approach covers both.
+
+## Pros / strengths
+
+- A concrete, working, real-world example of integrating stdin into asyncio with no background thread — directly reusable technique, not just a theoretical description.
+- The explicit Windows fallback shows the author understood and documented the technique's platform limits rather than hiding them.
+
+## Cons / limitations / caveats
+
+- The dossier reflects a synthesis of this one file's approach, not a full read of the surrounding MCP server codebase or its test coverage.
+- Applies the technique to real stdin; `tai_test.py` adapts the same mechanism to a different fd (a pty master), which was not something this source itself demonstrated — the adaptation is `tai_test.py`'s own design step, not something directly sourced here.
+
+## Relevance to tai
+
+This is the direct technical basis for `ManagedProcess.start()`'s pty-mode branch: rather than manually polling a pty master fd with raw `add_reader` callbacks and hand-rolled buffering, it wraps the master fd in an `asyncio.StreamReader` via `loop.connect_read_pipe(lambda: protocol, self._master_file)`, giving `wait_for_pattern()`/`drain_until_eof()` a uniform, native `StreamReader.read()` interface identical to the one `asyncio.subprocess.PIPE` streams already provide in pipe mode. This is what let `tai_test.py` expose one interface for both transports instead of two different ones.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Initial dossier created. |
@@ -0,0 +1,28 @@
+# test_local_interrupt_cleanup.py — hermes-agent
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | test_local_interrupt_cleanup.py |
+| Source URL | https://download.hermesedi.duckdns.org/.hermes/hermes-agent/tests/tools/test_local_interrupt_cleanup.py |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio create_subprocess_exec start_new_session" search query — a test file from another agent project specifically about interrupt/cleanup behavior; not individually opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# OpenBB CLI test_session.py
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | test_session.py (OpenBB CLI tests) |
+| Source URL | https://huggingface.co/spaces/CatPtain/OpenBB/blob/main/cli/tests/test_session.py |
+| Source type | repository |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio subprocess pty interactive CLI testing" search query as an example of CLI session testing code in a real project; not individually opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
@@ -0,0 +1,28 @@
+# rag-code-assistant: asyncio-subprocess.html (doc mirror)
+
+## Metadata
+
+| Field | Value |
+|---|---|
+| Institute | Molodetz Institute — Research & Retrieval Division |
+| Subject | async-pty-process-testing |
+| Document type | Source Citation Card |
+| Tier | 2 |
+| Source title | asyncio-subprocess.html |
+| Source URL | https://huggingface.co/spaces/parthtamu/rag-code-assistant/blob/main/docs/asyncio-subprocess.html |
+| Source type | repository (mirrored documentation) |
+| Date researched | 2026-10-09 |
+| Researched by | tai (agent), model: Claude Sonnet 5, on behalf of retoor |
+| Research method | Search aggregator result listing (not independently opened or quoted) |
+| Confidence | Not independently verified |
+| Status | Active |
+
+## Why it's here
+
+Surfaced by the "asyncio subprocess pty interactive CLI testing" search query as another mirror/bundling of the stdlib asyncio-subprocess documentation (inside an unrelated RAG-assistant project's doc bundle); not individually opened or quoted during this research pass.
+
+## Changelog
+
+| Date | Change |
+|---|---|
+| 2026-10-09 | Logged as consulted-but-not-analyzed. |
--- a/Show More
+++ b/Show More