claudemem — Your Persistent Memory

Memory that carries across conversations. Automatically captures important knowledge during work and saves structured session summaries when you're done. Searches past context before new tasks.

Slash Commands

• /wrap-up — End-of-session save: extracts ALL important knowledge + saves session summary in one step. Deduplicates automatically.
• /save-session — Save only the session summary (without extracting notes)
• /recall [topic] — Search persistent memory for a topic, or show recent activity

Natural Trigger Phrases

These natural phrases also activate memory operations:

To save knowledge:

• "remember this" / "save this" / "note this down" / "keep this in mind"

To search memory:

• "what do you remember about..." / "do you recall..." / "what do we know about..."

To wrap up (save everything):

• "wrap up" / "let's wrap up" / "save everything" — triggers /wrap-up (notes + session)
• "save this session" / "summarize what we did" — triggers /save-session (session only)

To recall past work:

• "what did we do last time" / "show me recent sessions" / "what happened with [topic]"

Setup

Before first use, verify the CLI is installed. If claudemem is not found on PATH, install it:

curl -fsSL https://raw.githubusercontent.com/zelinewang/claudemem/main/skills/claudemem/scripts/install.sh | bash

Or run the bundled installer:

bash "SKILL_DIR/scripts/install.sh"

After installation, verify with claudemem --version.

Commands

# Notes (knowledge fragments)
claudemem note add <category> --title "..." --content "..." --tags "tag1,tag2"
claudemem note search "query" [--in category] [--tag tags]
claudemem note list [category]
claudemem note get <id>
claudemem note update <id> --content "..." [--title "..."] [--tags "..."]
claudemem note append <id> "additional content"
claudemem note delete <id>
claudemem note categories
claudemem note tags

# Sessions (conversation summaries)
claudemem session save --title "..." --branch "..." --project "..." --session-id "..." --content "..."
claudemem session list [--last N] [--date today] [--date-range 7d] [--branch X]
claudemem session search "query" [--branch X]
claudemem session get <id>

# Unified search (across notes AND sessions)
claudemem search "query" [--type note|session] [--limit N]

# Statistics
claudemem stats

# Configuration
claudemem config set/get/list/delete <key> [value]

# Data portability
claudemem export [output-file]              # Backup as tar.gz
claudemem import <archive-file>             # Restore from backup (auto-reindexes)

# Data integrity
claudemem verify                            # Check DB-file consistency
claudemem repair                            # Fix orphaned entries

Add --format json to any command for structured output.

Autonomous Behavior

Recommended: Auto Wrap-Up Before Session Ends

If the user has enabled auto wrap-up in their CLAUDE.md, automatically execute /wrap-up before the conversation ends:

1. Extract unsaved knowledge fragments → save as notes (with dedup)
2. Generate session summary → save as session
3. Show brief report of what was saved

Auto-Save Notes (Silent + Brief Indicator)

Automatically capture knowledge without asking during normal conversation. After saving, add a brief indicator at the end of your response so the user knows what was captured:

[📝 Saved: "TikTok Rate Limits" → api-specs]

What to auto-save (proactive, no user prompt needed):

• API specs, field mappings, rate limits, endpoint details
• Technical decisions with rationale (why X over Y)
• Integration quirks, gotchas, workarounds
• Resolved bugs and their root causes
• Configuration requirements and defaults
• User preferences and project conventions
• Important URLs, endpoints, environment configs

How to auto-save gracefully:

1. Identify the knowledge fragment during your normal response
2. Choose an appropriate category (create new if none fits)
3. Before saving, quickly search to avoid duplicates: claudemem note search "keyword" --format json
4. If related note exists: claudemem note append <id> "new info" instead of creating duplicate
5. Save: claudemem note add <category> --title "..." --content "..." --tags "..."
6. Show the indicator: [📝 Saved: "<title>" → <category>]

Do NOT auto-save:

• Temporary debugging output or transient state
• File paths or code snippets without context
• General programming knowledge available in docs
• Information the user is likely to change immediately

Auto-Search Before Tasks (Silent)

Search memory at the start of tasks that might benefit from prior context:

• Before implementing a feature in a domain previously discussed
• When working with an API or system previously documented
• Before making architectural decisions

Search silently. If relevant results found, mention them briefly:

[🔍 Found related memory: "TikTok Rate Limits" — rate limit is 100/min]

Save Sessions (On Request via /save-session or Natural Phrase)

Session summaries are saved when the user explicitly asks — via /save-session command or natural phrases like "save this session" or "wrap up". Do NOT auto-save sessions without the user's request, as they may want to continue the conversation.

Workflow Rules

1. Before saving: search existing content first — update or append if related note exists
2. Before working: search for relevant context that may inform the current task
3. Merge related information under existing categories/titles when possible
4. Preserve existing content unless contradicted by new information
5. Focus on evergreen knowledge, not transient conversation artifacts

Session Summary Template

When saving a session, generate content following this structure:

## Summary
One or two paragraphs describing what was accomplished.

## Key Decisions
- Decision 1 with rationale
- Decision 2 with rationale

## What Changed
- `path/to/file.py` — Description of change

## Problems & Solutions
- **Problem**: Description of issue
  **Solution**: How it was resolved

## Questions Raised
- Open question needing future attention

## Next Steps
- [ ] First follow-up task

What NOT to Capture

• Temporary debugging sessions or transient state
• File paths or code snippets without context
• General programming knowledge available in docs
• Meta-commentary about the conversation itself
• Information that changes frequently without lasting value

Data Portability

All data stored at ~/.claudemem/ as plain Markdown files with YAML frontmatter. SQLite FTS5 index is a rebuildable cache — only the Markdown files matter.

Backup: claudemem export backup.tar.gz Restore: claudemem import backup.tar.gz (auto-rebuilds search index)

Storage

~/.claudemem/ — Plain text Markdown files organized by type (notes/ and sessions/). FTS5 SQLite index for sub-10ms full-text search. File permissions: 0600/0700.