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: ``bash npm run export # Outputs to viz/memories.json ``

To visualize: ``bash npm run dash # Opens UMAP visualization at localhost:3333 ``

License

MIT

Credits

Built by The Victor Collective.

collective-memory