tai/research/README.md

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:

# <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:

# <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:

# 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.