The Research Archive

# labs/research_archive.py
from dataclasses import dataclass, field
from datetime import datetime


@dataclass
class ResearchNote:
    title: str
    content: str
    tags: list[str] = field(default_factory=list)
    created_at: str = ""
    references: list[str] = field(default_factory=list)

    def __post_init__(self) -> None:
        if not self.created_at:
            self.created_at = datetime.now().isoformat(timespec="seconds")


if __name__ == "__main__":
    note = ResearchNote(
        "Whisper invents words on silence",
        "A near-silent buffer transcribes as 'Thank you.' Gate on RMS before calling the model.",
        tags=["stt", "gotcha"],
    )
    print(note.title)
    print(f"stamped {note.created_at}, tags {note.tags}")

$ uv run python labs/research_archive.py
Whisper invents words on silence
stamped 2026-08-14T21:18:07, tags ['stt', 'gotcha']

Your timestamp will read differently, obviously, and that is the entire point of the two lines doing the work. __post_init__ runs once per instance, right after the generated __init__ finishes, so every note gets the time it was actually created. Write created_at: str = datetime.now().isoformat() instead and the call happens once, when Python reads the class, freezing a single moment into every note the program will ever make. The empty string is not padding either: it is a sentinel meaning "nobody supplied one", and stage 2 depends on it. timespec="seconds" drops six digits of microsecond nobody reads while keeping ISO-8601 order, where a plain string sort is also a chronological sort.

import json
from dataclasses import asdict
from pathlib import Path

ARCHIVE_PATH = Path("glados/data/research_archive.json")


class ResearchArchive:
    def __init__(self, path: Path) -> None:
        self.path = path
        self.notes: list[ResearchNote] = self._load()

    def _load(self) -> list[ResearchNote]:
        if not self.path.exists():
            return []
        return [ResearchNote(**record) for record in json.loads(self.path.read_text())]

    def _save(self) -> None:
        self.path.parent.mkdir(parents=True, exist_ok=True)
        self.path.write_text(json.dumps([asdict(n) for n in self.notes], indent=2))

    def add(self, note: ResearchNote) -> bool:
        if any(n.title == note.title for n in self.notes):
            return False
        self.notes.append(note)
        self._save()
        return True

$ uv run python labs/research_archive.py
stored: True
stored again: False
reopened from disk: 1 note, created 2026-08-14T21:18:07

$ head -8 glados/data/research_archive.json
[
  {
    "title": "Whisper invents words on silence",
    "content": "A near-silent buffer transcribes as 'Thank you.' Gate on RMS before calling the model.",
    "tags": [
      "stt",
      "gotcha"
    ],
    "created_at": "2026-08-14T21:18:07",

Two library calls carry the whole persistence layer. asdict walks a dataclass recursively and returns plain dicts, lists and strings, which is exactly what json.dumps accepts; ResearchNote(**record) splats a loaded dict back through the constructor. Neither _load nor _save names a single field, so adding author tomorrow means editing the dataclass and nothing else. Now watch the sentinel earn its keep: the saved dict already carries a created_at, so on reload the guard in __post_init__ sees a non-empty value and leaves the original time alone. Without that if, every restart would restamp the entire archive to the moment you opened it. The title check in add matters for the same reason: since _load runs first, a script that adds its notes on every run would otherwise duplicate them on every run, and a boolean return turns "already knew that" into an ordinary answer instead of an exception.

    def search(self, query: str) -> list[ResearchNote]:
        q = query.lower()
        return [
            n for n in self.notes
            if q in n.title.lower()
            or q in n.content.lower()
            or any(q in tag.lower() for tag in n.tags)
        ]

$ uv run python labs/research_archive.py
2 notes match 'silence':
  [2026-08-14T21:18:07] Whisper invents words on silence
  [2026-08-16T10:02:44] Silence threshold in the kitchen
0 notes match 'tts':

One comprehension, three places to look, and the lowering on both sides is what makes TTS, Tts and tts the same query. The any() clause reads "matches if any tag contains the query", so a note filed under ["stt", "gotcha"] comes back for either word. The second search returning nothing is the honest limit of substring matching, worth seeing early: stt and tts are one transposition apart and share no substring, so nothing here is clever enough to guess what you meant. There is no ranking either. Chapter 37 needed an ORDER BY because she has to pick one fact to put in a prompt; you get the list, and your eyes do the ranking.

# labs/research_archive.py — the last additions
EXPERIMENTS_DIR = Path("glados/data/experiments")


def import_experiments(archive: ResearchArchive, directory: Path = EXPERIMENTS_DIR) -> int:
    imported = 0
    for path in sorted(directory.glob("*.json")):
        exp = json.loads(path.read_text())
        note = ResearchNote(
            title=f"experiment: {exp['name']}",
            content=f"{exp['hypothesis']} | result: {exp['results'] or 'pending'}",
            tags=["experiment", exp["status"]],
            created_at=exp["created_at"],
            references=[str(path)],
        )
        if archive.add(note):
            imported += 1
    return imported


def main() -> None:
    archive = ResearchArchive(ARCHIVE_PATH)
    archive.add(ResearchNote(
        "Whisper invents words on silence",
        "A near-silent buffer transcribes as 'Thank you.' Gate on RMS before calling the model.",
        tags=["stt", "gotcha"],
    ))
    archive.add(ResearchNote(
        "Servo 4 stops five degrees short",
        "Right elbow reaches 175 deg on a 180 deg command. Treat 175 as its ceiling.",
        tags=["hardware", "calibration"],
    ))
    imported = import_experiments(archive)
    print(f"{len(archive.notes)} notes in the archive, {imported} imported this run")
    hits = archive.search("threshold")
    print(f"{len(hits)} notes match 'threshold':")
    for note in hits:
        print(f"  [{note.created_at}] {note.title}  {note.tags}")


if __name__ == "__main__":
    main()

$ uv run python labs/research_archive.py
5 notes in the archive, 3 imported this run
2 notes match 'threshold':
  [2026-07-02T14:08:31] experiment: silence threshold sweep  ['experiment', 'complete']
  [2026-08-16T10:02:44] Silence threshold in the kitchen  ['hardware', 'calibration']

$ uv run python labs/research_archive.py   # again, immediately
5 notes in the archive, 0 imported this run
2 notes match 'threshold':
  [2026-07-02T14:08:31] experiment: silence threshold sweep  ['experiment', 'complete']
  [2026-08-16T10:02:44] Silence threshold in the kitchen  ['hardware', 'calibration']

The lab notebook from chapter 25 has been writing one JSON file per experiment this whole time, and the sweeps from chapter 38 added more. Those files are structured already, so importing them is a rename of fields, not a parse. Two details make the import honest. The note carries the experiment's own created_at forward, so the guard from stage 1 declines to restamp it and the imported note lands on the timeline at the hour the work actually happened. And references holds the path to the full record, so the note is a pointer, not a second copy that can drift from the first. The second run is the payoff of the title check: it imports nothing, changes nothing, and one query now reaches across your experiments and your loose observations at once.