{
  "markdown": "# Collective Memory\n\nMCP server for persistent, semantic memory across AI sessions. Store context, decisions, and learnings — recall them later with natural language search.\n\n## Why\n\nAI assistants forget everything between sessions. Collective Memory fixes that. Store what matters, search by meaning, build context that compounds.\n\n## Features\n\n- **Semantic search** — Find memories by meaning, not keywords (OpenAI embeddings + LanceDB)\n- **Automatic deduplication** — Won't store near-duplicates (>95% similarity)\n- **Project scoping** — Organize memories by project\n- **Type classification** — Categorize as `decision`, `milestone`, `context`, `learning`, or `session_summary`\n- **Zero config storage** — Embedded vector database, no server required\n\n## Installation\n\n```bash\nnpm install -g collective-memory\n```\n\nOr clone and build:\n\n```bash\ngit clone https://github.com/Hustada/collective-memory.git\ncd collective-memory\nnpm install\nnpm run build\n```\n\n## Setup\n\n### 1. Get an OpenAI API key\n\nRequired for embeddings. Get one at [platform.openai.com](https://platform.openai.com/api-keys).\n\n### 2. Add to Claude Code\n\nAdd to `~/.claude/settings.json` under `mcpServers`:\n\n```json\n{\n  \"mcpServers\": {\n    \"collective-memory\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"collective-memory\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\nOr if installed from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"collective-memory\": {\n      \"type\": \"stdio\",\n      \"command\": \"node\",\n      \"args\": [\"/path/to/collective-memory/dist/index.js\"],\n      \"env\": {\n        \"OPENAI_API_KEY\": \"sk-...\"\n      }\n    }\n  }\n}\n```\n\n### 3. Add usage instructions to CLAUDE.md\n\nAdd to your global `~/.claude/CLAUDE.md`:\n\n```markdown\n## Memory\n\nCollective Memory is active. Two tools:\n\n- `remember(content, project?, type?, tags?)` — Persist important context\n- `recall(query, project?, type?, limit?)` — Search memory\n\n**On session start**: Run `recall(\"recent decisions and context\")` to load relevant memory.\n\nWhen to remember: after decisions, milestones, completed work, learned patterns.\nWhen to recall: session start, context switches, referencing past work.\n\nTypes: decision, milestone, context, learning, session_summary.\n```\n\n## Tools\n\n### remember\n\nStore a memory with semantic embedding.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `content` | string | yes | The memory to store — be specific and self-contained |\n| `project` | string | no | Project context (e.g., \"myapp\", \"client-x\") |\n| `type` | string | no | One of: decision, milestone, context, learning, session_summary |\n| `tags` | string[] | no | Tags for categorization |\n\nReturns the stored memory ID, or existing ID if deduplicated.\n\n### recall\n\nSearch memories by semantic similarity.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `query` | string | yes | Natural language search query |\n| `project` | string | no | Filter to specific project |\n| `type` | string | no | Filter to specific memory type |\n| `limit` | number | no | Max results (default: 10) |\n\nReturns array of matching memories with similarity scores.\n\n## CLI\n\nAlso usable from command line:\n\n```bash\n# Store a memory\ncollective-memory remember --content \"Decided to use PostgreSQL for the auth service\"\n\n# Search memories\ncollective-memory recall --query \"database decisions\" --limit 5\n\n# Pipe content from stdin\necho \"Long content here\" | collective-memory remember --content-stdin --project myapp\n```\n\n## Configuration\n\n| Environment Variable | Default | Description |\n|---------------------|---------|-------------|\n| `OPENAI_API_KEY` | (required) | OpenAI API key for embeddings |\n| `COLLECTIVE_MEMORY_PATH` | `~/.collective-memory/data` | Storage location |\n\n## How it works\n\n1. **Store**: Content is embedded using OpenAI's `text-embedding-3-small` (768 dimensions)\n2. **Dedupe**: Before storing, checks for >95% similar existing memories\n3. **Index**: Stored in LanceDB, an embedded vector database\n4. **Search**: Queries are embedded and matched via cosine similarity\n\n## Data\n\nMemories are stored locally at `~/.collective-memory/data` (or `COLLECTIVE_MEMORY_PATH`). It's a LanceDB database — portable, no server process.\n\nTo export memories:\n```bash\nnpm run export  # Outputs to viz/memories.json\n```\n\nTo visualize:\n```bash\nnpm run dash    # Opens UMAP visualization at localhost:3333\n```\n\n## License\n\nMIT\n\n## Credits\n\nBuilt by [The Victor Collective](https://victorcollective.com).\n",
  "bytes": 4558,
  "sha": "31d9510ba7ea612a8e5b860a4c103c7d6c7a05f1613880c84c6761ef85a193d3",
  "repo_slug": "hustada/collective-memory",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_hustada_collective_memory_24fcef51/readme"
}