Memory System for Claude Code

Manage persistent memory across Claude Code sessions using Obsidian vault storage.

Memory Architecture

Each project has its own isolated memory space. The project name is auto-detected from the git repository name (or folder name if not a git repo).

claude-memory/
└── projects/
    └── {project-name}/          # Isolated per-project memory
        ├── short-term/          # Current session context (cleared between major tasks)
        │   ├── current-task.md  # Active task details
        │   └── conversation-context.md  # User preferences, session state
        ├── long-term/           # Persistent knowledge (never auto-cleared)
        │   ├── decisions-log.md     # Architectural/design decisions
        │   ├── code-patterns.md     # Reusable code patterns
        │   ├── lessons-learned.md   # Bugs, gotchas, hard-won knowledge
        │   └── tools-reference.md   # Commands and tool references
        └── daily/               # Session logs by date
            └── YYYY-MM-DD.md    # Daily activity log

Project Name Detection

The project name is determined by:

1. Git repository name: basename $(git rev-parse --show-toplevel 2>/dev/null)
2. Fallback: Current working directory name

When to Save Memory

Save to Long-term Memory

Trigger a save when discovering:

Save to Short-term Memory

Update during active work:

Memory Format

Use consistent formatting with metadata:

## YYYY-MM-DD: Title

**Context**: Why this matters
**Decision/Pattern/Lesson**: What was learned
**Files**: Affected files (if applicable)
**Tags**: #decision #pattern #bug #learning

Obsidian MCP Tools

Use these tools for memory operations:

Session Workflows

Start of Session

1. Read conversation context for user preferences
2. Check recent daily logs for continuity
3. Load project-specific memory if working on known project

Read: claude-memory/projects/{project}/short-term/conversation-context.md
Read: claude-memory/projects/{project}/daily/{recent-date}.md

During Work

1. Update current-task.md when switching tasks
2. Append to daily log for significant actions
3. Save patterns/decisions as discovered

End of Session

1. Summarize session in daily log
2. Save any important learnings to long-term memory
3. Update current-task.md with next steps

Memory Categories Reference

decisions-log.md

Architectural and design decisions with rationale:

• Technology choices
• Pattern selections
• Trade-off decisions
• Security decisions

code-patterns.md

Reusable code snippets and patterns:

• Error handling patterns
• API patterns
• Component patterns
• Testing patterns

lessons-learned.md

Bugs, gotchas, and hard-won knowledge:

• Bug root causes and fixes
• Common mistakes to avoid
• Environment-specific issues
• Integration gotchas

tools-reference.md

Commands and tool quick reference:

• MCP tool usage
• CLI commands
• Development commands
• Debugging tips

Best Practices

1. Be specific: Include file paths, error messages, concrete details
2. Add context: Explain why, not just what
3. Use tags: Enable searchability with consistent tags
4. Date entries: Always include date for temporal context
5. Cross-reference: Link related memories when applicable
6. Keep it lean: One concept per entry, expand in follow-ups

Additional Resources

Reference Files

For detailed patterns and templates:

• references/memory-templates.md - Entry templates for each category
• references/tagging-guide.md - Comprehensive tagging conventions

Example Files

Working memory entries:

• examples/decision-entry.md - Sample decision log entry
• examples/pattern-entry.md - Sample pattern entry
• examples/lesson-entry.md - Sample lesson learned entry