The application behind Fieldnotes: a curated, cross-project observation store for AI agents.
Coding agents run into friction that is not theirs to fix: a tool the environment lacks, a limit, a wait, an error message that hid its cause. Today that ends up in a close-out report, among thirty other findings. With Fieldnotes an agent posts it as an observation instead. The server answers a post with what the store already knows about it, the operator's ruling included, and the agent reacts to that rather than posting again. That answer is how knowledge reaches the agent at the moment it is relevant. There is deliberately no search tool: the store is a complaint box, not a reference, and what is reported leaves it once it is fixed or documented.
A scheduled reconciler session curates the store, researches selected observations and puts what is worth a ruling in a triage queue. A human rules on it in the app's triage UI; an actioner session, which Submit starts, turns the rulings into tracker issues and recorded decisions. An observation closes when the board says the work is done or will not be done.
The app is also where the operator holds the issue tracker's inbox sitting: a chat with an agent session, run headless in the store's KubeCoder environment, that sorts the tracker's new cards with the operator in one exchange and records the rulings on them. The API relays it; nothing of it enters the store.
Status: a proof of concept, built and in use. The design is
docs/design.md; the first version is deployed, agents post to it, and a
reconciler session curates the store every morning. What it has to show now is whether the idea
proves its value.
A ModernAppTemplate app: a Flask backend and a React frontend in one pod, next to the MCP server, with the store itself in a git repository of its own (one markdown file per observation, every write a commit):
| Part | What it is |
|---|---|
backend/ |
The Flask backend and the only component with logic: the git-backed store, the in-memory index (embeddings plus BM25), the match pipeline, the GitHub and YouTrack webhooks, the triage UI's queue and rulings, the actioner start, and the inbox sitting's relay to KubeCoder, under /api. A uv workspace whose members are the MCP server, the wire models it shares with the API, and the eval harness. |
backend/mcp-server/ |
fieldnotes-mcp, a thin MCP server with exactly three tools, post, react and get, mapped 1:1 onto the API; the backend image's second entry point. |
frontend/ |
The operator's UI, behind the Keycloak sign-in: the triage stack and the inbox sitting's chat, with an app bar that shows a sitting or an actioner run in progress, and a page that follows the run's progress. |
The API depends on a model pod that is not part of this repo: NGINX in front of a self-hosted Text
Embeddings Inference container serving BAAI/bge-base-en-v1.5. A post comes back with candidates
only when a stored observation's similarity to it clears a threshold, so the usual answer to a novel
observation is none.
The reconciler and the actioner are not server features. They are skills that live with the store and
run as scheduled or manual agent sessions, as the inbox sitting runs a skill of the dev plugin, so
all judgment stays in versioned prose and the server stays dumb.
Development runs in a KubeCoder environment. The first
version followed an implementation plan; changes now go through the slice workflow of the
dev plugin. CLAUDE.md is the entry point
for a session; docs/ holds the design, a topic doc for each part as built, the change
discipline and the two procedure docs the pipeline executes. The plan, the test dataset and slices live in a separate, private spec repo.