持久语义记忆服务

Claude Code  <──HTTP JSON-RPC──>  hms_claude_mem daemon (C++ binary)
                                        │
                                        ├── Storage
                                        │    ├── Local (default) — in-process vector index + local file, write-back persisted
                                        │    └── Redis (opt-in)  — Redis 8 vectorset (VADD/VSIM + HSET/HGET), shared/multi-machine
                                        │
                                        └── Embeddings
                                             ├── Local (default) — bundled nomic-embed-text via llama.cpp, in-process
                                             └── External (opt-in) — Ollama / OpenAI / vLLM / any OpenAI-compatible API

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

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

# Default: embedded store + in-process model — nothing else to run.

# Opt-in: Redis storage
export STORE_PROVIDER=redis
export REDIS_HOST=127.0.0.1

# Opt-in: Ollama embeddings
export EMBED_PROVIDER=ollama
ollama pull nomic-embed-text

# Opt-in: 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-...

mkdir build && cd build
cmake ..                 # fetches llama.cpp + downloads the bundled model (~139 MB)
make -j$(nproc)

cmake .. -DWITH_LOCAL_EMBED=OFF

cd build
./run_tests

{
  "mcpServers": {
    "claude-mem": {
      "type": "http",
      "url": "http://127.0.0.1:8901/mcp",
      "headers": { "Authorization": "Bearer <AUTH_TOKEN>" }
    }
  }
}

{
  "mcpServers": {
    "claude-mem": {
      "type": "http",
      "url": "http://127.0.0.1:8901/mcp",
      "headers": { "Authorization": "Bearer <AUTH_TOKEN>" }
    }
  }
}

{
  "mcpServers": {
    "claude-mem": {
      "type": "http",
      "url": "http://127.0.0.1:8901/mcp",
      "headers": { "Authorization": "Bearer <AUTH_TOKEN>" }
    }
  }
}

{
  "mcpServers": {
    "claude-mem": {
      "type": "http",
      "url": "http://127.0.0.1:8901/mcp",
      "headers": { "Authorization": "Bearer <AUTH_TOKEN>" }
    }
  }
}

{
  "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"
      ]
    }
  }
}

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:<name>' for project-specific facts, 'user:preferences' for how the user likes to work, 'feedback:<topic>' for corrections/validations that should change future behavior, 'reference:<system>' 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.

# 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, transport dispatch
│   ├── 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