obsidian-llm-memory

Long-term memory template for Claude Code using an Obsidian vault. Tracks project state, decisions, lessons, and stack notes across sessions — so Claude remembers your context without you re-explaining it every time.

Works on macOS and Windows. Includes AGENTS.md so Codex, Cursor, and Devin can read the same operating rules.

---

How It Works

Claude Code reads ~/.claude/CLAUDE.md at the start of every session. This template puts a structured memory system behind that file — project state, bug fixes, architectural decisions, coding conventions, and framework notes all live in your Obsidian vault and load on demand.

Token-efficient by design. Only small index files load at startup (~3,000 tokens). Full logs and stack notes load only when a trigger applies.

---

What It Does

• Loads project context, bug index, and decision index at every session start
• Keeps per-project working state in projects/<name>.md
• Tracks reusable bug fixes in lessons-learned.md (written immediately when resolved)
• Tracks architectural decisions in decisions-log.md (written immediately when made)
• Builds stack notes and synthesis playbooks organically as you work
• Provides slash commands for vault maintenance (/lint-vault, /compact-checkpoint, /consolidate-vault)
• Hooks auto-sync CLAUDE-source.md to ~/.claude/CLAUDE.md and write compaction checkpoints before context is lost

---

Prerequisites

• Obsidian with an existing vault
• Claude Code (npm install -g @anthropic-ai/claude-code)
• Git
• Bash (macOS/Linux native; Windows requires Git Bash)

---

Install

1. Clone into your Obsidian vault

cd /path/to/your/obsidian/vault
git clone https://github.com/<your-org>/obsidian-llm-memory.git

2. Copy the global Claude instructions

mkdir -p ~/.claude
cp obsidian-llm-memory/CLAUDE-source.md ~/.claude/CLAUDE.md

3. Copy optional Claude Code helpers

mkdir -p ~/.claude/hooks ~/.claude/commands ~/.claude/agents

# Hooks
cp obsidian-llm-memory/hooks/*.sh ~/.claude/hooks/
cp obsidian-llm-memory/hooks/extract_transcript.py ~/.claude/hooks/
chmod +x ~/.claude/hooks/*.sh

# Slash commands
cp obsidian-llm-memory/.claude/commands/*.md ~/.claude/commands/

# Subagents
cp obsidian-llm-memory/vault-reader.md ~/.claude/agents/
cp obsidian-llm-memory/agents/*.md ~/.claude/agents/

Windows (Git Bash):

mkdir -p "$HOME/.claude/hooks" "$HOME/.claude/commands" "$HOME/.claude/agents"
cp obsidian-llm-memory/hooks/*.sh "$HOME/.claude/hooks/"
cp obsidian-llm-memory/hooks/extract_transcript.py "$HOME/.claude/hooks/"
cp obsidian-llm-memory/.claude/commands/*.md "$HOME/.claude/commands/"
cp obsidian-llm-memory/vault-reader.md "$HOME/.claude/agents/"
cp obsidian-llm-memory/agents/*.md "$HOME/.claude/agents/"

4. Configure Claude Code settings

Add to ~/.claude/settings.json (create it if it doesn't exist):

{
  "env": {
    "LLM_MEMORY_ROOT": "/absolute/path/to/your/vault/obsidian-llm-memory",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "60"
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash /absolute/path/to/your/vault/obsidian-llm-memory/hooks/sync-claude-source.sh"
          }
        ]
      }
    ],
    "PreCompact": [
      {
        "matcher": "auto",
        "hooks": [
          {
            "type": "command",
            "command": "bash /absolute/path/to/your/vault/obsidian-llm-memory/hooks/pre-compact.sh"
          }
        ]
      },
      {
        "matcher": "manual",
        "hooks": [
          {
            "type": "command",
            "command": "bash /absolute/path/to/your/vault/obsidian-llm-memory/hooks/pre-compact.sh"
          }
        ]
      }
    ]
  }
}

Windows note: Use forward slashes or a WSL path for LLM_MEMORY_ROOT and hook commands. Git Bash handles both. Avoid backslashes in the JSON.

5. Customize for your workflow

Open conventions.md and update it with your preferred stack, coding style, and standards. Open recurring-tasks.md and adjust the standing rules to match your workflow. These two files are the most important to personalize — Claude reads them at every session start.

6. Start using it

cd /path/to/any/project
claude

On the first session Claude will ask which project you are working on and create a project memory file when you wrap up.

---

Daily Workflow

1. Open your project folder and run Claude Code.
2. Claude loads context automatically (project state, bug index, decision index).
3. Work normally.
4. Say "wrap up this session" before exiting.

Claude will:

• Write bug fixes to lessons-learned.md immediately when resolved
• Write decisions to decisions-log.md immediately when made
• Write a compaction checkpoint before context is compacted
• Update project state, session log, and index at wrap-up

---

Repository Layout

obsidian-llm-memory/
  CLAUDE-source.md          ← source of truth for ~/.claude/CLAUDE.md
  AGENTS.md                 ← copy of CLAUDE-source.md for Codex/Cursor/Devin
  CLAUDE.md                 ← stub — prevents double-load when working in this directory
  conventions.md            ← your coding standards (customize this)
  recurring-tasks.md        ← standing rules for every session (customize this)
  frontmatter-spec.md       ← controlled vocabularies for project frontmatter
  vault-reader.md           ← vault-reader subagent definition
  stack-notes-index.md      ← index of stack notes (starts empty, built organically)

  projects/
    example-project.md      ← reference template showing project file format
    index.md                ← projects overview (gitignored after cloning)

  stack-notes/              ← framework reference notes (built organically)
  synthesis/                ← cross-project pattern playbooks (built organically)
    index.md                ← playbook index (starts empty)

  agents/
    codebase-explorer.md    ← code search subagent
    test-runner.md          ← test runner subagent
    security-auditor.md     ← security audit subagent

  hooks/
    pre-compact.sh          ← writes session checkpoint before context compaction
    sync-claude-source.sh   ← syncs CLAUDE-source.md to ~/.claude/CLAUDE.md on save
    extract_transcript.py   ← transcript parser used by pre-compact.sh

  scripts/
    audit-claude-md.py      ← audits project CLAUDE.md files for vault integration
    rotate-summaries.py     ← rotates summary indexes when they exceed threshold
    propose-wikilinks.py    ← proposes wikilinks between log entries and project files

  .claude/
    commands/               ← slash commands (copy to ~/.claude/commands/)
    skills/                 ← Claude Code skills

  .gitignore
  LICENSE
  README.md

Files created locally (gitignored — never pushed): session-state.md, session-log.md, lessons-summary.md, lessons-learned.md, decisions-summary.md, decisions-log.md, sources.md, projects/<name>.md

---

Privacy Model

This template ships with empty memory files. Your projects, session history, lessons, decisions, and sources are created locally as you use it and are excluded from git by .gitignore. Only the reusable structure and instructions are tracked — never your personal work.

---

License

MIT