self-maintaining-wiki.md

A developer describes a pattern for an AI agent that autonomously builds and maintains a persistent personal wiki from work artifacts and external sources. The agent handles filing, linking, summarizing, and deduplication while the human focuses on work and questions. The system uses three storage layers—capture inbox, curated notes, and index—plus a configuration file to turn a generic agent into a disciplined knowledge base maintainer.

A pattern for an agent that captures, organizes, and maintains a personal knowledge base on its own. This is an idea file. It is meant to be handed to an agent platform Claude Code, Codex, OpenCode, or similar as a starting point. It describes the pattern, not a fixed implementation — the agent and the operator work out the concrete details together. Most of the knowledge produced while working with an agent evaporates into chat history: decisions and their rationale, hard-won fixes, reusable techniques, open threads to come back to. Plain retrieval systems upload files, retrieve chunks at query time don't help here either — they re-derive an answer from scratch on every question and accumulate nothing. This pattern is different. The agent builds and maintains a persistent wiki — a structured, interlinked set of markdown notes — out of two streams: the artifacts that surface while you work with it, and any external sources you choose to add. Knowledge is compiled once into durable notes and then kept current, rather than rediscovered per query. The cross-links are already in place, contradictions are already flagged, and the synthesis already reflects everything captured so far. The division of labor is the point. The agent owns the wiki: it does the filing, typing, linking, summarizing, deduplicating, and indexing — the bookkeeping that makes a knowledge base useful but that humans abandon. You do the work, supply the sources, and ask the questions. A common setup is the agent on one side and an Obsidian-style markdown editor on the other, so you can browse links and the graph while the agent edits. This is domain-independent. The same machinery serves personal tracking, long-running research, reading a book, team knowledge fed by meetings and threads, competitive analysis, course notes, or any context where knowledge accumulates over time and should be organized rather than scattered. Three storage layers plus one configuration file. Capture layer inbox . An append-only landing zone. Newly captured artifacts arrive here with provisional metadata and minimal processing. Writing here is cheap and never blocks, which keeps recall high. It is kept separate from the curated layer so half-formed captures never pollute the clean notes. If external sources are also ingested, keep the immutable originals in their own location — the inbox holds extracted notes, not the source files themselves. Curated layer the wiki . The clean layer the agent maintains: atomic, typed, domain-organized markdown notes that are interlinked. This is what a human browses. The agent creates pages, updates them as new material arrives, and keeps cross-references consistent. Index layer. Generated navigation: a content catalog manifest , maps of content, and a chronological log. This lets the agent and the human find things without scanning every note. The configuration file e.g. CLAUDE.md or AGENTS.md . The conventions and workflows: directory layout, the metadata schema, and how to capture, curate, answer, and lint. This is what turns a generic agent into a disciplined maintainer; it is co-evolved over time as conventions settle. An illustrative layout adapt freely : wiki/ inbox/ raw captures with provisional metadata review/ low-confidence captures awaiting a human decision notes/ curated, domain-organized notes <domain-a / <domain-b / index/ manifest + maps of content log.md append-only chronological record AGENTS.md conventions and workflows Organize curated notes primarily by domain, and carry the note's type in metadata rather than in the folder name. Cross-cutting types — reusable procedures, or open tasks — can additionally be surfaced through their own map of content so they stay browsable. Every note carries YAML frontmatter. This is what both the agent's index and the human's tools graph view, frontmatter queries read. --- id: 2026-06-30-short-slug type: knowledge decision | knowledge | recipe | task domain: domain-a, domain-b a list, so cross-cutting notes belong to several status: curated raw | curated | archived confidence: 0.9 set at capture; informs review routing tags: tag-a, tag-b links: " domain-a/related-note " source: <where it came from created: 2026-06-30 updated: 2026-06-30 --- The type of an artifact is a judgment about the structure of what happened, inferred from content — never a label the user has to type. A reasonable default set: decision — a choice made among alternatives, recorded with its rationale. knowledge — a fact or observation tied to a specific context; descriptive and one-off. recipe — a generalized, reusable procedure that applies to a class of situations; prescriptive and cross-cutting. task — an open future action whose outcome is not yet realized. Adapt the set per domain. The distinction that matters most is knowledge versus recipe: knowledge is descriptive and situation-bound, a recipe is prescriptive and reusable. Keeping them apart prevents reusable techniques from drowning in one-off notes. Capture automatic . At the end of a working session the agent reviews the conversation, applies a significance filter to decide what is worth keeping most chatter is not , and writes provisional, typed notes into the inbox. Capture should be safe to run more than once without producing duplicates. External sources enter the same way: you hand a source to the agent and it extracts and files notes from it. Curate maintenance pass . Periodically — on demand or on a schedule — the agent promotes inbox items into the curated layer in a single pass: it finalizes each note's type, deduplicates, splits compound notes into atomic ones, files them under the right domain, adds cross-links, promotes recurring knowledge into recipes, and rebuilds the index. Because the step operates over shared state the new notes, the link graph, the catalog , keep it as one coherent pass rather than many disconnected stages. Query. Questions are answered index-first: the agent reads the catalog, pulls only the few relevant notes, and synthesizes a concise answer that cites the notes it used and returns links rather than dumping full text. Keeping answers terse and reference-based is a deliberate property — it protects both the context window and the reader from overload. Good answers a comparison, an analysis, a newly discovered connection should be filed back as notes so that explorations compound just like captured artifacts. Lint. Periodically health-check the wiki: contradictions between notes, claims superseded by newer material, orphan notes with no inbound links, concepts referenced but lacking a page, missing cross-links, and the backlog of low-confidence captures awaiting review. The agent can also propose questions to investigate and gaps worth filling. Classification happens twice, on purpose, to get both recall and precision. At capture it is fast, cheap, and provisional: the agent assigns a type and a confidence and files without blocking. This favors recall — nothing useful is lost for want of certainty. At curation it is authoritative: the agent re-checks each type against clear criteria and finalizes it, including the knowledge-to-recipe promotion. This favors precision. Ambiguous captures are never guessed silently. Anything below a confidence threshold is routed to the review area instead of the clean layer, and is surfaced during lint or curation as a short digest for a human to resolve. The threshold is the recall/precision dial: raise it to involve the human less and let automation decide more, lower it for tighter control. This keeps the system from quietly making lossy choices on genuinely ambiguous material — for example, a remark that is half an observation and half an open action, which could be filed as either type without the other half being lost. Catalog manifest . A lightweight list of every note — path, type, domain, tags, a one-line summary, and last-updated — small enough to load whole. The agent reads it first to decide which notes to open, then drills in. At moderate scale this replaces embedding-based retrieval entirely. Maps of content. Human-browsable hub pages: one per domain, plus a hub for each cross-cutting type reusable recipes, open tasks . These present the same structure the catalog encodes, but for the eye. Log. An append-only chronological record of captures, curation passes, queries, and lint runs. Give each entry a consistent dated header so the log is parseable with ordinary text tools, which makes "what happened recently" a one-line query. Connectivity rides on frontmatter plus wikilinks. The domain field is a list, so a genuinely cross-cutting note can belong to several domains at once. Explicit links record the relationships the agent is responsible for keeping consistent and repairing when they break. This is what lets both a graph view and the agent traverse from one domain into another instead of treating domains as silos. Markdown editor for browsing. The wiki is just markdown, so an Obsidian-style editor gives a graph view hubs and orphans at a glance and working backlinks for free. Search. At small scale the catalog is enough. As the wiki grows, add a local markdown search engine — for example a hybrid keyword/vector engine that runs on-device and is usable both as a CLI and as a native tool — or a simple homemade search script. Frontmatter queries generate live tables from the metadata; a markdown slide format can turn notes into decks; and because the wiki is a git repository, version history and branching come for free. Automatic capture can be wired to the agent platform's session-end hook so it runs without being asked. The expensive part of a knowledge base is the bookkeeping, not the reading or the thinking: keeping cross-links current, summaries fresh, contradictions flagged, and types consistent across many notes. People abandon wikis because that upkeep grows faster than the payoff. An agent does not get bored, does not forget to update a link, and can touch many files in a single pass, so the cost of upkeep approaches zero and the base stays alive as it grows. The human curates sources, directs the analysis, and asks good questions; the agent does everything else. The spirit is close to Vannevar Bush's Memex — a private, actively curated store where the trails between documents matter as much as the documents — with the maintenance problem finally handled by the agent. This document is abstract on purpose. The directory names, the metadata schema, the type set, the confidence thresholds, and the tooling all depend on the domain and the agent. Treat everything here as modular: keep what helps and drop what does not. Hand this file to an agent and instantiate a concrete version together.