Hms Claude Mem

嗯，克劳德·梅

通过Redis 8向量集为Claude Code提供持久语义记忆。一个C++MCP服务器，使Claude能够跨会话存储、搜索和检索上下文——按需操作，而不会使上下文窗口膨胀。

问题

LLM的上下文窗口有限。随着对话的增加，早期的上下文会被压缩并丢失。基于文件的内存（如 MEMORY.md)提前加载所有内容，将上下文浪费在现在不相关的事情上。

解决方案

Claude自己管理的Redis支持的语义内存系统：

1. 商店 发现它时重要的是什么（构建命令、调试解决方案、用户首选项）
2. 搜索 当它以后需要上下文时（“我如何部署到Pi？”即使那些确切的单词从未存储过，也能找到正确的内存）
3. 检索 在小批量手术中，只关注相关内容

Claude Code    hms_claude_mem (C++ binary)
                                        │
                                        ├── Redis 8 (vectorset module)
                                        │    ├── VADD/VSIM  → semantic vector search
                                        │    └── HSET/HGET  → key-value storage
                                        │
                                        └── Embedding Provider (Ollama, OpenAI, vLLM, etc.)
                                             └── nomic-embed-text / text-embedding-3-small / etc.

运作原理

每个内存都存储在 两地:

• 矢量集 (claude:mem:vectors)--密钥通过nomic嵌入文本嵌入为768维矢量。启用语义相似性搜索 VSIM.
• 哈希 (claude:mem:data:{key})--实际值、类别和时间戳。通过以下方式实现精确检索 HGETALL.

什么得到 嵌入 是 "{category}: {key}"，而不是价值。键应该是描述性的句子，这样嵌入就可以捕捉到语义含义：

key:      "hms-cpap deploy process to raspberry pi"
category: "project:hms-cpap"
value:    "Use ./deploy_to_pi.sh for ARM build + deploy ..."

搜索“我如何将代码推送到Pi”将通过余弦相似性找到这个内存，即使单词不匹配。

MCP工具

先决条件

• Redis 8+ 带vectorset模块（Redis 8.0内置）
• 任何嵌入提供者：Ollama、OpenAI、vLLM、LiteLLM、LocalAI或任何与OpenAI兼容的软件
• C++17 编译器
• libhiredis开发, libcurl4-openssl-dev, nlohmann-json3-dev

# Install dependencies (Debian/Ubuntu)
sudo apt install -y libhiredis-dev libcurl4-openssl-dev nlohmann-json3-dev

# Option A: Ollama (local, free)
ollama pull nomic-embed-text

# Option B: OpenAI-compatible (any provider)
export EMBED_PROVIDER=openai
export EMBED_HOST=https://api.openai.com
export EMBED_MODEL=text-embedding-3-small
export EMBED_API_KEY=sk-...

下载

预构建的二进制文件附加到每个 :

每个档案都捆绑了二进制文件， README.md, LICENSE，以及 VERSIONWindows zip还将运行时DLL（hiredis、libcurl、zlib、openssl）放在 .exe.如果你的发行版是Docker，那么你更喜欢Docker镜像或从源代码构建 hiredis / libcurl ABI与跑步者不同。

构建

mkdir build && cd build
cmake ..
make -j$(nproc)

测试

14个集成测试（需要Redis+嵌入提供程序运行）：

cd build
./run_tests

配置

具有合理默认值的环境变量：

使用克劳德代码注册

项目范围（推荐起点）

添加 .mcp.json 在您的项目根目录中。记忆与这个项目是孤立的：

奥利玛（当地，免费）：

{
  "mcpServers": {
    "claude-mem": {
      "command": "/path/to/build/hms_claude_mem",
      "args": [],
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "EMBED_PROVIDER": "ollama",
        "EMBED_HOST": "http://localhost:11434",
        "EMBED_MODEL": "nomic-embed-text",
        "EMBED_API_KEY": "",
        "NAMESPACE": "my-project",
        "DECAY_RATE": "0.01"
      }
    }
  }
}

OpenAI/OpenAI兼容（vLLM、LiteLLM、LocalAI等）：

{
  "mcpServers": {
    "claude-mem": {
      "command": "/path/to/build/hms_claude_mem",
      "args": [],
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "EMBED_PROVIDER": "openai",
        "EMBED_HOST": "https://api.openai.com",
        "EMBED_MODEL": "text-embedding-3-small",
        "EMBED_API_KEY": "sk-...",
        "NAMESPACE": "my-project",
        "DECAY_RATE": "0.01"
      }
    }
  }
}

全球（所有会议、所有项目）

添加 ~/.claude/settings.json 所以克劳德在每个项目中都记得：

{
  "mcpServers": {
    "claude-mem": {
      "command": "/path/to/build/hms_claude_mem",
      "args": [],
      "env": {
        "REDIS_HOST": "127.0.0.1",
        "REDIS_PORT": "6379",
        "EMBED_PROVIDER": "ollama",
        "EMBED_HOST": "http://localhost:11434",
        "EMBED_MODEL": "nomic-embed-text",
        "NAMESPACE": "global",
        "DECAY_RATE": "0.01"
      }
    }
  }
}

Docker作为MCP服务器

如果你构建或拉取了Docker镜像，请指向Claude Code：

{
  "mcpServers": {
    "claude-mem": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "REDIS_HOST=host.docker.internal",
        "-e", "EMBED_HOST=http://host.docker.internal:11434",
        "-e", "NAMESPACE=my-project",
        "ghcr.io/hms-homelab/hms-claude-mem:latest"
      ]
    }
  }
}

备注

• 命名空间隔离： 不同 NAMESPACE 值创建完全独立的内存池。一个项目 .mcp.json 覆盖 ~/.claude/settings.json 当两者都存在时。
• 最小配置： 仅 NAMESPACE 和 EMBED_HOST 通常是需要的——其他所有东西都有合理的默认值。
• 需要重新启动： 更改MCP配置后，必须重新启动Claude Code。
• 远程Redis： 集 REDIS_HOST 连接到Redis服务器IP，以便跨机器共享内存。

教克劳德使用这个MCP

第一次将claude mem连接到新项目时，将下面的块粘贴到您的claude Code会话中。Claude会将这些使用约定存储为内存，这样以后的每个会话都会通过以下方式检索它们 mem_search 而不是你必须重新解释。

You now have the `claude-mem` MCP available (tools: `mem_store`, `mem_search`, `mem_get`, `mem_delete`, `mem_list`). Please store the following usage conventions as memories so future sessions can retrieve them.

Store each of these with `mem_store`:

1. key: "how and when to use mem_store"
   category: "meta:claude-mem"
   value: "Store a memory when you learn: a build/deploy command, a fix for a non-obvious bug, a user preference, a project decision with a durable why, or a reference to an external system. Do NOT store: ephemeral task state, info already in the code/git history, or duplicates — run mem_search first."

2. key: "how and when to use mem_search"
   category: "meta:claude-mem"
   value: "Search semantically at the start of a task and before asking the user questions the codebase can't answer. Use descriptive natural-language queries (e.g. 'how do I deploy the CPAP service'). Top-k=5 is a reasonable default."

3. key: "memory category conventions"
   category: "meta:claude-mem"
   value: "Use these category prefixes: 'project:' for project-specific facts, 'user:preferences' for how the user likes to work, 'feedback:' for corrections/validations that should change future behavior, 'reference:' for pointers to external systems, 'meta:claude-mem' for self-documentation of this MCP."

4. key: "memory key naming convention"
   category: "meta:claude-mem"
   value: "Keys are what gets embedded and searched. Write full descriptive sentences ('deploy process for hms-cpap on raspberry pi'), not short slugs ('deploy-cpap'). The value holds the actual content."

5. key: "avoid duplicate memories"
   category: "meta:claude-mem"
   value: "Before mem_store, run mem_search with the same phrasing. If a close match exists, mem_delete the old one or skip the new store. Drifting duplicates poison search results."

After storing, confirm with `mem_list category=meta:claude-mem` that all five are present.

从那时起，在任何会话开始时，克劳德都可以运行 mem_search query="how to use claude-mem" 这些惯例将会浮出水面。

码头工人

# Build
docker build -t hms-claude-mem .

# Run (needs access to Redis and Ollama)
docker run --rm \
  -e REDIS_HOST=host.docker.internal \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  hms-claude-mem

或者使用已发布的图像：

docker pull ghcr.io/hms-homelab/hms-claude-mem:latest

演出

项目结构

hms-claude-mem/
├── CMakeLists.txt          # C++17, hiredis + curl + nlohmann-json
├── Dockerfile              # Multi-stage (debian:trixie-slim)
├── VERSION                 # Semantic version
├── CHANGELOG.md
├── src/
│   ├── main.cpp            # Env config, wiring, stdio loop
│   ├── mcp_server.cpp/h    # JSON-RPC 2.0 MCP protocol handler
│   ├── redis_client.cpp/h  # hiredis wrapper (VADD, VSIM, HSET, SCAN)
│   ├── embedding_client.cpp/h  # Multi-provider embedding client (Ollama, OpenAI)
│   └── tools.cpp/h         # Tool implementations (store, search, get, delete, list)
├── tests/unit/
│   └── test_mcp_server.cpp # 14 integration tests
└── .github/workflows/
    └── docker-build.yml    # CI: build, test, push to GHCR

支持

许可证

麻省理工学院