玉记忆
人工智能代理的持久知识库和期刊。两个MCP服务器由一个共享的多语言嵌入式sidecar支持，部署为Docker容器。
知识库 使用语义搜索存储事实、决策、程序和故障排除说明。客服电话 store 保存知识和 recall 检索它。条目被键入、标记和跨语言搜索。
期刊 是一种自由形式、仅附加的认知工具。代理人写想法、反思和会议笔记。价值在于写作过程（结构化思维），而不仅仅是检索。没有类别或部分——语义存在于内容本身。
两者都使用向量嵌入（768dim，gte多语言库）通过sqlite-vec进行语义搜索。两者都可以通过带有承载令牌身份验证的MCP Streamable HTTP传输进行远程访问。API密钥是通过web管理UI创建的，不需要env vars。
建筑
┌─────────────────────────────────────────────────────┐
│ Docker network (internal bridge) │
│ │
│ jade-embeddings (Python, port 3102, internal only) │
│ Alibaba-NLP/gte-multilingual-base │
│ 768 dims, 100+ languages, ~1.2GB RAM │
│ │
│ jade-knowledge (Bun, port 3100) │
│ MCP Streamable HTTP at /mcp │
│ Bearer token auth │
│ │
│ jade-journal (Bun, port 3101) │
│ MCP Streamable HTTP at /mcp │
│ Bearer token auth (separate key) │
└─────────────────────────────────────────────────────┘嵌入sidecar只是内部的，不会暴露在Docker网络之外。两个MCP服务器都调用它来在存储/写入和搜索/调用时生成嵌入。
工具
知识库（玉石知识）
| 工具 | 说明 | 参数 |
|---|---|---|
recall | 搜索知识库 | query （字符串）， type? （枚举）， limit? （int，默认值10） |
store | 通过自动嵌入添加知识 | content （字符串）， type? （枚举，默认“常规”）， tags? （字符串\[\]） |
forget | 删除知识条目 | id （int） |
知识类型： fact, preference, decision, procedure, troubleshooting, general
期刊（玉刊）
| 工具 | 说明 | 参数 |
|---|---|---|
write | 记录日记账分录 | content （字符串） |
search | 语义搜索日志 | query （字符串）， limit? （int，默认值10） |
recent | 列出最近的条目 | limit? （int，默认值10） |
日记只作追加。不删除，不编辑。
上下文足迹
两种MCP加起来大约 约480个代币 代理上下文窗口的总计：
- 玉知识：约300个令牌（3个工具）
- 玉日志：约180个令牌（3个工具）
相比之下，剧作家MCP增加了约13700个代币。
安装
先决条件
- Docker和Docker Compose
- 主机上的端口3100和3101可用
1.克隆和配置
git clone jade-memory
cd jade-memory
cp .env.example .env
# Edit .env if you need to change ports or DB paths (no API keys needed)2.构建并启动
docker compose up -d --build首先构建下载嵌入模型（~1.2GB）并将其烘焙到映像中。这需要几分钟的时间。后续构建使用缓存层。
嵌入的sidecar有一个120秒的启动周期的健康检查，以允许模型加载。知识和日志容器在开始之前等待它健康。
3.创建管理员帐户
访问 http://:3100 （知识）或 http://:3101 （日志）在浏览器中。首次访问时，系统会提示您创建管理员帐户。
4.创建API密钥
登录web UI，转到 /admin，并创建API密钥。MCP客户端（Claude Code、OpenCode等）使用这些代码进行身份验证。立即复制密钥——它只显示一次。
5.验证
# Health checks (no auth required)
curl http://localhost:3100/health
curl http://localhost:3101/health
# Test MCP auth with your API key
curl -X POST http://localhost:3100/mcp \
-H "Authorization: Bearer " \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'6.（可选）反向代理
如果您想通过traefik或其他反向代理通过HTTPS公开MCP：
cp docker-compose.override.yml.example docker-compose.override.yml
# Edit docker-compose.override.yml with your domain names and TLS config
docker compose up -d连接到代理
API密钥是通过以下位置的web管理员UI创建的 /admin 登录后。更换 `` 下面是您在那里创建的密钥。
克劳德代码
选项A:CLI（推荐）
claude mcp add --transport http jade-knowledge http://:3100/mcp \
--header "Authorization: Bearer "
claude mcp add --transport http jade-journal http://:3101/mcp \
--header "Authorization: Bearer "使用 --scope user 使其可用于所有项目，或 --scope local （默认）仅适用于当前项目。
选项B:JSON配置
增添 ~/.claude.json （或项目级别 .claude/settings.json)under mcpServers:
{
"mcpServers": {
"jade-knowledge": {
"type": "http",
"url": "http://:3100/mcp",
"headers": {
"Authorization": "Bearer "
}
},
"jade-journal": {
"type": "http",
"url": "http://:3101/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}开源代码
增添 opencode.json 在项目根目录中：
{
"mcp": {
"jade-knowledge": {
"type": "remote",
"url": "http://:3100/mcp",
"headers": {
"Authorization": "Bearer "
}
},
"jade-journal": {
"type": "remote",
"url": "http://:3101/mcp",
"headers": {
"Authorization": "Bearer "
}
}
}
}你可以使用 {env:KNOWLEDGE_API_KEY} 而不是引用环境变量的文字键。
其他MCP客户端
任何支持MCP Streamable HTTP传输的客户端都可以连接。服务器接受：
POST /mcp--MCP JSON-RPC消息（需要Accept: application/json, text/event-stream)GET /mcp--服务器发起的消息的SSE流DELETE /mcp--会话清理GET /health--健康检查（无需身份验证）
提示代理人
为了获得最佳结果，指示代理主动使用知识库。在系统提示符或CLAUDE.md中添加以下内容：
You have access to a persistent knowledge base (jade-knowledge) and journal (jade-journal).
**Knowledge base**: Use `recall` when starting a task to check for relevant prior knowledge.
Use `store` when you learn something reusable — facts, decisions, troubleshooting solutions,
procedures. Tag entries with project names for cross-project retrieval.
**Journal**: Use `write` when you want to think through a problem, reflect on your approach,
or note something for your own reference. The value is in the writing process itself.发展
项目结构
jade-memory/
├── packages/
│ ├── shared/ # Auth, embed client, DB helpers, types
│ ├── knowledge/ # Knowledge base MCP server
│ └── journal/ # Journal MCP server
├── embeddings/ # Python embedding sidecar
├── docker-compose.yml
└── .env.example运行测试
# All tests (from repo root)
bun test
# Specific package
bun test --filter knowledge
bun test --filter journal
bun test --filter shared测试模拟嵌入sidecar并使用内存中的SQLite数据库。不需要Docker。
本地运行（无Docker）
# Terminal 1: Start embedding sidecar
cd embeddings
pip install -r requirements.txt
uvicorn main:app --port 3102
# Terminal 2: Start knowledge MCP
cd packages/knowledge
EMBEDDINGS_URL=http://localhost:3102 bun run src/index.ts
# Terminal 3: Start journal MCP
cd packages/journal
EMBEDDINGS_URL=http://localhost:3102 bun run src/index.ts启动时不需要API密钥。访问 http://localhost:3100 要创建管理员帐户，请转到 /admin 为MCP客户端创建API密钥。
资源使用
| 容器 | RAM | CPU | 磁盘 |
|---|---|---|---|
| 玉石镶嵌 | ~1.2 GB | 低（空闲），中等（编码） | ~2GB（型号） |
| 玉石知识 | ~50 MB | 最小值 | 随参赛作品增长 |
| 翡翠日记 | ~50 MB | 最小 | 随条目增长 |
嵌入模型（gte多语言库）是主要的资源成本。它支持100多种语言，包括英语、西班牙语、法语、德语和荷兰语。跨语言搜索是有效的——你可以用一种语言存储，用另一种语言回忆。