使用说明

克劳德艾记忆

MCP（模型上下文协议）服务器，提供持久的项目上下文存储、管理和语义搜索克劳德代码.技术支持： OpenViking 上下文数据库。

中文文档

问题

Claude Code会话是无状态的。当您关闭终端时，讨论的所有内容都会丢失：

为什么做出某种技术决策
上次会议讨论了什么，还有什么悬而未决
来自客户沟通的关键信息
通过多次会议积累的项目理解

项目文件捕获代码更改，但不捕获其背后的推理、讨论和上下文。

解决方案

克劳德艾记忆给克劳德代码一个 持久存储层 对于每个项目：

自动会话摘要 --关键决策、更改和TODO在每个会话结束时保存
手动内存捕获 --使用 /remember 明确存储重要信息
语义搜索 --使用自然语言查询查找相关历史上下文
智能上下文加载 --在会话启动时加载项目概述，按需检索详细上下文
多项目隔离 --每个项目都有自己独立的上下文空间

建筑

┌──────────────────────────────────────────────────────┐
│                   Docker Compose                      │
│                                                       │
│  ┌──────────────┐  ┌────────────┐  ┌──────────────┐  │
│  │ openviking   │  │ embedding  │  │ ollama       │  │
│  │ (Rust)       │  │ (FastAPI + │  │ Qwen3-0.6B   │  │
│  │ :1933        │←─│ MiniLM-L6) │  │ :11434       │  │
│  │              │  │ :8100      │  │ (fallback)   │  │
│  └──────┬───────┘  └────────────┘  └──────────────┘  │
│         │  /var/lib/openviking/data (persistent)      │
└─────────┼────────────────────────────────────────────┘
          ↑ HTTP
┌─────────┴────────────────┐
│  claude-ai-memory MCP    │
│  (Python, stdio)         │
└─────────┬────────────────┘
          ↑ MCP stdio
┌─────────┴────────┐
│  Claude Code CLI  │
│  + CLAUDE.md      │
└──────────────────┘

组件

组件	技术	目的
MCP服务器	Python+ `mcp` SDK	通过stdio传输向Claude Code公开4个工具
上下文数据库	OpenViking （Docker）	具有L0/L1/L2分层检索的文件系统范式上下文数据库
嵌入	全迷你LM-L6-v2 （本地）	语义向量编码，384维，零API成本
VLM（初级）	MiniMax M2.5	通过符合人体工程学的API生成摘要
VLM（回退）	Qwen3-0.6B-FP8 via Ollama	API不可用时的本地CPU推断

成本

项目	成本
OpenViking	免费（Apache 2.0）
嵌入（本地）	免费
Ollama（当地）	免费
MiniMax M2.5 API	约1美元/月（30美元/M输入+120美元/M输出）
总计	约1美元/月

MCP工具

只有4个粗粒度工具被公开以最小化API调用：

`context_load`

在会话启动时调用一次。在单个响应中返回项目概述、最近会话摘要、待处理项目和活动决策。

{
  "project_path": "/home/user/my-project"
}

`context_search`

跨项目内存的语义搜索。直接返回L1级内容，无需后续调用。

{
  "project_path": "/home/user/my-project",
  "query": "why did we choose Stripe for payments",
  "scope": "decisions",
  "limit": 5
}

`context_save`

在一次调用中批量保存多个内存条目。

{
  "project_path": "/home/user/my-project",
  "entries": [
    {
      "type": "session_summary",
      "title": "Implemented user registration",
      "content": "Completed email registration, verification, password strength check. Used Resend for email. TODO: OAuth login."
    },
    {
      "type": "decision",
      "title": "Email service selection",
      "content": "Chose Resend over SendGrid: simpler API, sufficient free tier."
    }
  ]
}

`context_manage`

低频管理操作：列表、删除、更新和项目初始化。

典型的会话呼叫模式

事件	通话
会话开始	1x `context_load`
工作期间（30分钟会议）	0-3x `context_search`
会话结束	1x `context_save` （批次）
手册 `/remember`	1x `context_save`
典型总计	2-5个电话

多项目隔离

每个项目都映射到OpenViking文件系统范式中的一个独立URI命名空间：

viking://
├── projects/
│   ├── <project-hash-1>/        # Project A
│   │   ├── sessions/            # Session summaries
│   │   ├── decisions/           # Architecture decisions
│   │   ├── changes/             # Change records
│   │   └── knowledge/           # Dev resources, notes
│   ├── <project-hash-2>/        # Project B
│   └── ...
└── global/                      # Cross-project knowledge

项目ID：项目根绝对路径的SHA256哈希的前12个字符。

部署

先决条件

Docker和Docker Compose v2
Python 3.10+
MiniMax API密钥(在这里买一个)

快速开始

# 1. Clone the repository
git clone https://github.com/alanshaka-real/claude-ai-memory.git
cd claude-ai-memory

# 2. Configure
cp config/ov.conf.example config/ov.conf
# Edit config/ov.conf with your MiniMax API key

# 3. Start services
docker compose up -d

# 4. Pull Ollama fallback model
docker compose exec ollama ollama pull qwen3:0.6b

# 5. Add MCP server to Claude Code
# Add to ~/.claude/settings.json:
# {
#   "mcpServers": {
#     "claude-ai-memory": {
#       "command": "python",
#       "args": ["/path/to/claude-ai-memory/mcp-server/server.py"]
#     }
#   }
# }

升级（零数据丢失）

docker compose pull openviking   # Pull latest image
docker compose up -d openviking  # Recreate container, data untouched
docker compose ps                # Verify healthy status

数据存储在主机上 /var/lib/openviking/data 通过绑定挂载——容器升级永远不会影响您的数据。

Docker编写服务

服务	图像	端口	用途
开幕式。 `ghcr.io/volcengine/openviking:main`	1933	上下文数据库
嵌入	自定义（FastAPI+句子转换器）	8100	本地嵌入服务
奥拉马	`ollama/ollama:latest`	11434	后备法学硕士

错误处理

所有后端故障都得到了妥善处理-- Claude Code始终正常工作，有或没有内存：

失败	行为
OpenViking不可用	`context_load` 回报 `{"available": false}`克劳德的作品没有历史
嵌入不可用	写入成功，搜索降级为目录浏览
MiniMax API不可用	自动回滚到本地Ollama Qwen3-0.6B
Ollama也不可用	原始文本已保存，摘要已排队等待重试
项目未注册	退货 `{"registered": false}`，提示初始化

如何使用Claude代码

当项目初始化时，claude ai内存将指令注入到项目的 CLAUDE.md:

会话开始：克劳德打来电话 context_load 了解项目状态
工作期间：克劳德打来电话 context_search 当需要历史背景时
会话结束：克劳德打来电话 context_save 保存会话知识
手动保存：用户触发器 /remember 显式存储信息

这创建了一个自然的记忆循环，Claude在会话中逐步建立项目理解。

项目结构

claude-ai-memory/
├── docker-compose.yml
├── config/
│   └── ov.conf
├── embedding-service/
│   ├── Dockerfile
│   ├── main.py
│   └── requirements.txt
├── mcp-server/
│   ├── __init__.py
│   ├── server.py
│   ├── viking_client.py
│   ├── project_manager.py
│   └── models.py
├── tests/
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── scripts/
│   ├── setup.sh
│   └── inject-claude-md.sh
├── docs/
│   └── plans/
│       └── 2026-03-01-claude-ai-memory-design.md
├── pyproject.toml
└── README.md

许可证

Apache许可证2.0

致谢

OpenViking --AI代理的上下文数据库
最小最大 -经济高效的LLM API
句子变换器 --本地嵌入模型
奥拉玛 --本地LLM推理

使用说明

克劳德艾记忆

问题

解决方案

建筑

组件

成本

MCP工具

context_load

context_search

context_save

context_manage

典型的会话呼叫模式

多项目隔离

部署

先决条件

快速开始

升级（零数据丢失）

Docker编写服务

错误处理

如何使用Claude代码

项目结构

许可证

致谢

相关 MCP

AI持久记忆服务器

Zotero文献库搜索与阅读MCP服务

Qdrant向量搜索MCP服务器

GitLab项目管理服务器

Primavera P6 XER文件解析服务器

本地LLM模型控制协议

`context_load`

`context_search`

`context_save`

`context_manage`