SpecMem

Memory that makes Claude actually remember.

What is SpecMem?

SpecMem is an MCP (Model Context Protocol) server that gives Claude persistent, semantic memory across sessions. Instead of starting every conversation from scratch, Claude remembers your codebase, your decisions, your preferences, and the context that matters.

One command. That's it:

specmem init

Claude connects automatically. No config files to edit. No environment variables to set. Just memory that works.

Quick Start

Prerequisites

  • Node.js 18+
  • Docker (for local embeddings)
  • Claude Code CLI

Installation

# Install globally
npm install -g specmem

# Initialize in your project
cd /path/to/your/project
specmem init

That's it. Two commands. Claude now has memory.

What Happens

  1. Database Setup: PostgreSQL + pgvector spins up automatically
  2. Embedding Service: Local MiniLM model starts in Docker (no API keys needed)
  3. MCP Configuration: Claude Code gets configured to use SpecMem
  4. Session Extraction: Your conversation history becomes searchable memories

Verify It Works

Open Claude Code in your project:

claude

Ask Claude: "What do you remember about this project?"

If SpecMem is working, Claude will have context from previous sessions.

Configuration (Optional)

SpecMem works out of the box, but you can customize via environment variables:

Variable Default Description
SPECMEM_DASHBOARD_PORT 8585 Web dashboard port
SPECMEM_COORDINATION_PORT 8596 Team coordination server
SPECMEM_MEMORY_LIMIT 250 Max heap MB

Troubleshooting

Claude doesn't see memories?

specmem status  # Check if services are running
specmem logs    # View recent logs

Embedding service not starting?

docker ps | grep specmem  # Check Docker containers
specmem restart           # Restart all services

Why SpecMem?

The Problem with Other Memory MCPs

Most memory solutions treat Claude like a search engine: dump text in, grep it back out. That's not memory - that's a filing cabinet.

Keyword search fails when:

  • You remember the concept but not the exact words
  • You want "that authentication fix from last week"
  • You're searching code you didn't write
  • Your naming conventions evolve

SpecMem is Different

SpecMem uses semantic search powered by vector embeddings. You search by meaning, not by matching strings.

You ask SpecMem finds
"user login stuff" Authentication handlers, session management, JWT code
"that bug with the API" The specific conversation where you debugged the rate limiting issue
"how we handle errors" Error boundaries, try-catch patterns, logging utilities

It's the difference between grep and having a colleague who actually remembers your project.

The "Claude Just Works" Philosophy

SpecMem was built with one principle: Claude should feel smarter, not require more work from you.

  • Auto-extraction: Your Claude Code sessions become memories automatically
  • Project-aware: Memories stay scoped to the right project
  • Self-maintaining: Old memories consolidate; irrelevant ones fade
  • Zero-config: specmem init handles everything

You don't manage SpecMem. You just use Claude, and Claude remembers.

Key Capabilities

1. Persistent Context Every conversation builds on the last. Ask Claude about code you discussed three months ago.

2. Semantic Code Search Find functions by what they do, not what they're named. Trace callers and callees automatically.

3. Team Coordination Multiple Claude instances can coordinate, claim tasks, and share findings through built-in team messaging.

4. Cross-Project Intelligence Search memories across all your projects. Find that pattern you used in another repo.

5. Production-Ready Scale PostgreSQL + pgvector backend. 100k+ memories? No problem.

Architecture

SpecMem is built on a layered architecture designed for reliability, semantic intelligence, and multi-agent coordination.

+------------------------------------------------------------------+
|                        CLAUDE (MCP Client)                        |
+------------------------------------------------------------------+
                              |
                         MCP Protocol
                              |
+------------------------------------------------------------------+
|                     SPECMEM MCP SERVER                            |
|  +--------------------+  +--------------------+  +---------------+ |
|  |   Memory Tools     |  |   Code Tools       |  |  Team Tools   | |
|  | save_memory        |  | find_code_pointers |  | send_message  | |
|  | find_memory        |  | drill_down         |  | read_messages | |
|  | get_memory         |  | check_sync         |  | claim_task    | |
|  | smush_memories     |  | force_resync       |  | get_status    | |
|  +--------------------+  +--------------------+  +---------------+ |
+------------------------------------------------------------------+
                              |
         +--------------------+--------------------+
         |                    |                    |
+----------------+   +-----------------+   +------------------+
|   Embedding    |   |    PostgreSQL   |   |   Coordination   |
|    Service     |   |   + pgvector    |   |     Server       |
| (Frankenstein) |   |                 |   |   (Port 8596)    |
+----------------+   +-----------------+   +------------------+

Core Components

1. PostgreSQL + pgvector (Memory Storage)

All memories live in PostgreSQL with the pgvector extension for vector similarity search.

Why PostgreSQL?

  • Battle-tested reliability for 100k+ memories
  • ACID transactions for data integrity
  • pgvector enables cosine similarity search on embeddings
  • No separate vector database needed

Memory Table Structure:

  • id: UUID primary key
  • content: The actual memory text
  • embedding: 384-dimensional vector (auto-detected from model)
  • memory_type: episodic | semantic | procedural | working | consolidated
  • importance: critical | high | medium | low | trivial
  • tags: Array for categorization
  • project_path: Scopes memories to specific projects
  • created_at, updated_at, accessed_at: Temporal tracking
  • expires_at: Optional TTL for working memories

2. Frankenstein Embedding Service (Local Embeddings)

The "Frankenstein" embedding service runs locally, generating 384-dimensional vectors using MiniLM.

Why Local?

  • Zero API costs
  • No rate limits
  • Works offline
  • Fast (sub-100ms per embedding)
  • Privacy: your data never leaves your machine

Architecture:

  • Air-gapped Docker container with no network access
  • Unix socket communication
  • 4GB RAM limit with auto-throttling
  • Fallback hash embeddings when container unavailable

3. Memory Types (Cognitive Architecture)

SpecMem implements a cognitive memory model inspired by human memory systems:

Type Purpose Example Typical TTL
Episodic Specific events/conversations "User asked about auth bug on Jan 15" Permanent
Semantic Facts and knowledge "Project uses PostgreSQL 15" Permanent
Procedural How-to instructions "To deploy: run ./deploy.sh" Permanent
Working Current session context "Currently debugging auth flow" 24 hours
Consolidated Merged/summarized memories Summary of 50 related memories Permanent

4. Consolidation System (Memory Maintenance)

The smush_memories_together tool intelligently merges similar memories:

Strategies:

  • similarity: Vector clustering (default) - groups semantically similar content
  • temporal: Time-based - groups memories from same time period
  • tag_based: Shared tags - groups by common categorization
  • importance: Priority-based - preserves critical, consolidates trivial

5. Code Indexing Architecture

SpecMem indexes your entire codebase for semantic code search.

What Gets Indexed:

  • Function/method definitions
  • Class definitions
  • Interface/type definitions
  • Variable/constant declarations

Traceback System: When you search for code, SpecMem shows:

  • Who calls this function
  • What this function calls
  • Import/dependency chain

6. Team Coordination Layer

SpecMem enables multiple Claude instances to work together.

Components:

  • Coordination Server (Port 8596)
  • Message routing between team members
  • Task claiming and release
  • Heartbeat-based presence detection

Features

Semantic Memory Search (find_memory)

Search memories by meaning, not just keywords.

Key Parameters:

Parameter Type Default Description
query string - Natural language search query
limit number 10 Max results (1-1000)
threshold number 0.25 Similarity score threshold (0-1)
memoryTypes array all Filter by memory type
importance array all Filter by importance
allProjects boolean false Search across ALL projects
cameraRollMode boolean false Return drilldown IDs for exploration
galleryMode boolean false Enable Mini COT analysis

Example:

find_memory({
  query: "authentication implementation",
  limit: 15,
  memoryTypes: ["semantic", "procedural"],
  importance: ["high", "critical"]
})

Semantic Code Search (find_code_pointers)

Find code by meaning with caller/callee tracebacks.

Key Parameters:

Parameter Type Default Description
query string - Natural language description
language string - Filter: typescript, python, go, etc.
definitionTypes array - Filter: function, class, interface, etc.
includeTracebacks boolean true Show callers/callees
zoom number 50 Detail level 0-100

Example:

find_code_pointers({
  query: "user authentication middleware",
  language: "typescript",
  includeTracebacks: true,
  zoom: 30
})

Memory Storage (save_memory)

Store memories with automatic embedding generation.

Parameters:

Parameter Type Default Description
content string required Memory content (unlimited length)
memoryType string semantic episodic, semantic, procedural, working
importance string medium critical, high, medium, low, trivial
tags array [] Categorization tags

Team Coordination

Full multi-agent communication system.

Core Tools:

  • send_team_message: Post to team channel with @mentions
  • read_team_messages: Check for updates
  • claim_task: Reserve files/tasks to avoid conflicts
  • release_task: Free when done
  • get_team_status: See who's working on what
  • request_help: Broadcast help requests
  • broadcast_to_team: System-wide announcements

Camera Roll Mode

Interactive memory browsing with drill-down exploration.

Zoom Levels:

Level Results Threshold Use Case
ultra-wide 50 15% Broad exploration
wide 25 25% General search
normal 15 40% Balanced
close 10 60% Focused
macro 5 80% Precision

Session Extraction

Automatically extract Claude Code sessions into searchable memories.

Tools:

  • extract-claude-sessions: Manual extraction from session files
  • get-session-watcher-status: Check auto-extraction status
  • extract-context-restorations: Parse context overflow summaries

File Watching and Sync

Keep memories in sync with filesystem changes.

Tools:

  • start_watching: Monitor codebase for changes
  • stop_watching: Pause monitoring
  • check_sync: Verify memory-filesystem sync
  • force_resync: Full resync of codebase

Cross-Project Search

Search across all your projects from one place.

find_memory({
  query: "authentication pattern",
  allProjects: true
})

Research Agent Spawning

Deploy Claude subprocesses for web research.

spawn_research_teamMember({
  topic: "latest React 19 features",
  depth: "medium",  // quick, medium, thorough
  saveToMemory: true
})

Dashboard

Access the web dashboard at http://localhost:8585 (default port).

Features:

  • Memory browser with semantic search
  • Codebase explorer with dependencies
  • Team member activity monitor
  • Statistics and metrics view
  • Syntax highlighted content

Environment Variables

Variable Default Description
SPECMEM_DB_HOST localhost PostgreSQL host
SPECMEM_DB_PORT 5432 PostgreSQL port
SPECMEM_DB_NAME specmem_* Database name
SPECMEM_COORDINATION_PORT 8596 Team server port
SPECMEM_DASHBOARD_PORT 8585 Web UI port
SPECMEM_DASHBOARD_PASSWORD required Dashboard password
SPECMEM_MEMORY_LIMIT 250 Max heap MB
SPECMEM_CACHE_SIZE 500 Embedding cache entries
SPECMEM_CODEBASE_WATCH true Auto-index on file change
SPECMEM_SESSION_WATCHER_ENABLED true Auto-extract sessions

Database Schema

Core Tables

memories - Main memory storage

  • id, content, content_hash, embedding
  • memory_type, importance, tags, metadata
  • created_at, updated_at, access_count
  • expires_at, project_path

memory_relations - Memory graph

  • source_id, target_id, relation_type, strength

codebase_files - Indexed files

  • file_path, content, embedding, content_hash
  • language_id, size_bytes, line_count

code_definitions - Symbols

  • file_id, name, type, line_number
  • signature, documentation

team_member_messages - Inter-agent messages

  • from_team_member, to_team_member, message
  • priority, read_at, created_at

Key Indexes

  • HNSW on embeddings for vector search
  • GIN on tags for array queries
  • GiST with pg_trgm for fuzzy text
  • B-tree on timestamps for ranges

Performance

  • Vector search under 50ms typical
  • 100k+ memories handled efficiently
  • File indexing 500+ files per minute
  • Connection pooling for concurrency
  • Embedding cache reduces API calls
  • Change tracking via triggers (zero overhead)

Why This Architecture?

PostgreSQL over specialized vector DBs: One database for everything. No Pinecone/Weaviate complexity. pgvector is production-ready.

Local embeddings over API: Cost, speed, privacy. MiniLM is good enough for code/conversation similarity.

MCP-native team coordination: No Redis/RabbitMQ. Memories ARE messages. Simple and searchable.

Cognitive memory types: Not all memories are equal. Working memory expires. Semantic memory persists. Consolidation prevents bloat.

Contributing

See license.md to see how you should properly commit and inform community of changes.

License

See license.md - Supercedes readme.

Credits

Built with Node.js, TypeScript, PostgreSQL, pgvector, and MCP.

Questions? Open an issue. Found a bug? PRs welcome. Like it? Star the repo.