xmemory-cli 0.1.0

package/README.md

@@ -0,0 +1,315 @@
+# xMemory CLI
+
+xMemory 命令行工具 — 从终端访问和管理你的知识库。
+
+## 特性
+
+- 🔍 **语义搜索** — 基于向量的记忆搜索
+- 📝 **快速添加** — 命令行即时记录想法
+- 🗂️ **空间管理** — 创建和管理多个工作空间
+- 🏷️ **标签系统** — 按标签组织和筛选
+- 🔗 **知识图谱** — 查询实体关系网络
+- 📦 **多环境支持** — 项目级配置，互不干扰
+
+## 安装
+
+### 方式一：npm 全局安装
+
+```bash
+npm install -g @xmemory/cli
+```
+
+### 方式二：从源码构建
+
+```bash
+cd packages/xmemory-cli
+pnpm install
+pnpm run build
+pnpm link --global  # 或手动链接到 PATH
+```
+
+### 方式三：直接运行（无需安装）
+
+```bash
+cd packages/xmemory-cli
+pnpm install
+node bin/xmemory-cli.cjs --help
+```
+
+## 快速开始
+
+### 1. 配置 API Key
+
+> **⚠️ 安全警告:** API Key 明文存储在配置文件中。请确保 `.xmemory.json` 文件权限为 600（`chmod 600 ~/.xmemory.json`），不要将其提交到代码仓库。
+
+**推荐方式：环境变量**
+
+```bash
+export XMEMORY_API_KEY="xm-your-api-key-here"
+export DEFAULT_SPACE="my-workspace"
+```
+
+**备选：配置文件**
+
+在项目根目录或 home 目录创建 `.xmemory.json`：
+
+```json
+{
+  "apiBaseUrl": "http://localhost:50505/api",
+  "defaultSpace": "my-workspace",
+  "apiKey": "xm-your-api-key-here"
+}
+```
+
+或设置环境变量：
+
+```bash
+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. 开始使用
+
+```bash
+# 搜索记忆
+xmemory-cli search "Next.js 路由"
+
+# 添加记忆
+xmemory-cli add "记住：明天开会"
+
+# 列出所有空间
+xmemory-cli spaces list
+
+# 查询知识图谱
+xmemory-cli graph --entity "Elon Musk"
+```
+
+## 命令
+
+### search — 搜索记忆
+
+```bash
+xmemory-cli search <query> [options]
+```
+
+| 选项                 | 说明                 |
+| -------------------- | -------------------- |
+| `-l, --limit <n>`    | 最大结果数（默认 5） |
+| `-s, --space <name>` | 按空间筛选           |
+| `--json`             | JSON 格式输出        |
+
+### add — 添加记忆
+
+```bash
+xmemory-cli add <content> [options]
+```
+
+| 选项                   | 说明           |
+| ---------------------- | -------------- |
+| `-s, --space <name>`   | 空间名称       |
+| `--space-id <id>`      | 空间 ID        |
+| `-t, --tags <tags...>` | 标签           |
+| `--source <source>`    | 来源（如 URL） |
+| `--json`               | JSON 格式输出  |
+
+### list — 列出空间
+
+```bash
+xmemory-cli list [options]
+```
+
+| 选项                 | 说明               |
+| -------------------- | ------------------ |
+| `-s, --space <name>` | 列出指定空间的记忆 |
+| `--json`             | JSON 格式输出      |
+
+### get — 获取单条记忆
+
+```bash
+xmemory-cli get <id> [options]
+```
+
+| 选项     | 说明          |
+| -------- | ------------- |
+| `--json` | JSON 格式输出 |
+
+### delete — 删除记忆
+
+```bash
+xmemory-cli delete <id> [options]
+```
+
+| 选项     | 说明          |
+| -------- | ------------- |
+| `--json` | JSON 格式输出 |
+
+### spaces — 空间管理
+
+```bash
+xmemory-cli spaces <action> [options]
+```
+
+动作：
+
+| 动作            | 说明         |
+| --------------- | ------------ |
+| `list`          | 列出所有空间 |
+| `create <name>` | 创建空间     |
+| `delete <id>`   | 删除空间     |
+| `info <id>`     | 空间详情     |
+
+选项：
+
+| 选项                       | 适用动作 | 说明          |
+| -------------------------- | -------- | ------------- |
+| `-d, --description <text>` | create   | 空间描述      |
+| `--json`                   | 全部     | JSON 格式输出 |
+
+### tags — 标签列表
+
+```bash
+xmemory-cli tags [options]
+```
+
+| 选项              | 说明          |
+| ----------------- | ------------- |
+| `--space-id <id>` | 按空间筛选    |
+| `--json`          | JSON 格式输出 |
+
+### graph — 知识图谱
+
+```bash
+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 |
+
+## 多项目管理
+
+### 项目级配置
+
+每个项目可以有独立的配置：
+
+```bash
+~/projects/project-a/.xmemory.json  # 项目 A 配置
+~/projects/project-b/.xmemory.json  # 项目 B 配置
+```
+
+CLI 会自动读取当前目录下的配置：
+
+```bash
+cd ~/projects/project-a
+xmemory-cli search "query"  # 使用 project-a 的配置
+
+cd ~/projects/project-b
+xmemory-cli search "query"  # 使用 project-b 的配置
+```
+
+### 指定配置文件
+
+```bash
+xmemory-cli search "query" --config ~/configs/prod.json
+```
+
+### Shell 别名
+
+```bash
+# ~/.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 模式
+
+```bash
+xmemory-cli search "Next.js" --json
+```
+
+```json
+{
+  "results": [
+    {
+      "id": "abc123",
+      "content": "Next.js App Router 使用 Server Components...",
+      "tags": ["nextjs", "react"],
+      "similarity": 0.921,
+      "createdAt": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+## 项目结构
+
+```
+packages/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