Collective Memory

MCP server for persistent, semantic memory across AI sessions. Store context, decisions, and learnings — recall them later with natural language search.

Why

AI assistants forget everything between sessions. Collective Memory fixes that. Store what matters, search by meaning, build context that compounds.

Features

Semantic search — Find memories by meaning, not keywords (OpenAI embeddings + LanceDB)
Automatic deduplication — Won't store near-duplicates (>95% similarity)
Project scoping — Organize memories by project
Type classification — Categorize as decision, milestone, context, learning, or session_summary
Zero config storage — Embedded vector database, no server required

Installation

npm install -g collective-memory

Or clone and build:

git clone https://github.com/Hustada/collective-memory.git
cd collective-memory
npm install
npm run build

Setup

1. Get an OpenAI API key

Required for embeddings. Get one at platform.openai.com.

2. Add to Claude Code

Add to ~/.claude/settings.json under mcpServers:

{
  "mcpServers": {
    "collective-memory": {
      "type": "stdio",
      "command": "npx",
      "args": ["collective-memory"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Or if installed from source:

{
  "mcpServers": {
    "collective-memory": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/collective-memory/dist/index.js"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

3. Add usage instructions to CLAUDE.md

Add to your global ~/.claude/CLAUDE.md:

## Memory

Collective Memory is active. Two tools:

- `remember(content, project?, type?, tags?)` — Persist important context
- `recall(query, project?, type?, limit?)` — Search memory

**On session start**: Run `recall("recent decisions and context")` to load relevant memory.

When to remember: after decisions, milestones, completed work, learned patterns.
When to recall: session start, context switches, referencing past work.

Types: decision, milestone, context, learning, session_summary.

Tools

remember

Store a memory with semantic embedding.

Parameter	Type	Required	Description
`content`	string	yes	The memory to store — be specific and self-contained
`project`	string	no	Project context (e.g., "myapp", "client-x")
`type`	string	no	One of: decision, milestone, context, learning, session_summary
`tags`	string[]	no	Tags for categorization

Returns the stored memory ID, or existing ID if deduplicated.

recall

Search memories by semantic similarity.

Parameter	Type	Required	Description
`query`	string	yes	Natural language search query
`project`	string	no	Filter to specific project
`type`	string	no	Filter to specific memory type
`limit`	number	no	Max results (default: 10)

Returns array of matching memories with similarity scores.

CLI

Also usable from command line:

# Store a memory
collective-memory remember --content "Decided to use PostgreSQL for the auth service"

# Search memories
collective-memory recall --query "database decisions" --limit 5

# Pipe content from stdin
echo "Long content here" | collective-memory remember --content-stdin --project myapp

Configuration

Environment Variable	Default	Description
`OPENAI_API_KEY`	(required)	OpenAI API key for embeddings
`COLLECTIVE_MEMORY_PATH`	`~/.collective-memory/data`	Storage location

How it works

Store: Content is embedded using OpenAI's text-embedding-3-small (768 dimensions)
Dedupe: Before storing, checks for >95% similar existing memories
Index: Stored in LanceDB, an embedded vector database
Search: Queries are embedded and matched via cosine similarity

Data

Memories are stored locally at ~/.collective-memory/data (or COLLECTIVE_MEMORY_PATH). It's a LanceDB database — portable, no server process.

To export memories:

npm run export  # Outputs to viz/memories.json

To visualize:

npm run dash    # Opens UMAP visualization at localhost:3333

License

MIT

Credits

Built by The Victor Collective.

collective memory