Persistent Memory for AI Agents — an Obsidian Methodology

Structuring a second brain: going from chatting with an LLM to an agentic system for your organization or projects.

Version française

A structured methodology for building a persistent knowledge base in Obsidian, powered by Claude Code agents, with two recommended layers — Graphify (a queryable knowledge graph) and ADR (a decision log). Inspired by Andrej Karpathy's work on LLM memory.

The core idea: instead of using AI to answer questions from scratch each time, you compile knowledge permanently into a wiki. Each conversation enriches the base — nothing disappears into chat history.

Author: Nicolas / Datashiru — licensed under CC BY-NC 4.0.

---

The three pillars

1. Obsidian — the wiki, your IDE

Obsidian isn't just a note editor: it's where the knowledge lives. Every wiki page follows a fixed structure (frontmatter, TL;DR, limits and counter-examples, relations), and [[wikilinks]] weave the explicit graph between notes. Obsidian stays the tool for human navigation and editing.

2. Claude Code — the agent that compiles the knowledge

Claude Code plays the programmer: the wiki is its codebase (Markdown), Obsidian its IDE. Four commands structure the knowledge lifecycle:

• /ingest — turns a raw source (raw/) into structured wiki pages
• /query — answers from the wiki, not from the model's general knowledge
• /lint — checks vault health (orphans, duplicates, broken links, stale content)
• /save — crystallizes a session answer into a permanent wiki page

Each command delegates to an isolated sub-agent that receives only the context its task needs (~40% token savings compared to a single agent loading the whole vault). The commands and sub-agents ship ready to install in templates/claude-code/.

3. Graphify — the queryable knowledge graph (recommended)

Past a certain volume, re-reading the whole wiki for every question gets slow and expensive. Graphify indexes the vault into a graph (graphify-out/graph.json): nodes, explicit and inferred relations, detected communities.

The "Read Graph" skill — documented in an AGENTS.md at the root, readable by any agent, not just Claude Code — enforces a 3-step protocol: consult the graph first, identify the relevant files, then selectively read full content only when necessary. This cuts token consumption compared to reading every file directly.

This layer also enables consistent multi-agent access: several agents (local Claude Code, an agent on a VPS, etc.) can consult the same graph and answer from the same structure, via read-only Git sync rather than exposing the vault on the network.

---

The mechanism that keeps the decision layer alive

An ADR isn't written "on top of" the work: it graduates from the daily note. A decision noted in daily/ is ephemeral by construction — retention is 30 days. If it's structuring and durable, it moves to wiki/decisions/ before the purge, and becomes queryable through the graph.

Without that graduation reflex, the decision layer is dead: decisions stay in daily/ and vanish with it.

---

What's inside

• Architecture — a layered folder structure (raw/, wiki/, context/, daily/, projects/)
• 4 core slash commands — /ingest, /query, /lint, /save — plus /adr (decisions layer) and /init-vault (bootstrap)
• 3 specialized agents — each agent receives only the context it needs (~40% token savings)
• Wiki page structure — frontmatter, TL;DR, limits & counter-examples, relations
• Decision layer (ADR) — recommended: captures the why behind choices (context, rejected options, consequences), with an /adr command
• Naming conventions — closed tag lists, kebab-case, ISO date prefixes
• Initialization checklist — step-by-step from zero to first ingestion
• Split vault rules — when to create a new vault (thematic + 500-page hard cap)
• Knowledge graph layer (recommended) — Graphify integration + "Read Graph" skill for token-efficient, multi-agent queryable access
• Ready-to-install agent kit — the 6 slash commands and 3 sub-agents as usable files, in French and English (templates/claude-code/)

---

How to use

Prerequisites: Obsidian, and Claude Code already installed and familiar. The method assumes you can start a session and invoke a slash command — it doesn't teach that.

1. Copy vault-methodology-template.en.md into your Obsidian vault root (or vault-methodology-template.md for the French original)
2. Start with context/ligne-rouge.md — write your non-negotiable constraint for this vault
3. Follow the initialization checklist at the bottom of the template
4. Install the agent kit: cp -r templates/claude-code/en/. /path/to/your-vault/.claude/
5. Adapt the domain examples to your field
6. (Recommended) Enable the ADR then Graphify layers once the core loop is second nature — see "Step 5" and the dedicated sections in vault-methodology-template.en.md

The template is intentionally domain-agnostic. Adapt it to your field.

---

Philosophy

Source → Ingest → Wiki → Query → Synthesize → Wiki (enriched)

Knowledge compounds. A vault used for 6 months becomes exponentially more useful than one used for 6 days — because every query builds on prior ingestion.

---

License

CC BY-NC 4.0 — free to use and adapt, attribution required, commercial use prohibited.