Claude Code + Obsidian + Graphify: The Definitive Guide to Token Savings & Persistent Memory

71.5x fewer tokens per session with Graphify + permanent memory across sessions with Obsidian Zettelkasten.

A complete setup to turn Claude Code into an agent with long-term memory and full codebase awareness — without wasting tokens re-reading files.

🇧🇷 Leia em Português

---

Table of Contents

1. The Problem
2. The Solution (Overview)
3. Part 1 — Obsidian as Persistent Memory
4. Part 2 — Chat Import Pipeline
5. Part 3 — Graphify (Codebase Knowledge Graph)
6. Part 4 — Complete Workflow
7. Real Results
8. Troubleshooting

---

The Problem

When working with Claude Code, two problems silently eat your tokens:

Problem 1 — Amnesia between sessions. Every time you open a new session, you have to re-explain your project: stack, past decisions, current bugs, what's left to do. Claude Code remembers nothing from the previous session.

Problem 2 — Codebase re-reading. Claude Code re-reads all your project files every session to understand the structure. A project with ~40 files burns ~20,000 tokens just for Claude to orient itself — before you even ask a question. If you run 10 sessions a day, that's 200,000 wasted tokens.

---

The Solution (Overview)

Two complementary systems, each solving a different problem:

Layer	Tool	Problem Solved	Cost
Project memory	Obsidian Zettelkasten	Amnesia between sessions	Free
Code map	Graphify	Codebase re-reading	Free (AST mode)
Conversation history	Import pipeline	Lost chat insights	Free
Continuity	/resume and /save commands	Picking up where you left off	Free

Obsidian handles what was decided (declarative memory). Graphify handles how the code is structured (structural map). Together, Claude Code starts every session knowing everything — without re-reading anything.

---

Part 1 — Obsidian as Persistent Memory

Concept

A single, centralized Obsidian vault acts as Claude Code's "second brain." It stores decisions, context, progress, and knowledge for all your projects. Notes follow the Zettelkasten method: atomic (one idea per note), densely interlinked, with standardized metadata.

Claude Code accesses the vault through CLAUDE.md and custom skills.

Recommended Structure

~/vault/                              # SINGLE vault for all projects
├── CLAUDE.md                         # global instructions for Claude Code
├── permanent/                        # consolidated atomic notes
├── inbox/                            # raw capture (ideas, drafts)
├── fleeting/                         # quick temporary notes
├── templates/                        # note templates
├── logs/                             # global session logs
├── references/                       # reference material
├── my-project/                       # MOCs and notes for project X
│   ├── architecture/                 #   architecture, decisions, conventions
│   ├── pipeline/                     #   data flows, APIs
│   ├── data/                         #   schema, data model
│   ├── features/                     #   planned/implemented features
│   └── logs/                         #   project session logs
├── another-project/                  # MOCs and notes for project Y
│   └── ...
├── chats/                            # imported Claude chats
│   ├── code/                         #   from Claude Code
│   └── web/                          #   from Claude Web/App
└── graphify/                         # codebase knowledge graphs
    ├── my-project/                   #   graph notes for project X
    └── another-project/              #   graph notes for project Y

Why a single vault? Having one vault per project fragments knowledge. With a single vault, a note about "Supabase Auth" links to both project A and B. The graph view reveals cross-project connections you didn't expect.

Step-by-Step Setup

Prerequisites:

• Claude Code installed and authenticated
• Obsidian installed (free: obsidian.md)

1. Create the vault:

Obsidian → "Create new vault" → choose a name and location.

2. Create the folder structure:

cd ~/vault  # adjust to your path
mkdir -p permanent inbox fleeting templates logs references
mkdir -p my-project/{architecture,pipeline,data,features,logs}

3. Create the CLAUDE.md:

This is the file Claude Code reads automatically. Create CLAUDE.md at the vault root:

# Vault — Instructions for Claude Code

## What is this vault
Centralized knowledge base for all projects.
Persistent memory across sessions.

## Project stacks
- Project X: React + Supabase
- Project Y: Python + FastAPI
(adapt to your projects)

## Zettelkasten Rules

### Note creation
- Use wikilinks: [[note-name]] (not markdown links)
- Mandatory YAML frontmatter on every note
- Filenames in kebab-case: `auth-flow.md`, not `Auth Flow.md`
- 1 concept per permanent note (atomicity)
- Minimum 2 wikilinks per note (dense linking)

### Standard frontmatter
---
title: Note Name
tags: [project, topic]
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: active
type: permanent
---

### Never do
- Don't delete notes without asking
- Don't use markdown links for internal notes (use wikilinks)
- Don't create notes without frontmatter
- Don't change folder structure without documenting it

## Session Commands

### /resume
When you receive this command:
1. Read the 3 most recent session logs in logs/
2. Read architecture/decisions.md for the current project
3. Summarize current state and what's left to do

### /save
When you receive this command:
1. Create a session log in logs/YYYY-MM-DD-description.md
2. Record: what was done, decisions made, pending items
3. Add wikilinks to created/modified notes
4. Run git commit + push if in a repository

4. Create a note template:

cat > templates/default-note.md << 'EOF'
---
title: {{title}}
tags: []
created: {{date}}
updated: {{date}}
status: draft
type: permanent
---

# {{title}}

## Context

## Details

## Related links
EOF

5. Recommended Obsidian plugins:

Plugin	Purpose	Install method
BRAT	Install beta plugins	Community Plugins → Browse
3D Graph	3D vault visualization	Via BRAT (v2.4.1)
Folders to Graph	Folders as graph nodes	Community Plugins → Browse
Calendar	Daily note navigation	Community Plugins → Browse

---

Part 2 — Chat Import Pipeline

Concept

Your Claude chats (both Code and Web) contain valuable decisions, insights, and context that get lost in the history. This pipeline exports, processes, and imports those conversations as vault notes — with frontmatter, automatic tags, and wikilinks to existing notes.

Components

~/scripts/
├── claude_to_obsidian.py          # processor (frontmatter, tags, wikilinks)
└── sync_claude_obsidian.sh        # automation (export + process)

~/claude-exports/                   # temporary staging area (outside vault)
├── code/                           # Claude Code exports
└── web/                            # Claude Web exports

Setup

1. Install the Claude Code extractor:

pip install claude-conversation-extractor

2. Create staging directories:

mkdir -p ~/claude-exports/code ~/claude-exports/web

3. Create the post-processing script (~/scripts/claude_to_obsidian.py):

The script should:

• Read each exported .md file
• Detect origin (Code vs Web)
• Generate automatic tags based on content keywords
• Add standardized YAML frontmatter
• Insert [[wikilinks]] for notes that already exist in the vault
• Copy to chats/code/ or chats/web/ inside the vault

Example keyword-to-tag mapping:

KEYWORD_TAG_MAP = {
    "python": "python",
    "react": "react",
    "supabase": "supabase",
    "deploy": "deploy",
    "bug": "debugging",
    "refactor": "refactoring",
    # add your own
}

4. Create the automation script (~/scripts/sync_claude_obsidian.sh):

#!/bin/bash
EXPORT_DIR="$HOME/claude-exports"
VAULT_DIR="$HOME/vault"  # adjust to your path
SCRIPT_DIR="$HOME/scripts"
LOG="$SCRIPT_DIR/sync.log"

echo "[$(date)] Sync started" >> "$LOG"

# Export Claude Code chats
claude-extract --all --output "$EXPORT_DIR/code" 2>> "$LOG"

# Process and send to vault
python3 "$SCRIPT_DIR/claude_to_obsidian.py" \
    --export-dir "$EXPORT_DIR" \
    --vault-dir "$VAULT_DIR" \
    --move 2>> "$LOG"

echo "[$(date)] Sync completed" >> "$LOG"

5. Schedule automatic execution:

chmod +x ~/scripts/sync_claude_obsidian.sh

# Run daily at 10 PM
(crontab -l 2>/dev/null; echo "0 22 * * * $HOME/scripts/sync_claude_obsidian.sh") | crontab -

6. For Claude Web chats:

Install the "Export Claude Chat to Markdown" browser extension for Chrome/Edge. Do periodic bulk exports, save the .md files to ~/claude-exports/web/, and the cron job handles the rest.

7. Add a section to the vault's CLAUDE.md:

## Chat Import Pipeline

### Structure
- `chats/code/` → imported Claude Code conversations
- `chats/web/` → imported Claude Web/App conversations
- All chats get frontmatter with `type: chat` and `chat-import` tag

### Filter in Graph View
- `tag:chat-import` → chats only
- `-path:chats` → hide chats

---

Part 3 — Graphify (Codebase Knowledge Graph)

Concept

Graphify transforms your codebase into a queryable knowledge graph. Instead of Claude Code re-reading every file, it queries the graph — which is persistent across sessions and costs a fraction of the tokens.

• Code: processed 100% locally via tree-sitter AST. No code content leaves your machine.
• Cache: SHA256 — re-runs only process modified files.
• Cost: 0 tokens in default mode (pure AST). --deep mode uses LLM for semantic edges.
• Languages: Python, JavaScript, TypeScript, Go, Rust, Java, C, C++, Ruby, C#, Kotlin, Scala, PHP, Swift, Lua, Zig, and more (20 languages via tree-sitter).

Setup

1. Install:

pip install graphifyy
graphify install --platform claude

graphify install --platform claude creates the skill at ~/.claude/skills/graphify/SKILL.md. Other platforms are also supported (cursor, codex, opencode, etc.).

1.5. Set up API key (required for semantic extraction):

Graphify needs an LLM API key from Anthropic or Moonshot (Kimi) for semantic extraction. Export one before running:

export ANTHROPIC_API_KEY="your-key-here"
# or
export MOONSHOT_API_KEY="your-key-here"

If you want to skip LLM costs entirely, use AST-only mode:

graphify extract . --out ./graphify-out --no-cluster

This generates a structural graph without semantic edges.

2. Generate the graph:

Graphify has two execution paths and the original --obsidian* flags only work on one of them. Pick the form that matches how you're invoking it:

A. Inside Claude Code (skill — recommended for this guide):

/graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name

This runs the /graphify slash command, which the skill at ~/.claude/skills/graphify/SKILL.md parses. The skill calls graphify.export.to_obsidian() in Python directly, so --obsidian and --obsidian-dir are recognized here — they're not part of the headless shell parser.

B. From the terminal / CI (headless CLI):

graphify extract . --out ./graphify-out

The headless CLI uses subcommands (extract, update, watch, tree) and does not expose --obsidian / --obsidian-dir / --wiki / --mode deep. If you want Obsidian integration from the terminal, symlink the output directory into your vault after extraction:

ln -s $(pwd)/graphify-out ~/vault/graphify/project-name/graphify-out

Generated output (varies by path and flags):

your-project/
└── graphify-out/
    ├── graph.json          # queryable graph (always)
    ├── graph.html          # interactive viz (skill auto-generates; headless: see step 3)
    ├── GRAPH_REPORT.md     # god nodes, connections, metrics (always)
    ├── wiki/               # Wikipedia-style articles (skill form with --wiki only)
    └── cache/              # SHA256 cache

~/vault/graphify/project-name/    # only when skill form was given --obsidian
    └── (Obsidian notes)          # one note per function/module

3. Generate interactive visualization (headless only):

The skill auto-generates graph.html during extraction. For the headless path, run the visualization as a separate step:

graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html

Open the HTML file in a browser to explore the graph interactively.

4. Update .gitignore:

# Graphify
graphify-out/cache/

Keep graph.json and GRAPH_REPORT.md versioned — they're useful for the team.

5. Add to the project's CLAUDE.md:

Append to the CLAUDE.md at the repository root:

## Context Navigation (Graphify)

### 3-Layer Query Rule
1. **First:** query `graphify-out/graph.json` or `graphify-out/wiki/index.md`
   to understand code structure and connections
2. **Second:** query the Obsidian vault for decisions, progress, and project context
3. **Third:** only read raw code files when editing
   or when the first two layers don't have the answer

### When to rebuild the graph
- After structural changes (new modules, major refactors)
- Headless: `graphify update .` (only processes modified files)
- Skill: `/graphify . --update` (same behavior, runs through the skill — also accepts `--obsidian` to refresh the vault)
- The graph is persistent — NO need to rebuild every session

### Do NOT
- Don't manually modify files inside `graphify-out/`
- Don't re-read the entire codebase if the graph already has the information

6. Add to the vault's CLAUDE.md:

## Graphify (Codebase Maps)

### Structure
- `graphify/project-x/` → knowledge graph for project X
- Future projects get their own subfolders
- Notes are auto-generated — do NOT edit manually

### In Graph View
- Filter by `path:graphify` to see only code nodes
- Filter by `-path:graphify` to hide code nodes

7. Git Hook (optional):

Automatically rebuilds the graph on every commit:

graphify hook install

8. Watch Mode (optional):

Auto-rebuild on file save. Pick the form that matches how you invoke graphify.

Headless (separate terminal):

graphify watch .

Skill (inside Claude Code):

/graphify . --watch

Useful Commands

The table below lists the headless CLI subcommands you'd run in a terminal. Inside Claude Code, the same operations are available via the /graphify slash form documented in ~/.claude/skills/graphify/SKILL.md — that form additionally supports --obsidian, --obsidian-dir, --wiki, and --mode deep (which the headless parser doesn't expose).

Command	Description
graphify extract .	Full extraction on current directory
graphify extract ./src	Scan specific folder
graphify update .	Only process modified files
graphify watch .	Auto-rebuild on save
graphify query "question"	Query the graph directly
graphify explain "NodeName"	Plain-language explanation of a node
graphify path "A" "B"	Shortest path between two nodes
graphify tree --graph ./graphify-out/graph.json --output ./graphify-out/GRAPH_TREE.html	Generate interactive visualization
open graphify-out/graph.html	Open interactive visualization (skill-generated) or GRAPH_TREE.html (headless)

Adding New Projects

With a centralized vault, each project is just a subfolder. Same two paths as the initial setup.

Skill (inside Claude Code):

/graphify ~/another-project --obsidian --obsidian-dir ~/vault/graphify/another-project

Headless (terminal):

cd ~/another-project
graphify extract . --out ./graphify-out
ln -s $(pwd)/graphify-out ~/vault/graphify/another-project/graphify-out

Drop the ln -s line if you don't need Obsidian to pick up the graph. Notes appear in Obsidian's graph view alongside everything else.

---

Part 4 — Complete Workflow

Typical session

Open Claude Code session
    │
    ├── /resume                      ← loads vault context
    │                                   (recent logs, decisions, progress)
    │
    ├── Claude queries graph.json     ← understands code structure
    │                                   without re-reading all files
    │
    ├── Work on code                  ← features, bugs, refactors
    │
    ├── /save                        ← generates session log in vault
    │
    └── git commit                   ← hook rebuilds graph automatically

Savings per layer

Layer	Without it	With it
/resume	Re-explain project every session	Claude already knows the context
Graphify	Re-read ~40 files (~20k tokens)	Query 1 graph (~280 tokens)
Chat pipeline	Insights lost in chat history	Everything indexed and searchable
/save + logs	Forget what was done	Complete history with wikilinks

Graph View Filters

Filter	What it shows
path:permanent	Only permanent notes (consolidated knowledge)
path:graphify	Only codebase nodes (functions, modules, imports)
tag:chat-import	Only imported chats
-path:graphify -path:chats	Only manual notes (pure vault)

---

Real Results

Tested on a React + Supabase project with 126 TypeScript files:

Metric	Value
Graph nodes	332
Edges (connections)	258
Communities detected	124
graph.json size	172 KB
Obsidian notes generated	456
Token reduction per query	499x
LLM cost for generation	0 tokens (AST mode)
Imported chats in vault	137
Accumulated permanent notes	65+
Total vault notes	780+

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    OBSIDIAN VAULT (single)                   │
│                                                             │
│  permanent/  ← consolidated knowledge (Zettelkasten)        │
│  logs/       ← session logs (/save)                         │
│  chats/      ← imported conversations (cron pipeline)       │
│  graphify/   ← codebase knowledge graphs                    │
│  project-x/  ← MOCs, decisions, architecture                │
│                                                             │
│  CLAUDE.md   ← global instructions for Claude Code          │
└─────────────────────────┬───────────────────────────────────┘
                          │
                    Claude Code reads/writes
                          │
┌─────────────────────────┴───────────────────────────────────┐
│                   PROJECT REPOSITORY                         │
│                                                             │
│  src/            ← source code                              │
│  CLAUDE.md       ← project instructions + Context Nav       │
│  graphify-out/   ← graph.json, graph.html, report           │
│  .git/hooks/     ← post-commit rebuilds the graph           │
└─────────────────────────────────────────────────────────────┘

---

Troubleshooting

Graphify notes don't appear in Obsidian: Confirm the notes are inside the actual vault directory. Obsidian doesn't always point where you think — create a note in Obsidian and run find ~ -name "note-name.md" to discover the real path. Then move the notes there and Cmd+Q / reopen.

Graph view empty with filter applied: Disable "Orphans" and "Existing files only" in the graph filters. Cmd+Q and reopen Obsidian to force reindexing.

Claude Code doesn't query the graph: Check that the project's CLAUDE.md has the "Context Navigation" section and that graphify-out/graph.json exists at the repo root.

Cron doesn't run (macOS): Grant Full Disk Access to your terminal in System Preferences → Privacy & Security.

Graphify doesn't generate wiki: The wiki/ folder is only produced by the skill form with --wiki (/graphify . --wiki inside Claude Code). The headless graphify extract subcommand doesn't expose --wiki. From the terminal, use graphify query "question" against graph.json instead, or run the skill form if you need the Wikipedia-style articles.

Files with parentheses in name: Graphify generates notes like myFunction().md. Obsidian may struggle indexing files with () in the name. If needed, batch rename:

cd ~/vault/graphify/project
for f in *"("*; do mv "$f" "$(echo "$f" | sed 's/[()]//g')"; done

Unknown Command error in graphify: If graphify . errors with unknown command '.', you're running the headless CLI — which requires a subcommand (extract, update, watch, etc.) before the path. Either use the headless form:

graphify extract . --out ./graphify-out
# or, to refresh an existing graph:
graphify update .

Or, inside Claude Code, use the skill form with the leading slash — which routes through the /graphify skill rather than the shell parser and supports the full flag set (--obsidian, --obsidian-dir, --wiki, --mode deep, etc.):

/graphify . --obsidian --obsidian-dir ~/vault/graphify/project-name

---

Credits & Links

• Graphify — codebase knowledge graphs (MIT)
• Obsidian — PKM and second brain (free)
• Claude Code — Anthropic's coding agent
• Inspired by Andrej Karpathy's system and the r/ClaudeAI community

---

If this guide helped you, give the repo a ⭐ and share it with other devs using Claude Code.