notio: project memory¶

Sources & anchors

Stack component: projio
Canonical artifact: survey component 6 §Convergent patterns docs/log/{idea,task,result,meeting}/
Workshop session: Day-2 PM session 2
Outline: _outline.md §B

Frame¶

docs/log/{idea,task,result,...}/ as structured project memory; agent-activity trail; project memory as audit trail. The pain notio solves is why was this run produced?

The pain¶

A pipeline ran three weeks ago and produced derivatives/preprocess_ieeg/. Git knows what changed: a config bump, two new rules, a bug-fix in a script. DataLad knows which commits of which subdatasets were pinned at the time of the run. The git history does not know why the run happened. It does not know which idea the run was responding to, which issue had been filed against the previous output, which alternative configurations had been tried and rejected, or which downstream report the run was a prerequisite for.

The default mitigation is a docs/notes/ folder where someone — usually the original author, weeks after the fact — types up what they remember. By the time the project has three contributors and ten pipelines, the notes folder is either out of date or empty, and the why is gone.

notio replaces that single-purpose notes/ folder with a structured project memory: a small set of typed note categories, one file per note, named-with-a-timestamp, indexed automatically, and queryable through MCP.

The layout¶

Every projio-aware project carries the same skeleton under docs/log/:

docs/log/
├── idea/      # speculative captures — possibilities not yet committed to
│   ├── index.md
│   └── idea-<author>-<YYYYMMDD>-<HHMMSS>-<hash>.md
├── task/      # actionable units — scheduled or in flight
│   ├── index.md
│   └── task-<author>-<YYYYMMDD>-<HHMMSS>-<hash>.md
├── result/    # written-up outcomes — surveys, specs, decisions, retros
├── issue/     # filed problems — bugs, blockers, surprises
├── meeting/   # meeting notes
└── goal/      # longer-horizon plans with milestones

Each subdirectory has an auto-generated index.md listing its contents in reverse-chronological order. The naming convention <kind>-<author>-<timestamp>-<short-hash>.md makes every note globally unique and trivially sortable. The index.md is regenerated by notio_reindex(); a manual edit is not the source of truth.

Each note carries a YAML frontmatter with a short, predictable schema: title, date, timestamp, status (open, scheduled, done, archived), actionable: true|false, tags, optional project_primary, optional goal, and a prompt field for tasks that the agent runner will execute. Everything outside the frontmatter is free-form markdown.

The MCP surface¶

Five small MCP tools cover everyday use:

note_create(note_type, ...) scaffolds a new note in the right subdirectory with the timestamped name and the right frontmatter template.
note_list(note_type=...) returns the recent notes of a given kind.
note_read(path) returns a note's frontmatter and body as structured data.
note_search(query) semantic-searches across the corpus (the same corpus indexio also indexes).
note_resolve(note_id) resolves a partial timestamp or hash to the exact path.

Behind the tools, notes are plain markdown checked into git. There is no separate database, no daemon. The structure is in the layout and the frontmatter — both of which a human can read and edit by hand. The MCP tools exist so agents can navigate the corpus without grepping filenames.

Agent-activity trail¶

The docs/log/agent-activity.md file (auto-appended) records, per agent session, a one-paragraph summary of what was done, which task note was sourced, and which result note was produced. It is the running ledger of agent work. When a stranger asks "why was this commit made?", the answer is usually one click away: the commit references a task note, the task note references a source idea, and the result note records what was actually delivered.

This chapter is itself a notio result¶

The handbook chapter you are reading was produced by the agent system described in chapter 70-agentic. The chain is in the docs/log/ tree of this very repository:

The source idea (the proposal to write a stack-axis handbook) lives in docs/log/idea/.
The roadmap that ordered the drafting work into chapter-sized tasks lives in docs/log/result/result-arash-20260508-stack-axis-roadmap.md.
The task that scheduled the drafting of this chapter group lives in docs/log/task/task-arash-20260511-handbook-60-projio.md.
The completion record will land in docs/log/result/ once the drafts are checked in.

The chain is navigable: any reader can answer "why does the handbook have a 60-projio chapter, what shaped its scope, and which agent session wrote it?" by following four file references. The git-history-only answer to the same question is a date, a hash, and a commit message — accurate but unilluminating.

What the convention costs¶

The convention is not free. Every dispatched task creates at least one task note and usually one result note; that is a directory that grows monotonically. Stale tasks (status: scheduled that never executed) accumulate; the index files grow long. notio supplies a few hygiene tools (note_update(path, status="archived"), automatic re-index) but the long-term curation is social — the same as for any structured-log discipline.

The stack-axis survey records that all four study projects in the cohort keep docs/log/{idea,issue,task,result,meeting}/ with an index.md, though two of them (msol) have notio.enabled: false in config while still using the directory layout — an example of the enabled-flag drift the handbook is honest about.

What it gives you back¶

When notio is consistently used, the project's audit trail becomes queryable. "Why did preprocess_ieeg run on 2026-04-22?" resolves to a task note. "What was the alternative we discussed for the spike-sorter?" resolves to an idea note. "What did the May collaboration meeting decide?" resolves to a meeting note. The next chapter shows how pipeio plugs into the same structure to record which config and which commit produced which derivative output, closing the loop from idea to evidence.