Obsidian Memory System

Persistent agent memory using an Obsidian vault with structured folders, daily journals, semantic search, and self-improvement logging.

Architecture

~/clawd/                        ← OpenClaw workspace
├── SOUL.md ──symlink──→ vault/00-brain/SOUL.md
├── USER.md ──symlink──→ vault/00-brain/USER.md
├── AGENTS.md ──symlink──→ vault/00-brain/AGENTS.md
├── TOOLS.md ──symlink──→ vault/00-brain/TOOLS.md
├── MEMORY.md ──symlink──→ vault/00-brain/MEMORY.md
├── HEARTBEAT.md             (standalone, periodic tasks)
├── memory/                  (daily memory files for semantic search)
└── vault/                   ← Obsidian vault
    ├── 00-brain/            Core identity files
    ├── 10-journal/          Daily work logs (YYYY-MM-DD.md)
    ├── 20-projects/         Project docs (overview, decisions, timeline)
    ├── 30-knowledge/        Reusable reference material
    ├── 40-people/           People notes
    ├── 50-ideas/            Future plans, brainstorms
    ├── 60-learnings/        Self-improvement logs (errors, learnings, feature requests)
    └── templates/           Note templates

OpenClaw auto-loads workspace root files (SOUL, USER, AGENTS, TOOLS, MEMORY) every session. Symlinks bridge workspace ↔ vault so Obsidian and the agent see the same files.

Setup

Run the setup script to initialize everything:

bash scripts/setup-vault.sh ~/clawd

This creates the vault structure, brain file templates, symlinks, vault/60-learnings/ directory, and templates. Then customize each brain file for your agent.

For details on each file's purpose: read references/brain-files.md For OpenClaw config: read references/openclaw-config.md

Daily Workflow

Session Start

1. OpenClaw loads brain files automatically (SOUL, USER, AGENTS, TOOLS, MEMORY)
2. Read today's and yesterday's journal: vault/10-journal/YYYY-MM-DD.md
3. Use memory_search for any recall needs

During Work

• Use memory_search("query") to find past context
• Follow wikilink references: [[20-projects/name/overview|Name]]

After Completing Tasks

1. Update daily journal — vault/10-journal/YYYY-MM-DD.md (always)
2. Update project docs — vault/20-projects/*/overview.md (if project changed)
3. Update MEMORY.md — Only for new preferences, lessons, or projects

Self-Improvement Logging

Entry format — see references/logging-format.md

Promotion Pipeline

When a learning proves broadly applicable, promote it:

Promote when: Recurrence ≥ 3, seen across 2+ tasks, within 30-day window.

Wikilinks

Always connect related content:

See [[20-projects/my-app/overview|My App]] for details.
Built by [[40-people/juan|Juan]].

Frontmatter

Every vault markdown file needs:

---
title: Document Title
type: note|project|reference|daily|decision
created: YYYY-MM-DD
permalink: agent-name/folder/filename
---

MEMORY.md Rules

• Keep under ~5K characters (max 10K)
• Include: preferences, lessons, project index, cross-project decisions
• Exclude: detailed timelines, code snippets, daily events
• Point to deeper docs via wikilinks
• Full rules: read references/memory-rules.md

Heartbeat Maintenance

During periodic heartbeats (every few days):

1. Review recent vault/60-learnings/ entries
2. Promote applicable learnings to brain files
3. Review recent journals → update MEMORY.md if needed
4. Check MEMORY.md size, move detail creep to project/knowledge docs

Quick Commands

# Count pending learnings
grep -rh "Status\*\*: pending" vault/60-learnings/*.md | wc -l

# Find high-priority items
grep -B5 "Priority\*\*: high" vault/60-learnings/*.md | grep "^## \["

# Search learnings by area
grep -l "Area\*\*: backend" vault/60-learnings/*.md