xMemory CLI

xMemory 命令行工具 — 从终端访问和管理你的知识库。

特性

• 🔍 语义搜索 — 基于向量的记忆搜索
• 📝 快速添加 — 命令行即时记录想法
• 🗂️ 空间管理 — 创建和管理多个工作空间
• 🏷️ 标签系统 — 按标签组织和筛选
• 🔗 知识图谱 — 查询实体关系网络
• 📦 多环境支持 — 项目级配置，互不干扰

安装

方式一：npm 全局安装

npm install -g xmemory-cli

方式二：从源码构建

cd apps/xmemory-cli
pnpm install
pnpm run build
pnpm link --global  # 或手动链接到 PATH

方式三：直接运行（无需安装）

cd apps/xmemory-cli
pnpm install
node bin/xmemory-cli.cjs --help

快速开始

1. 配置 API Key

⚠️ 安全警告: API Key 明文存储在配置文件中。请确保 .xmemory.json 文件权限为 600（chmod 600 ~/.xmemory.json），不要将其提交到代码仓库。

推荐方式：环境变量

export XMEMORY_API_KEY="xm-your-api-key-here"
export DEFAULT_SPACE="my-workspace"

备选：配置文件

在项目根目录或 home 目录创建 .xmemory.json：

{
  "apiBaseUrl": "http://localhost:50505/api",
  "defaultSpace": "my-workspace",
  "apiKey": "xm-your-api-key-here"
}

或设置环境变量：

export XMEMORY_API_KEY="xm-your-api-key"
export DEFAULT_SPACE="my-workspace"

2. 获取 API Key

1. 启动 xMemory：bun run start:web
2. 访问 http://localhost:50505/settings
3. 进入 Developer → Generate API Key

3. 开始使用

# 搜索记忆
xmemory-cli search "Next.js 路由"

# 添加记忆
xmemory-cli add "记住：明天开会"

# 列出所有空间
xmemory-cli spaces list

# 查询知识图谱
xmemory-cli graph --entity "Elon Musk"

命令

search — 搜索记忆

xmemory-cli search <query> [options]

| 选项 | 说明 | | -------------------- | -------------------- | | -l, --limit <n> | 最大结果数（默认 5） | | -s, --space <name> | 按空间筛选 | | --json | JSON 格式输出 |

add — 添加记忆

xmemory-cli add <content> [options]

| 选项 | 说明 | | ---------------------- | -------------- | | -s, --space <name> | 空间名称 | | --space-id <id> | 空间 ID | | -t, --tags <tags...> | 标签 | | --source <source> | 来源（如 URL） | | --json | JSON 格式输出 |

list — 列出空间

xmemory-cli list [options]

| 选项 | 说明 | | -------------------- | ------------------ | | -s, --space <name> | 列出指定空间的记忆 | | --json | JSON 格式输出 |

get — 获取单条记忆

xmemory-cli get <id> [options]

| 选项 | 说明 | | -------- | ------------- | | --json | JSON 格式输出 |

delete — 删除记忆

xmemory-cli delete <id> [options]

| 选项 | 说明 | | -------- | ------------- | | --json | JSON 格式输出 |

spaces — 空间管理

xmemory-cli spaces <action> [options]

动作：

| 动作 | 说明 | | --------------- | ------------ | | list | 列出所有空间 | | create <name> | 创建空间 | | delete <id> | 删除空间 | | info <id> | 空间详情 |

选项：

| 选项 | 适用动作 | 说明 | | -------------------------- | -------- | ------------- | | -d, --description <text> | create | 空间描述 | | --json | 全部 | JSON 格式输出 |

tags — 标签列表

xmemory-cli tags [options]

| 选项 | 说明 | | ----------------- | ------------- | | --space-id <id> | 按空间筛选 | | --json | JSON 格式输出 |

graph — 知识图谱

xmemory-cli graph [options]

| 选项 | 说明 | | --------------------- | ------------- | | -e, --entity <name> | 查询实体 | | -t, --tag <tag> | 按标签筛选 | | --space-id <id> | 按空间筛选 | | --json | JSON 格式输出 |

全局选项

| 选项 | 说明 | | ---------------------- | ---------------------- | | -c, --config <path> | 配置文件路径 | | --api-base-url <url> | API 地址 | | -s, --space <name> | 默认空间 | | --output <format> | 输出格式：json 或 text |

多项目管理

项目级配置

每个项目可以有独立的配置：

~/projects/project-a/.xmemory.json  # 项目 A 配置
~/projects/project-b/.xmemory.json  # 项目 B 配置

CLI 会自动读取当前目录下的配置：

cd ~/projects/project-a
xmemory-cli search "query"  # 使用 project-a 的配置

cd ~/projects/project-b
xmemory-cli search "query"  # 使用 project-b 的配置

指定配置文件

xmemory-cli search "query" --config ~/configs/prod.json

Shell 别名

# ~/.bashrc 或 ~/.zshrc
alias xm-a='xmemory-cli --config ~/.xmemory-project-a.json'
alias xm-b='xmemory-cli --config ~/.xmemory-project-b.json'

输出示例

文本模式（默认）

$ xmemory-cli search "Next.js"

Found 3 memories:

[abc123] (92.1% match)
Next.js App Router 使用 Server Components 作为默认渲染方式...
Tags: nextjs, react
Created: 2024-01-15 10:30:00

[def456] (85.3% match)
Next.js 14 新特性：Server Actions 和 Route Handlers...
Tags: nextjs
Created: 2024-01-14 15:20:00

JSON 模式

xmemory-cli search "Next.js" --json

{
  "results": [
    {
      "id": "abc123",
      "content": "Next.js App Router 使用 Server Components...",
      "tags": ["nextjs", "react"],
      "similarity": 0.921,
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

项目结构

apps/xmemory-cli/
├── package.json
├── build.mjs                    # esbuild 构建脚本
├── bin/
│   ├── xmemory-cli.js           # 源码入口
│   └── xmemory-cli.cjs          # 构建产物
└── src/
    ├── index.ts                 # 包导出
    ├── config/index.ts          # 配置加载
    ├── api/client.ts            # API 客户端
    └── commands/
        ├── search.ts
        ├── add.ts
        ├── list.ts
        ├── get.ts
        ├── delete.ts
        ├── spaces.ts
        ├── tags.ts
        └── graph.ts

技术栈

• 运行时：Node.js >= 18
• 打包：esbuild
• CLI 框架：Commander.js
• 输出着色：Chalk

许可证

MIT