A Shared Memory for Claude Code
Using Obsidian to Organise Human and AI Knowledge
Claude Code has some memory out of the box. CLAUDE.md files provide project instructions, .claude/MEMORY.md captures learnings across sessions, and you can resume a previous session to keep its full context. But this memory is per-project and unstructured — the agent can’t draw on what it learned about your data model conventions in project A when it’s working on project B, and there’s no way to represent relationships between the things it knows. Each piece of knowledge is an isolated note, unconnected to the rest.
OpenClaw — the open-source general-purpose AI assistant, not a coding agent — has gone further. It stores daily logs, curated knowledge, and skills as markdown files, and layers a hybrid search index (vector + BM25) on top. But its memory is still flat: a MEMORY.md file and a directory of daily logs, retrieved by semantic similarity. When related chunks end up in the same context window the agent can reason about their connections — but those connections aren’t captured anywhere. Next session, they have to be re-derived or they’re lost.
Both tools use markdown files as their persistence layer. This is a reasonable engineering choice — markdown is human-readable, version-controllable, and needs no infrastructure. But a pile of markdown files is not a knowledge base. What happens when you give those files structure — explicit relationships between notes, a shared taxonomy, an audit loop that checks the whole thing for consistency?
Obsidian and Claude Code’s skill system can turn flat agent memory into a knowledge graph that both the human and the agent can read and write. The setup takes a small amount of time, but the return is concrete: cheaper and more productive sessions because the agent starts each session already equipped with domain knowledge and an understanding of the codebase, rather than rediscovering it from scratch.
You don’t need Obsidian. But it helps.
Obsidian is a cross-platform note-taking app that has become popular with developers and knowledge workers for personal knowledge management (PKM). Unlike Notion or Google Docs, it stores everything as plain markdown files in a folder on your local disk — no cloud service, no proprietary format. You can read those same files with cat, edit them in vim, version-control them with git. If Obsidian disappeared tomorrow, nothing would change about the files themselves.
Obsidian’s two distinguishing features are wiki-links and a graph view. You link between notes with [[note-name]] syntax, and Obsidian renders those links as a navigable network — showing you not just what a note links to but everything that links to it (backlinks). This turns a folder of loose markdown files into an interlinked wiki.
For a human collaborating with an AI coding agent, this means you can see the shape of what the agent knows. The agent writes notes as markdown files; Obsidian lets you browse them as a knowledge graph. Everything we describe in this post works without Obsidian installed — the files are just markdown, and the agent reads and writes them directly — but Obsidian makes the structure visible and navigable in a way that a file listing can’t.
What Claude Code gives you to work with
Claude Code’s extensibility is built on three markdown-native mechanisms:
CLAUDE.mdfiles — project instructions loaded hierarchically (global, project, directory), governing agent behaviour..claude/MEMORY.md— auto-captured learnings that persist across sessions.Skills — markdown files in
.claude/skills/that define on-demand capabilities. Each skill is aSKILL.mdwith a frontmatter block and a procedure the agent follows when invoked — you can teach Claude Code new workflows without touching its source.
A skill can instruct the agent to read and write files or call APIs — all defined in plain markdown, no compiled code. This is enough to build a full knowledge management layer.
The coding payoff
Without a vault, every new Claude Code session starts cold. The agent maps out the codebase, builds up an understanding of how services interact — and then that understanding evaporates when the session ends. You pay for the same exploration in tokens, every time.
A vault changes this. The agent writes up what it finds — ORM model relationships, API contracts between services, the data flow through a processing pipeline — so that the next session can start with targeted code exploration rather than a broad sweep. If the agent previously documented how the payment service handles refunds, it doesn’t need to re-trace that flow; it reads the note, checks the entry points are still current, and spends its token budget on what’s actually changed. As codebases grow, this compounds — the agent’s orientation cost stays proportional to what’s changed since the last session, not the size of the codebase.
The vault is also writable by the human.
Domain knowledge: the human side of the vault
An AI coding agent can read every file in your repository. What it can’t do is understand why the code is the way it is. Why does the submission handler validate fields in that particular order? Why does the pricing model have a special case for that product category? The business logic is in the code, but the business reasoning is in the developer’s head.
Human-written vault notes fill this gap. When the developer writes a note explaining how insurance submissions flow through the underwriting pipeline — which fields are required at which stage and what the downstream consumers expect — the agent can read that note before touching the code. The result is code changes that respect business intent, not just syntactic correctness.
In practice this means the vault has two kinds of content: notes the agent writes (architecture, data models, patterns it discovered in the code) and notes the human writes (domain knowledge, design rationale, business rules that aren’t obvious from the implementation). The wiki-links between them are where the real value lies — a domain note about submission validation linked to the agent’s architectural note about the submission handler means the agent has both the what and the why available when you ask it to modify that code.
This also applies across projects. A developer working on multiple services that share a domain (say, a monorepo with several microservices handling different stages of the same business process) can write domain notes once. Every project’s agent sessions benefit from that shared understanding.
Obsidian as the structural layer
Point Obsidian at a shared vault directory that both you and your agent read from and write to. The agent’s skills govern how it interacts with the vault; Obsidian gives you the graph view and backlinks.
The key design decisions:
Flat structure — no folders. All notes live at the vault root. Organisation is via tags and wiki-links, not directory hierarchy. A note about a database migration can be simultaneously tagged #architecture, #service/payments, and #decision — something folders can’t express.
Tags as a multi-dimensional taxonomy. Hierarchical tags like #project/foo, #service/bar, #domain/finance let you slice the vault along any axis. Because tags are plain text in markdown, they’re trivially greppable — a single search for lines starting with # gives you the full taxonomy of the vault in one call.
Wiki-links as the knowledge graph. [[note-name]] links between notes build the graph that Obsidian visualises. The agent is instructed to prefer links over duplication — if a concept is explained elsewhere, link to it.
Daily notes as session journals. YYYY-MM-DD.md files capture what happened each session. They’re journals, not knowledge — append-only, carrying forward open items from previous days. The agent reads the most recent daily notes at the start of every session to orient.
Four skills that make it work
The system is built from four Claude Code skills, each a markdown file defining a procedure the agent follows when invoked. The full skill definitions are on GitHub — adapt them to your own stack.
1. Vault Manager
Invoked as: /pkm
The core read/write skill. Defines all vault conventions — file naming, tag taxonomy, note structure, and wiki-link policy. Instructs the agent to write notes when discovering architecture or making decisions, and to orient at the start of every session by reading recent daily notes and running a tag-line grep.
Also defines a backlog system: unchecked markdown checkboxes tagged #backlog in daily notes, carried forward across days, ticked off when completed. Greppable and self-contained.
Why it matters: Without this skill, the agent writes notes in whatever format occurs to it. The conventions ensure every note is machine-navigable and human-readable, and that the vault stays internally consistent as it grows.
2. Vault Auditor
Invoked as: /vault-insights
A periodic audit that reads every note and produces two analyses:
Inconsistency scan — contradictions between notes, broken wiki-links, and duplicate coverage at risk of drift. Findings are severity-rated (error, warning, info).
Latent insight scan — this is where the graph structure earns its keep. Because notes are explicitly linked by wiki-links and tagged along multiple dimensions, the auditor can traverse the graph to surface knowledge that’s implicit in the connections but not stated anywhere. A domain note about regulatory requirements linked to an architecture note about data retention, linked in turn to a service note about the deletion endpoint — none of these notes individually says “the deletion endpoint may violate regulatory requirements”, but the auditor can follow the links and draw that out. Each insight gets a confidence and immediacy rating.
Findings are written to the daily note only — the auditor never edits other notes. It deduplicates against previous runs, so unchanged findings aren’t repeated. The human reviews and decides what to act on.
Why it matters: This is the generate→test loop for knowledge itself. The agent generates notes as it works; the auditor tests them for coherence. If the developer wrote a domain note saying “submissions are immutable after approval” and the agent later documented an update endpoint on the submission model, the audit flags the contradiction before anyone writes code based on a stale assumption.
3. External Sync
Invoked as: /notion-sync
Bridges an external knowledge source (in this case Notion, but the pattern generalises to any API-accessible tool) into the vault. The skill determines areas of focus by reading the vault, searches the external source, deduplicates against existing notes, presents a preview with TLDRs for each candidate page, and only writes after human confirmation.
Synced notes are tagged with their source and include a source URL. The skill condenses rather than dumps — stripping boilerplate and reorganising content to match vault conventions.
Why it matters: Knowledge lives in many places — wikis, project management tools, design docs — and this skill brings relevant content into the vault without requiring you to abandon existing tools.
4. Work-in-Progress Dashboard
Invoked as: /wip
Generates an Obsidian Kanban board by pulling from the vault (backlog items, PR notes, sketches), GitHub (open PRs, review requests, related PRs by teammates), and external project management tools. The board is a markdown file in Kanban plugin format — drag-to-reorder in Obsidian, greppable from the terminal.
The skill derives active focus areas from your current work (open PRs, backlog tags, sketch notes) and uses them to filter noise — surfacing review requests that touch code you care about while collapsing unrelated items into summary counts.
Why it matters: It closes the loop between knowledge and action — the vault drives a daily dashboard of what to work on and what to review.
The OpenClaw parallel
OpenClaw’s memory architecture has the same dual-layer structure: daily logs that capture what happened, and curated knowledge that distils long-term principles. Its memsearch library (extracted and open-sourced by Zilliz) chunks markdown into ~400-token segments, embeds them, and runs hybrid search (70% vector, 30% BM25) against a local SQLite index.
This is a retrieval system — it helps the agent find relevant chunks, but it doesn’t help either the agent or the human understand the structure of what it knows or spot contradictions.
The Obsidian approach described here adds the missing layers:
Layer OpenClaw Claude Code + Obsidian Storage Markdown files Markdown files Retrieval Vector + BM25 hybrid search Context window loading + grep Structure Flat (MEMORY.md + daily logs) Tags, wiki-links, graph view Quality Manual editing Automated audit with severity/confidence ratings Action — WIP dashboard derived from vault state Integration Community skills (ClawHub) Skills + external sync
Retrieval — can the agent find what it needs? — matters, but the higher-leverage question is structural: can the agent and the human reason about what the agent knows, and where it’s wrong?
Getting started
The minimum viable setup:
Create a vault directory. Point Obsidian at it. Point your agent at the same directory (via
CLAUDE.mdinstructions or equivalent).Write a vault manager skill. Define conventions: file naming, tags, note structure, wiki-link policy. This is the constitution — everything else follows from it.
Instruct your agent to orient. At the start of each session, read recent daily notes and run a tag-line grep. This takes seconds and prevents the agent from re-discovering what it already knows.
Add an audit loop when the vault reaches ~20 notes. Before that, you can spot inconsistencies yourself. After that, you can’t.
The full skill definitions are available as a starting point — available on GitHub. Adapt the conventions to your domain and workflow. And start writing domain notes yourself — the agent can explore the code, but only you know why it’s the way it is.
Code: phelps-sg/claude-code-obsidian-skills — all four skill definitions, anonymised and ready to adapt.
Sources: