The Knowledge Base That Remembers Its Sources
claude-obsidian is a local-first Agent Skills package and Claude Code plugin for building a source-cited Obsidian knowledge base. The question for this series is not simply how an agent can write more notes; it is how an AI-assisted knowledge system can become more useful over time without losing ownership, evidence, or the ability to recover from a bad change. Understanding that question gives readers a practical way to judge what the project does, what its safeguards actually cover, and where its promises stop.
When an AI note is not yet knowledge
A generated paragraph can be fluent and still be a poor knowledge artifact. It may omit the source that prompted it, flatten a disagreement into a confident sentence, or preserve a conclusion without the context needed to decide whether it still applies. It may also sit alone: searchable today, but disconnected from the related concepts, decisions, and questions that would make it useful later. The failure is not that the paragraph contains no information. The failure is that its information has no durable relationship to the evidence and no reliable route back into use.
That distinction matters because a knowledge base is asked to do more than remember that a conversation happened. It must let someone ask a later question, find the relevant material, see how a claim was supported, and notice when the supporting source is stale or contradicted. It must also remain understandable when the agent is absent. In claude-obsidian, the intended output is therefore not a hidden model memory or a cloud database. It is a user-owned collection of Markdown, JSON, and source files that can be opened in Obsidian or read as ordinary files.
Consider a small but realistic interaction. A user captures documentation about a tool’s optional network adapter. Later, they ask whether a proposed workflow can run without sending page text to a remote model. A useful knowledge base should not answer only with a polished “yes” or “no.” It should preserve the original documentation, connect the answer to the relevant capability and privacy concepts, and make clear whether the statement describes the core, an optional adapter, or an external runner. If the documentation changes, the source identity and review state should give the user somewhere to start checking. The value lies in the chain around the answer, not merely in the answer’s wording.
The project describes this as a repeatable loop. A source is retained with context. Important claims are grounded. Related knowledge is connected through pages, indexes, maps, and visual views. The resulting vault is used again for querying, research, retrieval, linting, and rollups. Each step changes what the next step can safely do. A retained source makes a later claim auditable; a grounded claim makes a link more meaningful; a maintained graph makes retrieval more useful; retrieval creates an opportunity to discover what the vault already knows before starting from zero.
The loop also changes the meaning of “compounding.” It does not mean that every new note automatically increases value. It means that a new piece of knowledge can add durable connections without erasing the conditions under which it should be trusted. A short source that adds no reusable synthesis may be better left as a captured source than paraphrased into another page. A claim that lacks support should remain visibly unsupported rather than being polished until it looks established. Compounding is controlled accumulation, not accumulation at any cost.
What claude-obsidian actually connects
The project is best understood as a relationship among four things: source material, a user vault, a set of host-facing skills, and a portable core that enforces shared rules. The skills give an agent distinct jobs—setting up a vault, ingesting sources, answering from existing evidence, saving a selected result, checking health, or researching under a budget. The core supplies the common mechanics for selecting a vault, validating paths, recording provenance, and applying reviewed changes. The vault is where the user’s durable knowledge lives.
That relationship is more substantial than a collection of prompt templates. Capture preserves source identity before synthesis. Ingest decides whether material adds enough durable value to justify canonical pages and extracts claims, entities, concepts, contradictions, and open questions. Provenance records keep source identity separate from the prose that summarizes it. Query remains a read-only act of finding and explaining existing evidence; saving an answer is a separate choice. Maintenance looks for broken navigation, missing metadata, stale indexes, and provenance violations instead of assuming that a graph is healthy because it contains many files.
The separation between a source and a page is especially important. A source is evidence with an origin, a locator, and a lifecycle. A page is a reader-facing organization of knowledge. A claim is a statement that can be assessed against one or more sources. These are related, but they are not interchangeable. If a page says that an operation is safe, the relevant question is not whether the page exists or sits in a well-named folder. It is which source supports the statement, whether that source is current, and whether contradictory evidence is visible. That is the reasoning structure the project’s later ledgers and retrieval workflows are designed to preserve.
The same design appears in the project’s boundaries. The product checkout is not meant to become the user’s vault. Runtime locks, journals, queues, and retrieval indexes are operational state, not new evidence. An inbox source remains visible until the user removes it. A raw capture is immutable and content-addressed. These distinctions may sound administrative, but they answer a substantive question: when a result is wrong, can the user still find the original material, identify what changed, and decide what to keep?
The central theme of this series follows from that question. Ownership, provenance, and recoverability reinforce one another. Ownership tells us whose state is being changed. Provenance tells us why a claim deserves attention and what evidence it depends on. Recoverability ensures that a multi-file operation does not leave the vault in a state that is impossible to understand or repair. Remove any one of the three and the apparent convenience of AI-assisted note-taking can become a new source of opacity.
This loop is deliberately broader than ingestion. A system that only creates notes may increase the volume of information while making future judgment harder. A system that preserves sources but never connects or retrieves them becomes an archive. A system that retrieves quickly but cannot distinguish a current claim from a stale or unsupported one becomes a fluent search interface with uncertain foundations. claude-obsidian tries to keep these functions connected while giving each a bounded responsibility.
The loop also explains why the project offers several distinct ways to interact with the vault. Ingest is for supplied material, query is for reading what is already there, and save is for preserving a result that the user has deliberately selected. Research can widen the evidence boundary, but it is treated as a cited dossier before any canonical merge. Lint can reveal a broken link or stale index, but it reports rather than silently repairing the graph. These are not interchangeable interfaces with different names. Their separation keeps an action’s consequence visible: reading is not writing, a draft is not accepted knowledge, and a diagnostic is not a repair.
The promise includes boundaries
The project’s “local-first” description has a precise meaning. The portable core stores vault content on the selected filesystem and does not make network requests by default. It does not mean that every surrounding tool is offline. A host’s model, a web research workflow, a configured external capture runner, or an optional contextual-retrieval provider may send selected data elsewhere. Those paths are treated as explicit egress decisions rather than being hidden behind the word “local.”
This distinction is practical rather than semantic. A user can keep Markdown pages, raw source bytes, ledgers, journals, and local BM25 data in the vault while still choosing to send a query or page text to an approved provider for a particular extension. The fact that the files are local does not erase the later boundary where content enters a model context. Conversely, a missing external adapter is not treated as a successful extraction merely because its configuration file exists. The project’s useful answer may be a bounded local fallback or an honest statement that a capability is unavailable.
Likewise, “source-cited” does not mean “guaranteed true.” The system can retain a source locator, a content hash, a review state, and the evidence associated with a claim. Those records can make unsupported or contradictory material visible. They cannot turn a weak source into a strong one, and they cannot replace a reader’s judgment about what the source actually establishes. The repository is first-party evidence about the project’s design and implementation; it is not an independent study showing that every vault produces better decisions or that retrieval always finds the right answer.
The project is explicit about other non-promises. It is not an automatic transcript recorder, a cloud sync service, a factual oracle, a replacement for backups or source control, or a system that publishes or mutates public collaboration state without owner approval. It does not claim built-in semantic extraction for every media type. Optional capabilities may be absent, configured but unverified, or degraded. A safe workflow reports those states instead of simulating success.
There is also an important security boundary. The portable core runs with the current user’s filesystem permissions; it is not a sandbox that neutralizes an agent, plugin, hook, or external command that already has those permissions. The project’s safeguards are meant to make ownership, evidence, consent, and recovery explicit within that trust boundary. They reduce classes of accidental or concurrent damage; they do not make an already-authorized process harmless.
This is why the project’s safeguards should not be read as friction added around a note-taking feature. They are the conditions under which the feature can be trusted enough to compound. Before examining how a source is captured and how a claim is assessed, we need to establish a more basic boundary: which state belongs to the product, which belongs to the user, and which is only derived runtime machinery. That separation is what keeps a knowledge base—and the sources it remembers—from being confused with the tool that helps maintain it.