claude-crowed

A persistent semantic memory system for Claude Code, built as an MCP server. Replaces Claude Code's built-in flat-file memories with a structured, searchable, versioned document store.

Features

• Semantic search via sentence-transformers (nomic-embed-text-v1.5) + sqlite-vec
• Versioned memories with full history (update creates a new version, old versions preserved)
• Soft-delete with rate limiting (5 per session) and undo
• Dynamic "see also" via embedding nearest-neighbor lookup (no manual linking needed)
• Duplicate detection with adjustable similarity threshold
• Timeline browsing with cursor-based pagination
• Export/import for backup and portability
• Migration tool to import existing CLAUDE.md and auto-memory files
• Hot-reload dev mode via stdio proxy that watches for git commits
• Web visualizer — force-directed graph of memories with search, detail browsing, and CRUD

Install

uv sync

Setup

claude mcp add --scope user claude-crowed -- uv run --directory /path/to/claude-crowed claude-crowed

Then add the memory directive to your ~/.claude/CLAUDE.md so Claude knows to use it.

The core principle is that crowed is a memoization layer for Claude Code. Every piece of knowledge, research, implementation detail, design decision, open question, or idea should flow through crowed so that future sessions can skip the work entirely. Before you think, search. Before you conclude, store. If a prior session already figured something out, reuse it — don't re-derive it.

## Memory System (claude-crowed)

You have access to a persistent memory system via MCP tools (server: claude-crowed).
**This is your memoization layer.** The whole point is to avoid repetitive work and
thinking across sessions. Every piece of knowledge, research, implementation detail,
design decision, open question, or idea that you produce should flow through crowed
so that future sessions can skip the work entirely.

Think of crowed as a cache: before you think, search. Before you conclude, store.
If a prior session already figured something out, reuse it — don't re-derive it.

### Search Discipline
- At the **START** of every task, call `memory_recall` (or `memory_search`) with relevant keywords.
  Do not skip this step — you have no passive context from crowed without it.
- **Mid-task**: whenever you encounter unfamiliar code, patterns, or errors, search again.
  Don't only search at the beginning — search whenever you hit something you might have seen before.
- **Before expensive work**: always search before launching an Explore agent, doing
  multi-file Grep/Glob sweeps, or calling WebSearch/WebFetch. A prior session may have
  already answered the question — skip the work if it has.
- **Before forming a plan**: search for prior plans, design decisions, or rejected
  approaches. Don't re-propose something that was already tried and failed.
- Use `memory_recall` to combine search + read in one call (fewer round trips).
  Use `memory_search` + `memory_read` when you need finer control.

### When to Store
Store **anything** a future session might need. If you thought about it, researched it,
or figured it out, it belongs in crowed. Specific triggers:

- **After diagnosing a root cause**: "The problem was X because Y" is always worth storing.
- **When you discover a gotcha or workaround**: non-obvious behavior, API quirks,
  config footguns — things that would cost a future session time to rediscover.
- **After codebase exploration**: when you map out how a module, feature, or subsystem works,
  store the finding. Frame it as the question a future session would ask.
- **After web research**: store the *actionable conclusion* — not the URL.
- **After a user correction**: store it immediately — prevents the same wrong suggestion next time.
- **After every git commit**: store novel decisions, patterns, or architecture.
- **When you form an implementation plan**: store the plan, the alternatives considered,
  and why you chose this approach. Future sessions shouldn't re-derive the same plan.
- **When you have an open question or idea**: store it so it's not lost between sessions.
- **When you read and understand a complex code path**: store the summary. Reading code
  is expensive — don't make the next session re-read and re-understand the same thing.
- **Don't batch**: store as you go, not at the end. Mid-task insights are the most valuable
  and the easiest to forget.

### Storage Rules
- Title (max 150 chars): Must be a complete thought, not a label. Another instance of you
  should judge relevance from the title alone.
- Content (max 1500 chars): One insight per memory. Split larger ideas into multiple memories.
- Prefer creating NEW memories over updating existing ones unless refining the same idea.

### Do NOT
- Accumulate knowledge in this file or in auto-memory files. Crowed is the single source of truth.
- Fetch all search results — be selective (usually 1-5).
- Delegate memory_store to a subagent.
- Re-derive something that crowed already knows. Search first, always.

Usage

MCP Tools (used by Claude)

Tool	Purpose
memory_search	Semantic search, returns titles only
memory_read	Fetch full content of a memory
memory_recall	Search + read top results in one call (fewer round trips)
memory_store	Store a new memory (with dedup check)
memory_update	Create a new version of a memory
memory_delete	Soft-delete (rate-limited, reversible)
memory_undelete	Restore a deleted memory
memory_history	View all versions of a memory
memory_timeline	Browse chronologically with pagination
memory_related	Find semantically similar memories (dynamic nearest-neighbor)
memory_export	Export all data to JSON
memory_import	Import from JSON export
memory_migrate	Discover and split existing memory files for migration
memory_threshold	View/adjust duplicate similarity threshold
memory_stats	Summary statistics

CLI

# Start MCP server (default, stdio transport)
claude-crowed serve

# Development mode with hot-reload on git commits
claude-crowed dev

# Export/import
claude-crowed export [--output path]
claude-crowed import <path> [--overwrite]

# Restore from backup
claude-crowed restore <backup-path>

# Rebuild embedding index
claude-crowed rebuild-embeddings

# Show stats
claude-crowed stats

# Launch web visualizer (opens browser)
claude-crowed visualize [--port 4242] [--no-browser]

Visualizer

The web visualizer shows all memories as a force-directed graph. Nodes are colored by age (blue = recent, gold = older). Similarity edges connect semantically related memories via dynamic nearest-neighbor lookup.

uv sync --extra visualizer
uv run claude-crowed visualize

The frontend is built automatically on launch if visualizer/dist/ is missing or stale (requires npm). It skips the build if the dist is already up to date.

Features:

• Force-directed graph with age coloring and similarity-based clustering
• Labels appear progressively as you zoom in
• Semantic search (press / to focus)
• Click any node to browse its content and metadata
• Delete/restore memories from the detail panel

Architecture

• SQLite with WAL mode for the memory store
• sqlite-vec for vector similarity search (vec0 virtual tables)
• sentence-transformers with nomic-embed-text-v1.5 (768-dim, CPU by default)
• Background model loading — embedding model loads in a thread during MCP handshake (~1s startup)
• Two-phase retrieval — search returns titles/metadata, read fetches full content
• Embedding prefixes — search_document: for storage, search_query: for retrieval

Data

All data is stored in ~/.local/share/claude-crowed/:

• crowed.db — SQLite database
• backups/ — rolling backups (max 30, created on each server start)
• exports/ — JSON exports

Tests

uv run pytest