memory

ShackleAI 记忆

为 AI 编码工具提供持久记忆。首个原生 MCP 记忆服务。

让 Claude Code、Cursor、Windsurf、VS Code Copilot、OpenAI Codex 或任何兼容 MCP 的 AI 工具都能跨会话持久记忆。你的 AI 会记住决策、约定、错误和上下文，并准确接续你上次的工作。

安装 — 一条命令

在项目目录中运行：

npx -y @shackleai/memory-mcp@latest setup

这会在你的项目中创建两个文件：

• .mcp.json — 注册记忆服务，让你的 AI 工具自动启动它
• CLAUDE.md — 告诉 AI 在每个会话中主动使用记忆

将这两个文件都提交到 git，让整个团队都能使用记忆。就这么简单——无需配置、API 密钥或账户。

npm/npx 版本太旧？ 如果命令失败，请参阅故障排除。

工作原理

1. Run the setup command above (one-time)
2. Start your AI tool in the project directory
3. Memory server starts automatically in the background
4. AI stores decisions, conventions, and bugs as you work
5. Next session — AI searches memory and picks up where you left off

**设置完成后，你无需做任何操作。**AI 会看到记忆工具并主动使用它们——存储重要决策、搜索过往上下文，并保存会话摘要。

验证是否正常运行

设置完成后，启动一个会话并给 AI 一个任务。然后询问：

“到目前为止，你在记忆中存储了什么？”

如果它调用 memory_search 并显示已存储的条目，就说明一切正常。在下一个会话中，询问：

“你还记得这个项目的哪些内容？”

它应该能回忆起上一个会话的上下文，而无需读取任何文件。

其他设置方法

npx setup 命令适用于所有 MCP 客户端。如果你更倾向于使用特定客户端的配置：

claude mcp add memory -- npx -y @shackleai/memory-mcp@latest

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@shackleai/memory-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@shackleai/memory-mcp@latest"]
    }
  }
}

{
  "servers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@shackleai/memory-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@shackleai/memory-mcp@latest"]
    }
  }
}

npm install -g @shackleai/memory-mcp
shackleai-memory setup

{
  "mcpServers": {
    "memory": {
      "command": "shackleai-memory"
    }
  }
}

git clone https://github.com/shackleai/memory-mcp.git
cd memory-mcp && npm install && npm run build

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/absolute/path/to/memory-mcp/dist/index.js"]
    }
  }
}

首次运行

首次运行时会下载嵌入模型（约 80MB，仅需下载一次）。之后，所有功能都可离线运行。

功能

• 一条命令即可完成设置 — 执行 npx -y @shackleai/memory-mcp@latest setup 即可完成
• 全自动 — 启动时自动检测项目，无需手动初始化
• 11 个 MCP 工具 — 初始化、存储、搜索、更新、删除、列出项目、结束会话、TODO 状态、导出、导入、清理
• MCP 资源 — 项目上下文以可读资源的形式提供
• 本地优先 — 所有内容都存储在你的设备上的 ~/.shackleai/
• 零配置 — 无需 API 密钥、云账户，也无需执行安装命令之外的任何设置
• 离线可用 — 使用 MiniLM-L6-v2 在本地生成嵌入（免费，可在 CPU 上运行）
• 可供人工阅读 — 记忆以 Markdown 文件形式存储，你可以阅读和编辑
• 适用于 Git — 使用标准 git 对 AI 的记忆进行版本控制
• 语义搜索 — 根据含义查找相关记忆，而不仅仅是匹配关键词
• 去重 — 自动检测并合并重复记忆
• 自动归档 — 根据保留期限清理旧会话文件
• 多项目支持 — 每个项目都有独立的记忆空间，并自动检测
• LLM 通用 — 随时切换 AI 工具，记忆始终保留

MCP 工具参考

memory_init

初始化或切换项目上下文。服务启动时自动调用——仅在会话期间切换项目时才需手动调用。

Input:  { project_path: "/path/to/project" }
Output: { project_name, tech_stack, memory_count, summary }

根据 package.json、pyproject.toml 或目录名称自动检测项目名称。检测技术栈（Node.js、Python、Rust、Go、Java、Ruby、PHP、.NET、Docker 等）。

memory_store

将重要信息保存到持久记忆中。用于保存决策、约定、错误、架构、偏好、TODO 和上下文。

Input:  {
  content: "We chose PostgreSQL with Prisma ORM for type-safe queries",
  category: "decision",        // decision|convention|bug|architecture|preference|todo|context|session_summary
  importance: "high",           // low|medium|high (optional, default: medium)
  tags: ["database", "orm"]     // optional
}
Output: { id, stored: true, deduplicated: false }

自动检查重复内容。如果存在相似内容（余弦相似度 > 0.9），则更新现有记忆，而不是新建记忆。

memory_search

根据语义含义搜索过往记忆。

Input:  { query: "what database are we using", category: "decision", limit: 5 }
Output: { results: [{ id, content, category, relevance, ... }], count }

使用向量相似度搜索——即使措辞不同，也能找到相关记忆。

memory_update

信息发生变化时，更新现有记忆。

Input:  { id: "mem-uuid", content: "Updated content", reason: "Changed approach" }
Output: { updated: true, previous_content }

memory_delete

移除不再相关的记忆（软删除）。

Input:  { id: "mem-uuid" }
Output: { deleted: true }

memory_list_projects

列出所有存有记忆的项目。

Input:  {}
Output: { projects: [{ name, path, tech_stack, memory_count, last_session }], count }

memory_session_end

保存会话摘要和待处理事项，确保会话之间的连续性。

Input:  { summary: "Built auth system with JWT", open_items: ["Add refresh tokens", "Write tests"] }
Output: { saved: true, date: "2026-03-04" }

MCP 资源

该服务将项目上下文作为 MCP 资源提供：

• memory://project/context — 当前项目的约定、决策、架构、错误和 TODO。支持资源的 MCP 客户端可以在会话开始时自动加载此资源。

存储

所有数据都存储在你的设备本地：

~/.shackleai/
  db/
    memory.db                    SQLite database + vector index
  projects/
    my-project/
      decisions.md               Key decisions with reasoning
      conventions.md             Coding standards and patterns
      bugs.md                    Known issues and fixes
      architecture.md            Architecture choices
      preferences.md             Developer preferences
      todos.md                   Open items
      context.md                 General context
      sessions/
        2026-03-04.md            Today's session summary
        2026-03-03.md            Yesterday's session
  config.yaml                    Optional configuration

**Markdown 是唯一真实来源。**你可以使用文本编辑器阅读、编辑或删除任何记忆文件。SQLite 数据库则是搜索索引。

配置

创建 ~/.shackleai/config.yaml（可选——默认设置开箱即用）：

# Embedding provider: "local" (free, offline) or "openai" (better quality, requires API key)
embedding:
  provider: local

# Custom storage path (default: ~/.shackleai)
# storage_path: /path/to/custom/location

# Maximum memories per project before oldest are archived
max_memories_per_project: 10000

# Session files older than this are auto-archived
max_session_history_days: 90

# Automatically detect and merge duplicate memories
auto_dedup: true

# Cosine similarity threshold for deduplication (0.0 to 1.0)
dedup_threshold: 0.9

云模式

默认情况下，ShackleAI Memory 使用 SQLite 在本地运行——无需账户。云模式通过 Gateway 将你的记忆同步到 ShackleAI 的托管基础设施，提供服务端持久化、跨设备访问，以及由 PostgreSQL + pgvector 驱动的语义搜索。

本地模式与云模式

获取 API 密钥

1. 前往 shackleai.com 并登录（或创建账户）
2. 前往 设置 > API 密钥
3. 点击 创建密钥——你将获得一个格式为 sk_shackle_* 的统一账户密钥
4. 复制密钥。之后将无法再次查看。

配置云模式

云模式通过 Bearer 身份验证连接到 ShackleAI Gateway MCP 端点。将 MCP 客户端配置为指向 Gateway，而不是运行本地服务。

claude mcp add memory-cloud --transport http https://gateway.shackleai.com/mcp \
  --header "Authorization: Bearer sk_shackle_YOUR_KEY_HERE"

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "https://gateway.shackleai.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_shackle_YOUR_KEY_HERE"
      }
    }
  }
}

{
  "mcpServers": {
    "memory": {
      "type": "http",
      "url": "https://gateway.shackleai.com/mcp",
      "headers": {
        "Authorization": "Bearer sk_shackle_YOUR_KEY_HERE"
      }
    }
  }
}

所有 11 个记忆工具（memory_init、memory_store、memory_search、memory_update、memory_delete、memory_list_projects、memory_session_end、memory_status、memory_export、memory_import、memory_cleanup）在云模式下的工作方式完全相同——无需更改代码。

高级：自动初始化选项

服务按以下顺序自动检测项目：

1. CLI 参数：--project-path /path/to/project
2. 环境变量：SHACKLEAI_PROJECT_PATH=/path/to/project
3. 工作目录：使用 process.cwd()（大多数 MCP 客户端会传递此值）

如需明确指定，请在 MCP 配置中设置项目路径：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@shackleai/memory-mcp@latest", "--project-path", "/path/to/project"]
    }
  }
}

或者通过环境变量设置：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@shackleai/memory-mcp@latest"],
      "env": {
        "SHACKLEAI_PROJECT_PATH": "/path/to/project"
      }
    }
  }
}

故障排除

npx setup 失败或提示“command not found: setup”

你的 npm/npx 版本太旧。如果 npm 是 v6.x，就会出现这种情况（较旧的 Node 安装程序会附带此版本）。使用以下命令检查：

npm --version

如果显示 6.x，请按以下步骤修复：

# Option 1: Update npm (recommended — gets you modern npx)
npm install -g npm@latest

# If that fails on Windows with "Refusing to delete" error:
# Delete the stale files first, then retry:
# Remove-Item "$env:APPDATA\npm\npm.cmd", "$env:APPDATA\npm\npx.cmd" -Force
# npm install -g npm@latest

# Option 2: Install globally instead (works with any npm version)
npm install -g @shackleai/memory-mcp
shackleai-memory setup

“Cannot connect to MCP server” / 服务启动失败

确保已安装 Node.js 20+。然后验证服务能否运行：

npx -y @shackleai/memory-mcp --help

如果使用全局安装，请确认二进制文件位于 PATH 中：

shackleai-memory --help

Claude Code：“memory”未显示在 claude mcp list 中

如果你使用了 npx setup，Claude Code 会自动从项目目录读取 .mcp.json——无需通过 claude mcp list 查看。只需在项目目录中启动 claude。

如果你使用了 claude mcp add，请使用以下命令验证：

claude mcp list
# Should show: memory: connected

AI 在会话期间不存储记忆

setup 命令会创建一个 CLAUDE.md 文件，其中包含指示 AI 主动使用记忆的说明。如果你已经有 CLAUDE.md，设置程序会将记忆说明追加到文件中。请检查 CLAUDE.md 是否包含“ShackleAI Memory”部分。

如果 AI 仍未存储记忆，你可以直接向它提出要求：

“将你刚才完成的操作存入记忆”

这可以确认工具正常工作，并促使 AI 在后续交互中更主动地存储记忆。

首次调用工具较慢

首次使用时会下载嵌入模型（约 80MB）。这只需下载一次。之后运行时会使用缓存的模型，速度很快。

会话之间记忆未持久保存

检查 ~/.shackleai/ 目录是否存在且具有写入权限。服务会在首次运行时自动创建该目录。

检测到错误的项目

使用 --project-path 明确设置项目，或使用正确的路径调用 memory_init。

为什么选择 ShackleAI？

如今，每种 AI 编码工具都存在记忆缺失的问题。会话一结束，上下文就消失。切换工具，一切也随之丢失。

ShackleAI 通过提供适用于所有 MCP 兼容 AI 工具的通用记忆层来解决这一问题：

• 适用于所有 AI 工具 — Claude Code、Cursor、Windsurf、VS Code Copilot、OpenAI Codex、Claude Desktop
• 适用于所有大模型 — Claude、GPT、Gemini、Llama、Mistral——任何 MCP 客户端背后的任何大模型
• 你的记忆由你掌控 — 随时切换工具，你的知识始终保留
• 不受供应商锁定 — 开源、本地存储、标准协议

要求

• Node.js 20 或更高版本
• npm 7 或更高版本（用于 npx setup——也可使用任意 npm 版本进行全局安装）
• 任意 MCP 兼容 AI 客户端

参与贡献

欢迎在 github.com/shackleai/memory-mcp 提交问题和 PR。

许可证

MIT——永久免费开源。

让 AI 始终扎根的枷锁。 由 ShackleAI 构建。