@hippo-memo/cli 1.0.1 → 1.0.3

package/dist/template/README.md

@@ -15,8 +15,14 @@ Hippo Memory 的预设内存模板集合。
 ```
 template/
 ├── mcp/          # MCP 服务器相关模板
-│   └── system/   # 系统级内存模板
+│   └── AGENTS.md # MCP 协议配置
+├── skill/        # Claude Code Skill 模板
+│   ├── hippo-memory/  # 记忆管理技能
+│   └── hippo-init/    # 初始化引导技能
 └── system/       # 通用系统模板
+    ├── agent.md  # AI 能力边界
+    ├── soul.md   # AI 身份和行为模式
+    └── user.md   # 用户信息和偏好
 ```
 
 ## 系统模板
@@ -50,4 +56,38 @@ AI 能力边界定义
 
 ## 使用方式
 
-模板通常在初始化新的 Hippo Memory 实例时自动应用，通过 `@hippo-memo/core` 包的初始化功能加载。
+### CLI 初始化
+
+运行 `hippo init` 时会自动：
+
+1. 创建 `.hippo` 记忆存储目录
+2. 初始化系统记忆（system://boot, system://soul, system://user）
+3. 提示选择 Claude Code 集成方式：
+   - **MCP 模式**：将协议注入到 `AGENTS.md` 或 `CLAUDE.md`
+   - **Skill 模式**：复制技能模板到 `.claude/skills/`
+   - **混合模式**：同时配置 MCP 和 Skill
+
+### MCP vs Skill
+
+| 特性 | MCP | Skill |
+|------|-----|-------|
+| **作用域** | 全局/用户级 | 项目级 |
+| **存储位置** | Claude 配置目录 | `.claude/skills/` |
+| **版本控制** | 不推荐 | 推荐 |
+| **适用场景** | 跨项目共享 | 项目特定流程 |
+
+### 技能说明
+
+#### hippo-memory
+提供完整的 Hippo Memory 操作指南，包括：
+- 创建、读取、更新、删除记忆
+- 搜索记忆内容
+- 管理记忆别名
+- URI 设计规范和最佳实践
+
+#### hippo-init
+项目初始化引导技能，包括：
+- 记忆目录创建
+- MCP vs Skill 选择指导
+- 配置文件说明
+- 故障排查

package/dist/template/skill/AGENTS.md

@@ -0,0 +1,21 @@
+# 🧠 Hippo Memory
+
+**hippo-memory** 是项目的持久记忆层 skill，用于存储用户偏好、项目上下文、技术决策等跨会话信息。
+
+## ⚡ 会话启动
+
+**每次新会话必须检索系统引导记忆，了解用户偏好、项目上下文和核心配置。**
+
+## 🎯 调用指南
+
+**触发场景：**
+- 用户询问或提及任何可被记忆的信息（偏好、配置、决策、历史、上下文等）
+- 关键词命中：我/我的/习惯/喜欢/选择/决定/记住/保存/my/I prefer/remember/save/previous/architecture/config/settings/架构/配置/规范
+- 用户透露任何可存储的信息（新的偏好、决策、习惯、技术选型等）
+- 回答涉及用户私有信息时需要验证
+
+**核心原则：**
+- 涉及用户私有信息时，必须先检索记忆，禁止猜测
+- 用户透露新信息时，立即存储到记忆
+
+---

package/dist/template/skill/hippo-memory/SKILL.md

@@ -0,0 +1,257 @@
+---
+name: hippo-memory
+description: "🧠 Persistent memory layer. ALWAYS ACTIVE: (1) SEARCH when user asks about memorable info, (2) STORE when user reveals storable info. Keywords: 我/我的/习惯/喜欢/选择/决定/记住/保存/my/I prefer/remember/save/previous/architecture/config/架构/配置. Never guess without searching."
+---
+
+# Hippo Memory Skill
+
+## 概述
+
+此技能提供 Hippo Memory 存储系统的管理功能，通过 `bunx @hippo-memo/cli@latest` 命令进行记忆的增删改查、搜索和别名操作。
+
+## ⚡ 会话启动协议
+
+**每次新会话必须且只能执行：**
+```bash
+bunx @hippo-memo/cli@latest memory read "system://boot"
+```
+
+## 🎯 "三思而后答"强制检查
+
+**回复前必须完成以下思维链：**
+
+| 检查项 | 判定 | 动作 |
+|--------|------|------|
+| **A. 领域** | 用户询问私有记忆/历史/偏好？ | → 立即检索 |
+| **B. 完备性** | 我有确凿证据支撑回答？ | → 不确定则先验证 |
+| **C. 决策** | A=B=是 | → **调用 CLI 后再输出** |
+
+**违规 = 任务失败**
+
+## 🏗️ 系统节点
+
+推荐创建以下系统级记忆节点：
+
+| URI | 作用 |
+|-----|------|
+| `system://boot` | 会话入口，合成核心摘要 |
+| `system://soul` | 身份/行为模式 |
+| `system://user` | 用户信息/偏好 |
+| `system://project` | 项目核心信息 |
+| `system://recent` | 近期事件 |
+
+## 📖 读取协议：检索优先
+
+### 必须检索的触发条件（任一）
+1. 用户提到：项目名、人名、过往约定
+2. 问题包含："我记得"、"之前说过"、"我的配置"
+3. 涉及时间线："上周"、"上次"
+4. disclosure 被触发
+5. 回答依赖"可能"、"大概"
+
+### 检索策略
+```bash
+# 确切 URI
+bunx @hippo-memo/cli@latest memory read "system://user"
+
+# 大致位置
+bunx @hippo-memo/cli@latest memory search "数据库"
+
+# 不确定 - 多个关键词尝试
+bunx @hippo-memo/cli@latest memory search "上周 项目 数据库"
+```
+
+### ❌ 禁止
+- 基于通用知识回答私有信息
+- 使用"可能"、"大概"而不验证
+- 未检索时说"我记得..."
+
+### ✅ 正确
+调用 CLI → "根据您的记录..."
+
+## ✍️ 写入协议
+
+### create_memory 触发条件
+- 新的重要认知/感悟
+- 用户透露重要信息
+- 发生重大事件
+- 跨会话复用的结论
+
+### update_memory 触发条件
+- **必须先 `memory read`**，再修正
+- 发现过去认知错误
+- 用户纠正你
+- 信息过时
+
+**铁律：改记忆前，先读记忆。**
+
+## URI 设计规范
+
+### 域名分类
+- `system://` - 系统级记忆（身份、配置）
+- `project://` - 项目级记忆（架构、决策）
+- `user://` - 用户级记忆（偏好、习惯）
+- `knowledge://` - 知识库（技术文档、最佳实践）
+- `temp://` - 临时记忆（会话缓存）
+
+### 路径设计
+```
+system://boot
+system://soul
+system://user/preferences
+system://project/{project-name}
+project://myapp/architecture/database
+user://preferences/pkg-manager
+knowledge://tech/auth-jwt
+temp://session/cache
+```
+
+## CLI 命令
+
+### 1. 创建记忆
+```bash
+bunx @hippo-memo/cli@latest memory create "user://note/test" "# 测试笔记\n这是内容"
+```
+选项：
+- `-p, --priority <1-10>` - 优先级（默认: 5）
+- `-d, --disclosure <string>` - 触发条件
+- `--dir <directory>` - 记忆目录（默认: .memory）
+
+### 2. 读取记忆
+```bash
+bunx @hippo-memo/cli@latest memory read "user://note/test"
+```
+
+### 3. 更新记忆
+```bash
+bunx @hippo-memo/cli@latest memory update "user://note/test" "更新内容"
+```
+选项：
+- `-p, --priority <1-10>` - 更新优先级
+- `-d, --disclosure <string>` - 更新触发条件
+
+### 4. 删除记忆
+```bash
+bunx @hippo-memo/cli@latest memory delete "user://note/test"
+```
+选项：
+- `-r, --recursive` - 递归删除子记忆
+- `--permanent` - 永久删除（不进入回收站）
+
+### 5. 搜索记忆
+```bash
+bunx @hippo-memo/cli@latest memory search "测试"
+```
+选项：
+- `--domain <string>` - 限定域名
+- `-l, --limit <number>` - 结果数量（默认: 20）
+
+### 6. 列出所有记忆
+```bash
+bunx @hippo-memo/cli@latest memory list
+```
+选项：
+- `--domain <string>` - 限定域名
+
+### 7. 添加别名
+```bash
+bunx @hippo-memo/cli@latest memory alias "alias://test" "user://note/test"
+```
+选项：
+- `-p, --priority <1-10>` - 别名优先级（继承目标默认）
+- `-d, --disclosure <string>` - 别名触发条件
+
+## 🔄 结构操作
+
+```bash
+# 移动/重命名：先建后删
+bunx @hippo-memo/cli@latest memory alias "new" "old"
+bunx @hippo-memo/cli@latest memory delete "old"
+
+# 删除前：先读确认
+bunx @hippo-memo/cli@latest memory read "to_delete"
+bunx @hippo-memo/cli@latest memory delete "to_delete"
+
+# 多重入口
+bunx @hippo-memo/cli@latest memory alias "path/a" "path/b"
+bunx @hippo-memo/cli@latest memory alias "path/c" "path/b"
+```
+
+## 最佳实践
+
+### 优先级指南
+| 级别 | 含义 | 上限 | 示例 |
+|------|------|------|------|
+| **10** | 核心身份 | 5条 | `system://boot`, `system://soul` |
+| **8-9** | 关键事实/高频模式 | 15条 | 用户偏好、项目架构决策 |
+| **5-7** | 一般记忆 | 无限制 | 技术文档、会议记录 |
+| **1-4** | 冷门信息 | 无限制 | 临时缓存、调试信息 |
+
+### Disclosure 规范
+Disclosure 定义了记忆的自动触发条件，帮助 LLM 主动检索：
+
+✅ **好的 disclosure**:
+```
+"当用户提到项目 hippo 时"
+"当讨论包管理器选择时"
+"当周五或周末安排任务时"
+"当实现认证功能时"
+```
+
+❌ **不好的 disclosure**:
+```
+"重要"
+"记住"
+"用户信息"
+"配置"
+```
+
+### 主动触发场景
+
+| 场景 | 示例输入 | 存储动作 |
+|------|----------|----------|
+| **显性请求** | "记住我周末不工作" | `memory create "user://availability/weekend" ...` |
+| **偏好表达** | "我喜欢用 pnpm" | `memory create "user://pref/pkg-manager" "pnpm" --disclosure "当选择包管理器时"` |
+| **架构决策** | "这个项目用 PostgreSQL" | `memory create "project://myapp/database" "PostgreSQL 15+" --disclosure "当讨论数据库时"` |
+| **技术约定** | "组件都用 shadcn/ui" | `memory create "project://myapp/ui-lib" "shadcn/ui" --disclosure "当创建 UI 组件时"` |
+
+## 🎭 Few-Shot 示例
+
+### 检索优先
+```
+用户："我上周项目用的什么数据库？"
+
+❌ "可能是 PostgreSQL..."
+✅ bunx @hippo-memo/cli@latest memory search "上周 项目 数据库"
+   → bunx @hippo-memo/cli@latest memory read "..."
+   → "根据记录，用的是 MongoDB"
+```
+
+### Disclosure 触发
+```
+用户："我要实现登录功能"
+
+✅ 检测到"登录"
+   → bunx @hippo-memo/cli@latest memory read "knowledge/auth"
+   → "您之前确定用 JWT 方案，对吗？"
+```
+
+### 写入新记忆
+```
+用户："我周末不工作"
+
+✅ bunx @hippo-memo/cli@latest memory create \
+     "user://availability/weekend" \
+     "用户周末不工作，周一处理" \
+     --priority 8 \
+     --disclosure "当周五/周末安排任务时"
+```
+
+## 🔚 回复前自检
+
+- [ ] 涉及私有信息？→ 调用 `memory read`/`memory search`
+- [ ] 不确定？→ 先验证而非猜测
+- [ ] 用户新信息？→ 立即 `memory create`
+- [ ] 引用记忆？→ 标注来源 URI
+
+**全部通过 → 输出 | 任一未通过 → 先执行 CLI**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hippo-memo/cli",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "bin": {
     "hippo": "./dist/index.js"
@@ -16,6 +16,7 @@
   },
   "devDependencies": {
     "@types/node": "^20",
+    "@types/prompts": "^2.4.9",
     "concurrently": "^9.2.1",
     "typescript": "^5"
   }

package/src/commands/index.ts

@@ -1,2 +1,3 @@
 export * from "./init";
+export * from "./memory";
 export * from "./web";

package/src/commands/init.ts

@@ -1,6 +1,7 @@
 import {
   access,
   constants,
+  cp,
   mkdir,
   readFile,
   writeFile
@@ -9,10 +10,19 @@ import { EOL } from "node:os";
 import { join } from "node:path";
 import { createConfig, createStore } from "@hippo-memo/core";
 import { MEMORY_DIR_NAME } from "@hippo-memo/shared";
+import prompts from "prompts";
 
 const __dirname = import.meta.dirname;
 const TEMPLATE_DIR = join(__dirname, "../../template/system");
-const AGENTS_TEMPLATE_PATH = join(__dirname, "../../template/mcp/AGENTS.md");
+const MCP_AGENTS_TEMPLATE_PATH = join(
+  __dirname,
+  "../../template/mcp/AGENTS.md"
+);
+const SKILL_AGENTS_TEMPLATE_PATH = join(
+  __dirname,
+  "../../template/skill/AGENTS.md"
+);
+const SKILL_TEMPLATE_DIR = join(__dirname, "../../template/skill");
 
 const TEMPLATE_URIS = {
   agent: "system://agent",
@@ -20,6 +30,8 @@ const TEMPLATE_URIS = {
   user: "system://user"
 };
 
+type InitMode = "mcp" | "skill";
+
 async function readTemplateContent(filename: string): Promise<string> {
   return readFile(join(TEMPLATE_DIR, filename), "utf-8");
 }
@@ -38,15 +50,12 @@ function getInjectionMarker(content: string): string {
  */
 function isAlreadyInjected(content: string, marker: string): boolean {
   const lines = content.split("\n");
-  // 跳过开头的空行
   const firstNonEmptyLine = lines.find((line) => line.trim() !== "");
   return firstNonEmptyLine?.trim() === marker;
 }
 
 /**
  * 安全地将内容注入到文件顶部
- * @param filePath 目标文件路径
- * @param contentToInject 要注入的内容
  */
 async function injectToTopOfFile(
   filePath: string,
@@ -61,10 +70,8 @@ async function injectToTopOfFile(
       originalContent = "";
     }
 
-    // 从注入内容中提取第一行作为标识符
     const injectionMarker = getInjectionMarker(contentToInject);
 
-    // 幂等性检查：通过第一行判断是否已注入
     if (
       originalContent &&
       isAlreadyInjected(originalContent, injectionMarker)
@@ -73,7 +80,6 @@ async function injectToTopOfFile(
       return;
     }
 
-    // 拼接内容，注意处理换行符
     const separator = originalContent ? `${EOL}${EOL}` : "";
     const updatedContent = `${contentToInject}${separator}${originalContent}`;
 
@@ -88,7 +94,11 @@ async function injectToTopOfFile(
 /**
  * 检测并处理 AGENTS.md 和 CLAUDE.md 文件
  */
-async function handleAgentsAndClaudeFiles(directory: string): Promise<void> {
+async function handleAgentsAndClaudeFiles(
+  directory: string,
+  templatePath: string,
+  mode: InitMode
+): Promise<void> {
   const agentsPath = join(directory, "AGENTS.md");
   const claudePath = join(directory, "CLAUDE.md");
 
@@ -109,24 +119,139 @@ async function handleAgentsAndClaudeFiles(directory: string): Promise<void> {
     // CLAUDE.md 不存在
   }
 
-  // 读取 AGENTS.md 模板内容
-  const agentsContent = await readFile(AGENTS_TEMPLATE_PATH, "utf-8");
+  const agentsContent = await readFile(templatePath, "utf-8");
+  const configName = mode === "mcp" ? "MCP" : "Skill";
 
   if (hasClaude) {
-    // CLAUDE.md 存在：优先注入到 CLAUDE.md 顶部
     console.log("› Found: CLAUDE.md");
-    await injectToTopOfFile(claudePath, agentsContent);
+
+    // 检查是否已注入
+    const existingContent = await readFile(claudePath, "utf-8");
+    const injectionMarker = getInjectionMarker(agentsContent);
+
+    if (!isAlreadyInjected(existingContent, injectionMarker)) {
+      const response = await prompts({
+        type: "confirm",
+        name: "inject",
+        message: `Inject ${configName} configuration to CLAUDE.md?`,
+        initial: true
+      });
+
+      if (response.inject) {
+        await injectToTopOfFile(claudePath, agentsContent);
+      } else {
+        console.log("› Skipped: CLAUDE.md");
+      }
+    } else {
+      console.log("› Skipped: content already exists");
+    }
   } else if (hasAgents) {
-    // 只有 AGENTS.md 存在：注入到 AGENTS.md 顶部
     console.log("› Found: AGENTS.md");
-    await injectToTopOfFile(agentsPath, agentsContent);
+
+    const existingContent = await readFile(agentsPath, "utf-8");
+    const injectionMarker = getInjectionMarker(agentsContent);
+
+    if (!isAlreadyInjected(existingContent, injectionMarker)) {
+      const response = await prompts({
+        type: "confirm",
+        name: "inject",
+        message: `Inject ${configName} configuration to AGENTS.md?`,
+        initial: true
+      });
+
+      if (response.inject) {
+        await injectToTopOfFile(agentsPath, agentsContent);
+      } else {
+        console.log("› Skipped: AGENTS.md");
+      }
+    } else {
+      console.log("› Skipped: content already exists");
+    }
   } else {
-    // 两者都不存在：创建 AGENTS.md
-    console.log("✔ Created: AGENTS.md");
+    console.log(`✔ Created: AGENTS.md`);
     await writeFile(agentsPath, agentsContent, "utf-8");
   }
 }
 
+/**
+ * 复制 Skill 模板到项目目录
+ */
+async function copySkillTemplates(directory: string): Promise<void> {
+  const targetSkillDir = join(directory, ".claude", "skills");
+
+  try {
+    await mkdir(targetSkillDir, { recursive: true });
+  } catch {
+    // 目录可能已存在
+  }
+
+  const skills = ["hippo-memory"];
+
+  for (const skill of skills) {
+    const sourceDir = join(SKILL_TEMPLATE_DIR, skill);
+    const targetDir = join(targetSkillDir, skill);
+    const targetFile = join(targetDir, "SKILL.md");
+
+    try {
+      await mkdir(targetDir, { recursive: true });
+
+      // 检查文件是否已存在
+      let fileExists = false;
+      try {
+        await access(targetFile, constants.F_OK);
+        fileExists = true;
+      } catch {
+        // 文件不存在
+      }
+
+      if (fileExists) {
+        const response = await prompts({
+          type: "confirm",
+          name: "overwrite",
+          message: `Skill ${skill} already exists. Overwrite?`,
+          initial: false
+        });
+
+        if (!response.overwrite) {
+          console.log(`› Skipped: ${skill}`);
+          continue;
+        }
+      }
+
+      await cp(join(sourceDir, "SKILL.md"), targetFile);
+      console.log(`✔ Installed skill: ${skill}`);
+    } catch (error: unknown) {
+      console.error(`✖ Failed to install skill: ${skill}`, error);
+    }
+  }
+}
+
+/**
+ * 询问用户初始化模式
+ */
+async function askInitMode(): Promise<InitMode> {
+  const response = await prompts({
+    type: "select",
+    name: "mode",
+    message: "选择 Claude Code 集成方式:",
+    choices: [
+      {
+        title: "🔌 MCP 模式 (推荐全局配置)",
+        description: "适用于跨项目共享记忆，需要单独配置 MCP 服务器",
+        value: "mcp"
+      },
+      {
+        title: "📜 Skill 模式 (推荐项目配置)",
+        description: "项目级技能，可提交到 Git 与团队共享",
+        value: "skill"
+      }
+    ],
+    initial: 1
+  });
+
+  return (response.mode as InitMode) || "skill";
+}
+
 export async function init(directory: string): Promise<void> {
   const memoryRoot = join(directory, MEMORY_DIR_NAME);
 
@@ -134,7 +259,6 @@ export async function init(directory: string): Promise<void> {
     await access(memoryRoot, constants.F_OK);
     console.log(`Memory directory already exists at ${memoryRoot}`);
   } catch {
-    // Directory doesn't exist, proceed with creation
     await mkdir(memoryRoot, { recursive: true });
 
     const store = createStore({
@@ -149,10 +273,38 @@ export async function init(directory: string): Promise<void> {
       })
     );
 
-    console.log(`Initialized hippo memory at ${memoryRoot}`);
+    console.log(`✔ Initialized hippo memory at ${memoryRoot}`);
   }
 
-  // 处理 AGENTS.md 和 CLAUDE.md 文件
-  console.log("◇ Checking AGENTS.md and CLAUDE.md...");
-  await handleAgentsAndClaudeFiles(directory);
+  // 询问初始化模式
+  const mode = await askInitMode();
+
+  // 处理 MCP 配置 (注入到 AGENTS.md/CLAUDE.md)
+  if (mode === "mcp") {
+    console.log(`${EOL}◇ Setting up MCP integration...`);
+    await handleAgentsAndClaudeFiles(directory, MCP_AGENTS_TEMPLATE_PATH, mode);
+    console.log(`${EOL}✨ Setup complete!${EOL}`);
+    console.log("📌 Next steps:");
+    console.log("   1. Configure MCP server in Claude Code settings");
+    console.log("   2. Run: hippo web -p 3000");
+    console.log("");
+  }
+
+  // 处理 Skill 配置
+  if (mode === "skill") {
+    console.log(`${EOL}◇ Installing Claude Code Skills...`);
+    await handleAgentsAndClaudeFiles(
+      directory,
+      SKILL_AGENTS_TEMPLATE_PATH,
+      mode
+    );
+    await copySkillTemplates(directory);
+    console.log(`${EOL}✨ Setup complete!${EOL}`);
+    console.log("📌 Next steps:");
+    console.log("   1. Skills installed in .claude/skills/");
+    console.log("   2. Configuration injected to CLAUDE.md");
+    console.log("   3. LLM will automatically trigger when needed");
+    console.log("   4. Commit to Git to share with your team");
+    console.log("");
+  }
 }