AI导哈

本地内存MCP服务器

一个本地MCP（模型上下文协议）服务器，提供语义搜索、存储和更新记忆的功能，适用于AI代理和编码会话中的上下文管理。

  • by basst85
  • TypeScript
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 basst85/local-memory-mcp

使用说明

用于编码/AI代理的本地内存MCP服务器

这个项目是 本地MCP（模型上下文协议）服务器 这暴露了一小部分工具：

  • memory.search -对存储的记忆进行语义搜索
  • memory.save –存储新内存
  • memory.supersede –将旧记忆标记为已取代
  • memory.delete –按id永久删除内存
  • memory.ping –健全性检查/版本输出

你可以用这个项目做什么

  • 在聊天会话中保持持久的编码上下文（决策、偏好、gotchas、API契约）。
  • 从语义上检索相关的过去上下文（不仅仅是关键字匹配）。
  • 使用每个项目的范围内存 WORKSPACE_KEY 同时保留一个共享的本地数据库。
  • 随着时间的推移，通过替换过时的条目或删除不相关的条目来纠正内存。
  • 在本地运行所有内容（不需要外部矢量数据库）。

典型工作流程

  1. 用户在聊天中提问。
  2. 客服电话 memory.search 以获取相关上下文。
  3. 代理使用检索到的内存+当前代码库上下文进行应答。
  4. 新的持久见解通过以下方式存储 memory.save.
  5. 旧内存通过以下方式更新 memory.supersede 或通过以下方式删除 memory.delete.

它使用：

  • 包子 + TypeScript
  • 实验 (@zvec/zvec)作为嵌入式进程内矢量数据库（文档：https://zvec.org/en/docs/)
  • 奥拉玛 /api/embed 随着 嵌入gemma 对于嵌入（文档：https://docs.ollama.com/capabilities/embeddings，型号：https://ollama.com/library/embeddinggemma)

先决条件

  • Bun已安装
  • Ollama在本地安装并运行

拉动嵌入模型：

ollama pull embeddinggemma

安装

bun install

跑

bun run start

这将运行MCP服务器 标准.

测试

bun run test

目前的测试包括：

  • tests/embed.test.ts –验证Ollama嵌入响应解析和错误处理
  • tests/memory-db.test.ts –验证 save, search, supersede，以及 delete Zvec支持的商店

环境变量

  • MEMORY_DB_PATH （默认值 ./data/memory.zvec)
  • OLLAMA_BASE_URL （默认值 http://localhost:11434)
  • OLLAMA_EMBED_MODEL （默认值 embeddinggemma)
  • EMBEDDING_DIM （默认值 768，必须与您的嵌入模型匹配）
  • WORKSPACE_KEY （默认值 default)

VS代码

工作区设置

此回购包括 .vscode/mcp.json 注册此服务器：

  • 命令： bun
  • args： run start

您可以调整该文件中的环境变量。

在所有项目中始终打开

如果您希望此MCP服务器在所有工作区中都可用，请将其添加到您的 用户MCP配置 而不仅仅是 .vscode/mcp.json:

  1. 打开命令选项板： MCP: Open User Configuration
  2. 添加一个从固定目录启动此仓库的服务器条目。

示例（Linux）：

{
  "servers": {
    "local-memory-mcp": {
      "type": "stdio",
      "command": "bun",
      "args": ["--cwd", "/path/to/local-memory-mcp", "run", "start"],
      "env": {
        "MEMORY_DB_PATH": "/path/to/local-memory-mcp/data/memory.zvec",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "embeddinggemma",
        "EMBEDDING_DIM": "768",
        "WORKSPACE_KEY": "${workspaceFolderBasename}"
      }
    }
  }
}

笔记：

  • 使用A 绝对的 MEMORY_DB_PATH 因此，所有项目都使用相同的数据库。
  • WORKSPACE_KEY=${workspaceFolderBasename} 自动为每个项目分离内存。
  • 启用VS代码设置 chat.mcp.autoStart （实验性）在需要时自动启动/重启MCP服务器。

文件：

  • https://code.visualstudio.com/docs/copilot/customization/mcp-servers

克劳德代码

将此服务器作为本地stdio MCP服务器添加到Claude Code中。

此存储库已包含：

  • .mcp.json 用于项目范围的Claude MCP配置
  • CLAUDE.md 内存优先代理行为指南

用户范围（所有项目）

claude mcp add --transport stdio --scope user \
  --env MEMORY_DB_PATH=/absolute/path/to/local-memory-mcp/data/memory.zvec \
  --env OLLAMA_BASE_URL=http://localhost:11434 \
  --env OLLAMA_EMBED_MODEL=embeddinggemma \
  --env EMBEDDING_DIM=768 \
  --env WORKSPACE_KEY=default \
  local-memory-mcp -- bun --cwd /absolute/path/to/local-memory-mcp run start

项目范围（在存储库中共享）

claude mcp add --transport stdio --scope project \
  --env MEMORY_DB_PATH=./data/memory.zvec \
  --env OLLAMA_BASE_URL=http://localhost:11434 \
  --env OLLAMA_EMBED_MODEL=embeddinggemma \
  --env EMBEDDING_DIM=768 \
  --env WORKSPACE_KEY=${PWD##*/} \
  local-memory-mcp -- bun run start

项目 .mcp.json 例子：

{
  "mcpServers": {
    "local-memory-mcp": {
      "type": "stdio",
      "command": "bun",
      "args": ["run", "start"],
      "env": {
        "MEMORY_DB_PATH": "./data/memory.zvec",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_EMBED_MODEL": "embeddinggemma",
        "EMBEDDING_DIM": "768",
        "WORKSPACE_KEY": "${PWD##*/}"
      }
    }
  }
}

笔记：

  • --scope project 写信给 .mcp.json 在项目根中。
  • --scope user 将服务器存储在您的用户Claude配置中。
  • 保留服务器名称前的所有Claude标志，并将 -- 在服务器命令之前。

有用的命令：

claude mcp list
claude mcp get local-memory-mcp
claude mcp remove local-memory-mcp

文件：

  • https://code.claude.com/docs/en/mcp

工具使用（示例）

搜索

{
  "tool": "memory.search",
  "arguments": {
    "query": "What is our policy for multi-session memory?",
    "topK": 8,
    "workspaceKey": "my-repo"
  }
}

保存

{
  "tool": "memory.save",
  "arguments": {
    "workspaceKey": "my-repo",
    "type": "decision",
    "summary": "We use zvec with Ollama embeddinggemma for long-term memory.",
    "text": "Decision: The Copilot/agent memory sidecar stores vectors in zvec and generates embeddings via Ollama /api/embed using embeddinggemma.",
    "tags": ["memory", "zvec", "ollama", "embeddinggemma"],
    "importance": 0.8
  }
}

删除

{
  "tool": "memory.delete",
  "arguments": {
    "workspaceKey": "my-repo",
    "id": 42
  }
}

实现注意事项

  • DB使用一个Zvec集合：
    • 密集矢量场 embedding
    • 元数据的标量字段(workspaceKey, type, summary等等）
  • KNN查询通过Zvec执行 querySync 使用元数据过滤器。

测试

运行所有测试：

bun run test

当前测试覆盖率：

  • tests/embed.test.ts
    • 解析成功的Ollama /api/embed 回应 Float32Array
    • 验证Ollama返回非2xx响应时的错误处理
  • tests/memory-db.test.ts
    • 验证 save + search 使用工作区/类型过滤的行为
    • 验证 supersede 行为（被取代的项目被排除在搜索之外）
    • 验证 delete 行为和返回的有效载荷语义

相关 MCP