collective-memory

Collective Memory

用于在 AI 会话间持久保存语义记忆的 MCP 服务。存储上下文、决策和经验总结，之后可通过自然语言搜索找回。

为什么需要

AI 助手会忘记不同会话之间的所有内容。Collective Memory 可以解决这个问题。存储重要信息，按含义搜索，构建不断积累的上下文。

功能

• 语义搜索 — 按含义而非关键词查找记忆（OpenAI 嵌入 + LanceDB）
• 自动去重 — 不会存储近似重复项（相似度 >95%）
• 项目范围 — 按项目整理记忆
• 类型分类 — 分类为 decision、milestone、context、learning 或 session_summary
• 零配置存储 — 嵌入式向量数据库，无需服务器

安装

npm install -g collective-memory

或者克隆并构建：

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

设置

1. 获取 OpenAI API 密钥

嵌入功能需要此密钥。请前往 platform.openai.com 获取。

2. 添加到 Claude Code

在 ~/.claude/settings.json 的 mcpServers 下添加：

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

或者，如果从源代码安装：

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

3. 在 CLAUDE.md 中添加使用说明

在全局 ~/.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.

工具

remember

存储带语义嵌入的记忆。

参数	类型	必需	描述
content	字符串	是	要存储的记忆——内容应具体且自成一体
project	字符串	否	项目上下文（例如，“myapp”、“client-x”）
type	字符串	否	可选值：decision、milestone、context、learning、session_summary
tags	字符串[]	否	用于分类的标签

返回已存储记忆的 ID；如果检测到重复，则返回现有 ID。

recall

按语义相似度搜索记忆。

参数	类型	必需	描述
query	字符串	是	自然语言搜索查询
project	字符串	否	筛选指定项目
type	字符串	否	按特定记忆类型筛选
limit	数字	否	最大结果数（默认值：10）

返回包含相似度分数的匹配记忆数组。

CLI

也可通过命令行使用：

# 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

配置

环境变量	默认值	描述
OPENAI_API_KEY	（必需）	用于嵌入的 OpenAI API 密钥
COLLECTIVE_MEMORY_PATH	~/.collective-memory/data	存储位置

工作原理

1. 存储：使用 OpenAI 的 text-embedding-3-small 将内容转换为嵌入（768 维）
2. 去重：存储前，检查是否存在相似度 >95% 的记忆
3. 索引：存储在 LanceDB 嵌入式向量数据库中
4. 搜索：将查询转换为嵌入，并通过余弦相似度进行匹配

数据

记忆存储在本地 ~/.collective-memory/data（或 COLLECTIVE_MEMORY_PATH）中。这是一个 LanceDB 数据库，可移植且无需服务器进程。

导出记忆：

npm run export  # Outputs to viz/memories.json

可视化：

npm run dash    # Opens UMAP visualization at localhost:3333

许可证

MIT

致谢

由 The Victor Collective 构建。