collective-memory

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

1. Store: Content is embedded using OpenAI's text-embedding-3-small (768 dimensions)
2. Dedupe: Before storing, checks for >95% similar existing memories
3. Index: Stored in LanceDB, an embedded vector database
4. 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.