AI导哈

AI代理知识库与日志服务

为AI代理提供的持久化知识库和日志服务，支持多语言语义搜索和结构化思考记录。

  • by jjjona
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 jjjona/jade-memory

使用说明

玉记忆

人工智能代理的持久知识库和期刊。两个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 <repo-url> 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://<host>:3100 （知识）或 http://<host>: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 <your-api-key>" \
  -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 登录后。更换 <API_KEY> 下面是您在那里创建的密钥。

克劳德代码

选项A:CLI（推荐）

claude mcp add --transport http jade-knowledge http://<host>:3100/mcp \
  --header "Authorization: Bearer <API_KEY>"

claude mcp add --transport http jade-journal http://<host>:3101/mcp \
  --header "Authorization: Bearer <API_KEY>"

使用 --scope user 使其可用于所有项目，或 --scope local （默认）仅适用于当前项目。

选项B:JSON配置

增添 ~/.claude.json （或项目级别 .claude/settings.json)under mcpServers:

{
  "mcpServers": {
    "jade-knowledge": {
      "type": "http",
      "url": "http://<host>:3100/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    },
    "jade-journal": {
      "type": "http",
      "url": "http://<host>:3101/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

开源代码

增添 opencode.json 在项目根目录中：

{
  "mcp": {
    "jade-knowledge": {
      "type": "remote",
      "url": "http://<host>:3100/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    },
    "jade-journal": {
      "type": "remote",
      "url": "http://<host>:3101/mcp",
      "headers": {
        "Authorization": "Bearer <API_KEY>"
      }
    }
  }
}

你可以使用 {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多种语言，包括英语、西班牙语、法语、德语和荷兰语。跨语言搜索是有效的——你可以用一种语言存储，用另一种语言回忆。

相关 MCP