All posts
Article·9 min read

How To Build An Obsidian-Compatible Wiki That AI Agents Can Maintain

Build an Obsidian-compatible AI agent knowledge base by separating raw inbox items, canonical sources, claims, evidence, questions, contradictions, and compiled cache files.

An AI-maintained wiki should not be a pile of smart summaries. It should be a small evidence system: raw inputs come in, canonical sources are created, claims are extracted, evidence stays attached, questions remain visible, contradictions are reported, and agents read compiled cache files instead of rummaging through everything from scratch.

That is the useful version of an Obsidian AI workflow. Obsidian remains the human-readable markdown surface. Git remains the change log. Agents do the repetitive maintenance work, but only inside a structure that makes provenance hard to lose.

The design below is based on the local Agent Wiki pattern: an Obsidian-compatible vault that separates sources, claims, evidence, relations, questions, contradictions, syntheses, reports, and generated machine-facing caches.

Start with folders that force good behavior

The folder structure is the product. If sources, summaries, claims, and generated files all live in the same place, the wiki will rot as soon as an agent starts "helpfully" rewriting things.

Use this layout for a standalone vault:

wiki/
  AGENTS.md
  WIKI.md
  INBOX.md
  overview.md
  index.md

  _inbox/
  raw/
  _attachments/
  _archive/

  sources/
    parts/
  entities/
  concepts/
  claims/
  syntheses/
  questions/
  reports/

  _system/
    cache/
    indexes/
    logs/

Use the same internal layout when the wiki lives inside a larger project:

workspace/
  docs/
  research/
  decisions/
  wiki/
    sources/
    entities/
    concepts/
    claims/
    questions/
    reports/
    _system/

The important rule is simple: the wiki owns wiki/, not the rest of the workspace. In workspace mode, agents can discover source candidates outside the wiki, but the original workspace files stay in place. They only become evidence after an agent creates a canonical source page under wiki/sources/.

Write the contract before you invite agents in

Put two short rule files at the root:

  • AGENTS.md tells agents how to behave: preserve source material, do not rewrite human-authored content casually, use stable IDs, log maintenance work, and do not hand-edit generated cache files.
  • WIKI.md tells agents the schema: page types, required frontmatter, status values, source types, evidence rules, relationship predicates, and examples.

Do not rely on a vague prompt like "maintain this vault carefully." Agents need local rules they can read every time. The contract should say which folders are canonical, which are generated, and which files are allowed to be modified during each workflow.

For routine use, the agent should usually read AGENTS.md and the relevant sections of WIKI.md. Keep the full specification available for implementation work, but do not make every small maintenance task load a giant design document.

Move inbox items into canonical sources

The inbox is not evidence. It is a queue.

Drop raw notes, transcripts, links, copied articles, meeting notes, PDFs, screenshots, and research captures into _inbox/. Then have an agent promote each item into a source page under sources/.

For plain text or Markdown, preserve the original body. For converted documents, record conversion details when you have them. After a successful promotion, move the raw file to raw/ so _inbox/ only contains unprocessed work.

A source page should have frontmatter like this:

id: source.2026-07-01.article.example-ai-workflow
pageType: source
title: Example AI Workflow
status: unprocessed
sourceType: article
sourceRole: whole
originUrl: https://example.com/ai-workflow
originPath: raw/2026-07-01-example-ai-workflow-original.md
retrievedAt: 2026-07-01
createdAt: 2026-07-01
updatedAt: 2026-07-01
aliases: []
tags: []
attachments: []

The body below that frontmatter should contain the source text or a faithful converted version of it. The source page is where evidence can point. The raw retained file is useful for audit and recovery, but it is not the main reasoning surface.

For very large sources, do not create one enormous Markdown page. Create a short parent source and split the source into sources/parts/ with stable locators such as chapter names, page ranges, timestamps, or section headings. Evidence citations become much more useful when they can point to a specific part instead of a 90,000-word blob.

Extract claims separately from source pages

After source pages exist, extract knowledge primitives. This is the step that turns a readable vault into an agent-usable knowledge base.

Extract:

  • entities/ for durable things: people, organizations, products, projects, systems, places, events, documents
  • concepts/ for reusable ideas: workflows, methods, definitions, standards, checklists, principles
  • claims/ for atomic propositions that can be evaluated
  • questions/ for unresolved uncertainties and research gaps
  • relations in frontmatter when one object depends on, uses, contradicts, supports, or belongs to another

Keep claims atomic. This is bad:

Acme launched the product in 2024 and customers loved it.

Split it:

Acme launched the product in 2024.
Customers responded positively to the product.

Those two statements need different evidence. One may be a dated historical claim. The other may be an interpretive or descriptive claim that needs survey data, reviews, interviews, sales notes, or some other support.

A claim page can look like this:

id: claim.descriptive.example-workflow-separates-sources
pageType: claim
title: Example Workflow Separates Sources From Claims
status: unverified
claimType: descriptive
text: The example workflow separates canonical source pages from extracted claim pages.
confidence: 0.60
sourceIds:
  - source.2026-07-01.article.example-ai-workflow
evidence:
  - id: evidence.quote.supports.8f3a12c9
    kind: quote
    relation: supports
    sourceId: source.2026-07-01.article.example-ai-workflow
    excerpt: "Promote raw inbox items into source pages, then extract claims separately."
createdAt: 2026-07-01
updatedAt: 2026-07-01
aliases: []
tags: []

Notice the modest default confidence. A source saying something does not make it true. It only means the source made the claim. The wiki becomes more trustworthy when it preserves that distinction instead of laundering every excerpt into certainty.

Treat evidence as a bounded record

Evidence should answer three questions:

  1. Where did this support or challenge come from?
  2. What exact excerpt, locator, or observation matters?
  3. How does it relate to the claim?

Use evidence relations like supports, weakens, contradicts, and context_only. That last one matters. A source may mention a topic without proving the claim you care about. Marking that as context keeps agents from overstating the case later.

Evidence can live on claim pages or in structured frontmatter that your compiler understands. Either way, keep it close enough to the claim that an agent can reconstruct the reasoning path without rereading the entire vault.

Track contradictions instead of smoothing them away

Most note systems turn disagreement into mush. A stronger wiki preserves the conflict.

Contradictions can come from:

  • two sources giving different dates
  • one claim marked supported while a related claim is contested
  • evidence that directly contradicts a claim
  • competing definitions of the same concept
  • changed product behavior across versions or time periods

In the Agent Wiki pattern, v2 does not require authors to maintain a separate contradiction page for every conflict. Contradictions are primarily surfaced through compiled outputs and reports. That is a practical choice: agents can flag conflicts from structured claim and evidence records, then a human or maintenance agent can decide whether the issue deserves a durable synthesis or question page.

The workflow should be:

  1. Preserve both claims.
  2. Attach evidence to each side.
  3. Mark the weaker, stale, or contradicted claim honestly when you know enough.
  4. Add a question page when the contradiction needs research.
  5. Let the compile step surface unresolved conflicts in reports/contradictions.md and _system/cache/contradictions.json.

Do not ask the agent to "resolve" contradictions by picking the nicer-sounding answer. Ask it to make the disagreement legible.

Keep questions first-class

Questions are not failures. They are the maintenance queue for knowledge.

Create a questions/ page when a source raises a real unknown:

id: question.research.example-workflow-automation-boundary
pageType: question
title: What parts of the workflow should remain human-approved?
status: open
createdAt: 2026-07-01
updatedAt: 2026-07-01
sourcePages:
  - sources/2026-07-01-article-example-ai-workflow.md
relatedPages:
  - concepts/agent-maintained-wiki.md
aliases: []
tags: ["workflow", "approval"]

The body should say what is unknown, why it matters, and what would count as an answer. When the question is resolved, update its status. Do not delete it. The resolved question is part of the wiki's memory.

Compile the wiki into an agent-readable cache

Humans can browse Obsidian. Agents need compact, normalized context.

After sources, claims, questions, or relationships change, run a compile step that regenerates machine-facing files from canonical pages. In the Agent Wiki layout, the compile pipeline writes files like:

_system/cache/pages.json
_system/cache/claims.jsonl
_system/cache/relations.jsonl
_system/cache/agent-digest.json
_system/cache/contradictions.json
_system/cache/questions.json
_system/cache/timeline-events.json
_system/cache/source-index.json

_system/indexes/alias-index.json
_system/indexes/tag-index.json
_system/indexes/id-to-path.json
_system/indexes/path-to-id.json
_system/indexes/pagetype-index.json

It can also regenerate human-facing maintenance reports:

reports/open-questions.md
reports/contradictions.md
reports/low-confidence.md
reports/claim-health.md
reports/stale-pages.md
reports/evidence-gaps.md

The rule is non-negotiable: do not hand-edit _system/cache/, _system/indexes/, or deterministic reports as if they are source material. Fix the canonical pages, then compile again.

This gives agents a fast path. Instead of reading every Markdown file in the vault, an agent can load agent-digest.json, claims.jsonl, questions.json, and the relevant source pages.

Add a maintained overview, but do not treat it as evidence

An overview.md page is useful. It gives humans a readable landing page and gives agents orientation before they dive into the cache.

But it should not become a source of truth. Treat overview prose as a map, not the territory. If the overview says something important, the supporting source, claim, evidence record, or synthesis page should exist elsewhere in the vault.

Use syntheses/ for durable cross-source interpretation: briefs, comparisons, timelines, decision memos, literature-style summaries, and analyses that need to preserve uncertainty. A synthesis can cite sources, claims, questions, and related pages. It should say plainly where the evidence is weak or contested.

Schedule maintenance as separate jobs

An agent-maintained wiki works best when maintenance is boring and repeatable.

Schedule small jobs instead of one giant "update everything" command:

Daily:
  - Process new _inbox/ items into source pages.
  - Extract primitives from source pages with status: unprocessed.
  - Compile the wiki and refresh reports.

Weekly:
  - Review open questions.
  - Review contradictions.
  - Review low-confidence claims and evidence gaps.
  - Refresh overview.md if the shape of the vault changed.

Monthly:
  - Audit stale pages.
  - Archive dead projects or obsolete syntheses.
  - Review whether the folder/schema contract still matches how the wiki is used.

If you use a CLI, have it print scheduled-agent prompts rather than pretending the CLI itself can judge sources. For example, one prompt can tell an agent to process inbox files. Another can tell it to extract primitives from unprocessed source pages. Another can compile and refresh the overview.

That separation keeps the responsibility clear:

  • CLI: scaffolding, validation, registry, health checks, cache generation
  • agent: reading sources, selecting claims, judging evidence, writing prose
  • human: approving local setup policy, resolving ambiguous decisions, correcting important mistakes

This is where the Seeds of Joy show up as building capability and iteration. The point is not to make a perfect wiki on day one. The point is to create a structure where each pass makes the system more capable: one source promoted, one claim clarified, one contradiction exposed, one cache regenerated, one better version than the last.

The minimum viable version

You do not need a giant product to start. You need a disciplined markdown vault.

Start with:

  1. Create the folders.
  2. Write AGENTS.md and WIKI.md.
  3. Drop one source into _inbox/.
  4. Promote it to sources/.
  5. Extract three claims, one concept, and one open question.
  6. Compile a tiny cache.
  7. Ask a fresh agent to answer a question using only the source page and compiled cache.

If the answer can cite the right source, distinguish evidence from interpretation, and notice the open question, the structure is working.

That is the real test. Not whether the vault looks impressive in graph view. Whether a tired future agent can enter the project, read the contract, load the cache, and avoid making a confident mess of your knowledge.