玉记忆
知识库 使用语义搜索存储事实、决策、程序和故障排除说明。客服电话 store 保存知识和 recall 检索它。条目被键入、标记和跨语言搜索。
期刊 是一种自由形式、仅附加的认知工具。代理人写想法、反思和会议笔记。价值在于写作过程(结构化思维),而不仅仅是检索。没有类别或部分——语义存在于内容本身。
建筑```
┌─────────────────────────────────────────────────────┐
│ 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.克隆和配置```bash
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.构建并启动```bash
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.验证```bash
# 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:```bash
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(推荐)```bash
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:```json
{
"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` 在项目根目录中:```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
运行测试```bash
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)```bash
# 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 | 最小 | 随条目增长 |