Claude本地内存服务器

通过MCP为Claude Code提供持久共享内存

一个轻量级的内存服务器，为Claude Code提供跨机器的持久、可搜索内存。使用DuckDB构建，通过句子转换器提供语义搜索，实现高效存储。

┌─────────────────┐     ┌─────────────────┐
│ Claude Code     │     │ Claude Code     │
│ (laptop)        │     │ (desktop)       │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
          ┌─────────────────────┐
          │  claude-local-      │
          │  memory-server      │
          │  (your LXC/server)  │
          └─────────────────────┘

特性

持久存储 –记忆在重启后仍然存在，存储在DuckDB中
语义搜索 –通过意义而不仅仅是关键字来寻找记忆
混合搜索 –将关键字匹配与向量相似性（RRF）相结合
项目范围界定 –从git自动检测项目，为每个项目隔离内存
跨机器共享 –运行中央服务器，从任何地方连接
快速查询 –DuckDB支持自动索引
客户跟踪 –知道是哪台机器创建了每个内存
基于标签的组织 –按项目、技术栈或自定义标签筛选
生产就绪 –速率限制、请求日志记录、CORS支持
简单设置 –一个脚本在Debian/Ubuntu上安装所有内容

快速开始

选项1：本地模式（单机）

# Install
pip install claude-local-memory-server

# Configure Claude Code
claude mcp add-json "memory" '{
  "command": "python",
  "args": ["-m", "claude_memory.cli", "serve"],
  "env": {"MEMORY_CLIENT_ID": "my-laptop"}
}'

选项2：使用Docker的服务器模式（推荐）

git clone https://github.com/thomasbeste/claude-local-memory-server.git
cd claude-local-memory-server
./scripts/install-docker.sh

脚本构建图像，启动容器，并打印API密钥。

或者直接使用docker compose：

# Generate an API key
export MEMORY_API_KEY=$(openssl rand -base64 32 | tr -d '/+=' | head -c 32)

# Start the server
docker compose up -d

# Check status
docker compose logs -f

HTTP MCP模式（直接连接）：

服务器在以下位置公开MCP over HTTP端点 /mcp.配置Claude Code直接连接：

claude mcp add memory --transport http --url http://your-server:8420/mcp

这消除了对本地客户端进程的需要——Claude Code通过HTTP直接连接到服务器。

选项3：带Systemd的服务器模式（LXC/VM）

在您的服务器上（Debian/Ubuntu LXC、VM等）：

git clone https://github.com/thomasbeste/claude-local-memory-server.git
cd claude-local-memory-server
sudo ./scripts/install-systemd.sh

该脚本安装Python，创建一个systemd服务，并打印您的API密钥。

在每台客户端机器上：

pip install claude-local-memory-server

claude mcp add-json "memory" '{
  "command": "python",
  "args": ["-m", "claude_memory.cli", "client"],
  "env": {
    "MEMORY_SERVER": "http://your-server:8420",
    "MEMORY_API_KEY": "your-key-here",
    "MEMORY_CLIENT_ID": "laptop"
  }
}'

用法

配置后，Claude可以存储和检索内存：

存储内存：

“记住，我们决定在GPI项目中使用FastAPI”

回忆往事：

“我们对GPI做出了哪些决定？”

按客户搜索：

“上周我在笔记本电脑上做了什么？”

CLI命令

# Show current project (auto-detected from git)
claude-memory project

# Add a memory (auto-associates with current project)
claude-memory add "Project X uses Python 3.12" --type fact --tags project:x

# Add memory to a specific project
claude-memory -p my-project add "Memory content"

# Add memory without project association
claude-memory add "Global memory" --no-project

# Search memories (default: hybrid mode, scoped to current project)
claude-memory search --query "Python"

# Search with specific mode
claude-memory search -q "software development" -m semantic  # meaning-based
claude-memory search -q "Python" -m keyword                  # exact matching
claude-memory search -q "API framework" -m hybrid            # combined (default)

# Search across ALL projects
claude-memory search -q "Python" --global

# Get context summary for current project (prioritized decisions, preferences, facts)
claude-memory context

# Get context as JSON
claude-memory context --json

# Filter by type and tags
claude-memory search --type decision --tags project:x

# View statistics (for current project)
claude-memory stats

# View statistics across all projects
claude-memory stats --global

# Backfill embeddings for existing memories
claude-memory backfill-embeddings

# Delete a memory
claude-memory delete

搜索模式

模式	描述
`keyword`	传统子字符串匹配（ILIKE）
`semantic`	使用句子变换器的向量相似性
`hybrid`	将两者与往复式排名融合相结合（默认）

存储器类型

类型	用途
`fact`	具体事实（名称、版本、配置）
`decision`	对话中做出的决定
`preference`	用户偏好（工具、风格、语言）
`observation`	一般性意见
`entity`	人员、项目、组织
`relation`	实体之间的关系

配置

环境变量

客户端变量：

变量	描述
`MEMORY_SERVER`	HTTP服务器URL（客户端模式）
`MEMORY_API_KEY`	用于身份验证的API密钥
`MEMORY_CLIENT_ID`	此客户端的标识符（例如，“笔记本电脑”、“工作电脑”）
`MEMORY_PROJECT`	覆盖自动检测到的项目ID

服务器变量：

变量	描述
`MEMORY_API_KEY`	用于身份验证的API密钥（生产需要）
`CORS_ORIGINS`	逗号分隔的允许来源（例如。， `https://ui.example.com`)

服务器选项

claude-memory server --help

Options:
  --host TEXT      Host to bind to [default: 0.0.0.0]
  --port INTEGER   Port to bind to [default: 8420]
  --data-dir TEXT  Data directory [default: /var/lib/claude-local-memory-server]

安装脚本选项

Docker（安装Docker.sh）：

./scripts/install-docker.sh --help

Options:
  --port PORT         HTTP port [default: 8420]
  --api-key KEY       Set API key (generated if omitted)
  --no-start          Build only, don't start the container

Systemd（安装Systemd.sh）：

./scripts/install-systemd.sh --help

Options:
  --port PORT         HTTP port [default: 8420]
  --api-key KEY       Set API key (generated if omitted)
  --data-dir DIR      Data directory [default: /var/lib/claude-local-memory-server]
  --no-service        Don't install systemd service

在反向代理后面部署

该服务器被设计为在nginx或其他反向代理后面通过互联网暴露。它包括：

API密钥验证 –所有路线（除 /health)要求 X-API-Key 头球
速率限制 –写入30/分钟，读取60/分钟（根据API密钥）
请求日志记录 –记录的每个请求都带有计时、IP和API密钥提示
CORS支持 –可通过以下方式配置 CORS_ORIGINS 环境变量

Nginx配置

# Rate limiting zone (optional, server has built-in limits)
limit_req_zone $binary_remote_addr zone=memory_api:10m rate=10r/s;

server {
    listen 443 ssl http2;
    server_name memory.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/memory.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/memory.yourdomain.com/privkey.pem;

    # Security headers
    add_header X-Content-Type-Options nosniff;
    add_header X-Frame-Options DENY;

    location / {
        proxy_pass http://127.0.0.1:8420;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Optional: nginx-level rate limiting
        limit_req zone=memory_api burst=20 nodelay;

        # Request size limit (prevent memory bombs)
        client_max_body_size 1m;
    }

    # Health check (no auth required)
    location /health {
        proxy_pass http://127.0.0.1:8420/health;
    }
}

# Redirect HTTP to HTTPS
server {
    listen 80;
    server_name memory.yourdomain.com;
    return 301 https://$server_name$request_uri;
}

速率限制

每个API密钥的内置速率限制（如果没有密钥，则为IP）：

操作	限制
创建内存	30/分钟
更新内存	30/分钟
删除内存	30/分钟
搜索	60次/分钟
获取内存	60/分钟
统计数据/上下文	60/分钟

当速率受到限制时，服务器返回 429 Too Many Requests.

请求日志记录

所有请求都以以下格式记录：

2025-12-18 12:34:56 | claude_memory.api | INFO | POST /memories | 201 | 45.2ms | ip=192.168.1.5 key=abc12345...

日志包括：

时间戳
HTTP方法和路径
应答状态
请求持续时间
客户端IP地址
API密钥的前8个字符（用于调试而不暴露完整密钥）

建筑

src/claude_memory/
├── storage.py   # DuckDB/Parquet storage layer
├── server.py    # MCP stdio server (local mode)
├── api.py       # FastAPI HTTP server + MCP-over-HTTP endpoint
├── client.py    # MCP stdio client → HTTP proxy
└── cli.py       # Command-line interface

本地模式： 克劳德代码↔ 标准输入输出↔ server.py ↔ DuckDB

客户端模式： 克劳德代码↔ 标准输入输出↔ client.py ↔ HTTP休息↔ api.py ↔ DuckDB

HTTP MCP模式： 克劳德代码↔ HTTP MCP↔ api.py /mcp 端点↔ DuckDB

数据存储

记忆存储在持久的DuckDB数据库中：

服务器： /var/lib/claude-local-memory-server/memories.duckdb
当地： ~/.claude-memory/memories.duckdb

该数据库包括用于语义搜索的嵌入（来自 all-MiniLM-L6-v2).

使用DuckDB进行检查：

duckdb ~/.claude-memory/memories.duckdb -c "SELECT id, content, memory_type FROM memories LIMIT 10"

导出到拼花地板（用于备份）：

# From Python
from claude_memory.storage import MemoryStorage
storage = MemoryStorage()
storage.export_parquet("/path/to/backup.parquet")

备份脚本：

./scripts/backup.sh  # Creates timestamped backup in /var/backups/claude-local-memory-server/

使用钩子实现自动上下文

克劳德代码支持钩子 --响应事件运行的shell命令。您可以使用钩子在每次对话开始时自动注入内存上下文。

自动注入项目上下文

创建 .claude/settings.json 在您的项目中（或 ~/.claude/settings.json 全球）：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claude-memory context --json 2>/dev/null | jq -r '\"[Memory Context for \" + .project_id + \"]\\n\" + (.memories | map(\"- [\" + .memory_type + \"] \" + .content) | join(\"\\n\"))' 2>/dev/null || echo ''",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

这将在每次提示提交时运行，并在您的对话中添加相关记忆。空的 matcher 意味着它在所有提示下运行。

更简单的钩子（不需要jq）

如果你没有 jq 安装：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "claude-memory context 2>/dev/null || echo ''",
            "timeout": 5000
          }
        ]
      }
    ]
  }
}

钩子提示

超时：设置合理的超时时间（5000ms），这样慢速网络就不会阻止您的对话
错误处理：The || echo '' 确保Claude Code不会因错误而阻塞
Stderr重定向: 2>/dev/null 抑制连接警告
项目范围界定: claude-memory context 自动检测您的git项目，并仅返回相关内存

其他钩子想法

事件	用例
`PreToolUse`	当Claude要存储内存时记录
`PostToolUse`	内存操作后触发通知
`Stop`	总结会议中记住的内容

看 Claude Code挂钩文档以获取完整的事件参考。

发展

# Clone and install in development mode
git clone https://github.com/thomasbeste/claude-local-memory-server.git
cd claude-local-memory-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,server,embeddings]"

# Run tests
pytest

# Run linter
ruff check src/

可选依赖关系

额外	描述
`server`	FastAPI+uvicon用于HTTP服务器模式
`embeddings`	语义搜索的句子变换器
`dev`	pytest+ruff用于开发
`all`	上面的一切

路线图

\[x\] 嵌入语义搜索
\[x\] 混合搜索（关键字+语义）
\[x\] DuckDB持久模式
\[x\] 速率限制和请求日志记录
\[x\] 生产已准备好进行反向代理部署
\[x\] HTTP端点上的MCP（直接克劳德代码连接）
\[\]用于浏览回忆的Web UI
\[\]内存过期/TTL
\[\]知识图关系
\[\]自动摘要
\[\]普罗米修斯指标端点

看 TODO.md 完整的路线图。

许可证

MIT许可证-请参阅许可证

贡献

欢迎投稿！看贡献.md 作为指导方针。

Claude Local Memory Server

快速接入

详细介绍