内容
align="center">
<picture>
<source srcset="assets/diamondblock-logo.webp" type="image/webp">
<img src="assets/diamondblock-logo.png" width="220" height="124" alt="钻石块 — 钻石矿石块">
</picture>
</p>
<h1 align="center">钻石块</h1>
<p align="center">
<em>用于 AI 编程代理的本地优先的语义记忆服务器。</em>
</p>
<p align="center">
<img src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=flat-square&logo=nodedotColor=white" alt="Node.js 20+">
<img src="https://img.shields.io/badge/MCP-stdio-6B4C9A?style=flat-square" alt="MCP stdio">
<img src="https://img.shields.io/badge/license-MIT-111111?style=flat-square" alt="MIT 许可证">
</p>
<p align="center">
<strong>私有 · 语义 · strong><br>
<sub>钻石块在编码会话之间保留重要信息 — 您的偏好、项目决策和提炼的对话上下文 — 而不会将数据泄露到云端。</sub>
</p>
---
## 功能特点
- **本地优先：** 所有记忆、嵌入和索引都存储在您的机器上，以 Markdown + SQLite 格式。
- **MCP 服务器：** 通过 stdio 提供 `get_context`、`search_memory`、`save_memory`、`update_memory`、`delete_memory` 和 `log_session` 接口。
- **语义搜索：** 使用 `Xenova/all-MiniLM-L6-v2` 进行本地嵌入，可选 OpenAI 作为备用。
- **人类 CLI：** 通过终端管理记忆和会话，支持丰富的表格、颜色和加载动画。
- **会话提炼：** 原始会话日志会自动提炼成精选记忆。
- **代理友好：** 与 Claude Code、Kimi Code、AGY 以及任何 MCP 兼容的代理一起工作。
## 安装
需要 Node.js 20+。
```bash
npm install
npm run build
```
这会将 TypeScript 编译到 `dist/` 目录下，并注册 `diamondblock` 和 `dblock` 二进制文件。
## 快速入门
初始化一个保险库。默认情况下，它位于 `~/.diamondblock`。
```bash
npx diamondblock init
```
添加一个记忆：
```bash
npx diamondblock memory add --title "Prefer TypeScript" --type user --scope user --content "Always prefer TypeScript over JavaScript."
```
搜索记忆：
```bash
npx diamondblock memory search "typescript"
```
显示当前状态：
```bash
npx diamondblock status
```
## 为编码代理配置 MCP
将 DiamondBlock 集成到您的代理中的最快方法是使用内置安装程序：
```bash
npx diamondblock install mcp
```
这会检测您机器上的支持代理，并为每个代理编写正确的 MCP 配置。运行 `--dry-run` 预览更改内容：
```bash
npx diamondblock install mcp --dry-run
```
为单个代理安装：
```bash
npx diamondblock install mcp --target kimi
```
支持的代理：`kimi`、`kimi-code`、`claude`、`codex`、`agy`、`cursor`、`windsurf`、`cline`、`continue`。
### Kimi Code 手动配置
如果您更喜欢手动配置 Kimi Code，请创建或编辑 `~/.kimi/mcp.json`:
```json
{
"mcpServers": {
"diamondblock": {
"command": "node",
"args": [
"/path/to/diamondblock/dist/presentation/mcp/server.js"
],
"env": {
"DB_HOME": "${HOME}/.diamondblock"
}
}
}
}
```
| 代理 | 配置文件 |
|-------|-------------|
| `kimi` | `~/.kimi/mcp.json` |
| `` | `~/.kimi-code/mcp.json` |
| `claude` | `~aude/claude_desktop_config.json` |
| `codex` | `~/.codex/mcp.json` |
| `agy` | `~/.gem/mcp_config.json` `cursor` | `~/.cursor/mcp.json` |
windsurf` | `~/.codeium/windsurf/mcp_config.json` |
| `cline` | `~/.cline/mcp.json` |
| ` | `~/.continue/config.json` |
### OpenAI 嵌入（可选）
添加到/.diamondblock/.diamondblock.yml`:
```yaml
embedding openai
openaiApiKey: sk-...
openaiEmbeddingModel: text-embedding-3-small
```
如果省略，Diamond本地嵌入并且从不调用远程服务。
## CLI 参考 `diamondblock init [初始化一个新的保险库。如果省略 `path则使用 `~/.diamondblock` 或 `$DB。
### `diamondblock memory list [--scope < [--limit <n>]`
以表格形式列出记忆 `diamondblock memory search <query> [--scope <scope>] <n>]`
按语义或关键词搜索记忆 `diamondblock memory add --title <title> [--type <type>] [--scope <scope>] [--content <content>] [--tag <tag>]`
创建一个记忆。如果省略 `--content`，则打开器。
### `diamondblock memory show <id>`
以 Markdown 格式显示一个记忆。
### `diamondblock memory edit>`
在默认编辑器中打开一个记忆。
### `diamondblock memory delete <id> [--yes]`
删除一个非传递 `--yes`，否则会要求确认。
### `diamondblock session list [--limit>]`
列出最近的会话。
### `diamondblock session show <id>`
显示一个会话的原始日志。
### `diamondblock distill [--dry-run] [--limit <n>]`
将未处理的会话提炼成记忆。
### `diamondblock status`
显示保险库统计信息：路径、嵌入提供程序、记忆数量和会话数量。
### `diamondblockcp [--target <agent>] [--dry-run为检测到的代理安装 作为 MCP 服务器。使用 `--dry-run` 预览更改并使用 `--target` 为单个代理安装。
## MCP 工具参考
MCP 服务器为编码代理公开相同的记忆系统。
### `get_context`
返回当前会话的紧凑上下文。
```json
{
"session_id": "sess_abc123",
"project_id": "my-project",
"mode": "coding"
}
```
### `search_memory`
按关键词搜索记忆。
{
"query": "authentication strategy",
" "project/my-project",
"limit": 5
}
```
### `save_memory`
创建一个记忆。
```json
{
"title": "Use JWT for auth",
"content": "We decided to use signed JWTs stored in httpOnly cookies.",
"type": "project",
"scope": "project/my-project",
"tags": ["auth", "architecture"]
}
```
### `update_memory`
更新到一个记忆中。
```json
{
" "mem_abc123",
"content": "Updated "append": false
}
```
### `delete_memory一个记忆。
```json
{
"id": "mem_abc123"
}
```
### `log_session`
记录一个原始会话以供后续提炼。
```json
{
"session_id": "sess_abc123",
"project_id": "my-project",
" [
{ "roleuser", "content": "How do we handle auth { "role":", "content": "Use JWT in httpOnly cookies." }
]
}
```
## 配置
DiamondBlock 读取 `~/.diamondblock/.diamondblock.yml`:
```yaml
vaultPath:/me/.diamondblock
embeddingProvider: local
heartbeatIntervalMinutes: 60
contextWindowTokens: 8000
```
| 字段 | 默认值 | 描述 |
|-------|---------|-------------|
| `vaultPath` |/.diamondblock` | 保险库的根目录。 |
| `embeddingProvider` | `local` | `local` 或 `openai`。 |
| `heartbeatIntervalMinutes` | `60` | 自动会话提炼的间隔。 |
|WindowTokens` | `8000` | 返回给代理的上下文目标大小。 |
## 开发
```bash
npm install
npm run build
npm test
npm run typecheck
```
在开发模式下运行 CLI：
```bash
npm run cli -- memory list
```
手动运行 MCP 服务器：
```bash
npm run mcp
```
## 许可证
MIT
