@hippo-memo/cli 1.0.0

package/dist/template/mcp/AGENTS.md

@@ -0,0 +1,137 @@
+# 🧠 Hippo Memory MCP Protocol
+
+## ⚡ 会话启动协议
+**每次新会话必须且只能执行：**
+```
+read_memory(uri="system://boot")
+```
+
+## 🎯 "三思而后答"强制检查
+
+**回复前必须完成以下思维链：**
+
+| 检查项 | 判定 | 动作 |
+|--------|------|------|
+| **A. 领域** | 用户询问私有记忆/历史/偏好？ | → 立即检索 |
+| **B. 完备性** | 我有确凿证据支撑回答？ | → 不确定则先验证 |
+| **C. 决策** | A=B=是 | → **调用 MCP 工具后再输出** |
+
+**违规 = 任务失败**
+
+## 🏗️ system:// 特殊节点
+
+| URI | 作用 |
+|-----|------|
+| `system://boot` | 会话入口，合成核心摘要 |
+| `system://soul` | 身份/行为模式 |
+| `system://user` | 用户信息/偏好 |
+| `system://agent` | 能力边界 |
+| `system://index` | 记忆索引 |
+| `system://recent` | 近期事件 |
+
+## 📖 读取协议：检索优先
+
+### 必须检索的触发条件（任一）
+1. 用户提到：项目名、人名、过往约定
+2. 问题包含："我记得"、"之前说过"、"我的配置"
+3. 涉及时间线："上周"、"上次"
+4. disclosure 被触发
+5. 回答依赖"可能"、"大概"
+
+### 检索策略
+```
+确切 URI → read_memory(uri="...")
+大致位置 → search_memory(query="关键词")
+不确定   → search_memory(query="多个关键词尝试")
+```
+
+### ❌ 禁止
+- 基于通用知识回答私有信息
+- 使用"可能"、"大概"而不验证
+- 未检索时说"我记得..."
+
+### ✅ 正确
+调用工具 → "根据您的记录..."
+
+## ✍️ 写入协议
+
+### create_memory 触发条件
+- 新的重要认知/感悟
+- 用户透露重要信息
+- 发生重大事件
+- 跨会话复用的结论
+
+### update_memory 触发条件
+- **必须先 `read_memory`**，再修正
+- 发现过去认知错误
+- 用户纠正你
+- 信息过时
+
+**铁律：改记忆前，先读记忆。**
+
+### Priority 指南
+| 级别 | 含义 | 上限 |
+|------|------|------|
+| 10 | 核心身份 | 5条 |
+| 8-9 | 关键事实/高频模式 | 15条 |
+| 5-7 | 一般记忆 | 无限制 |
+| 1-4 | 冷门信息 | 无限制 |
+
+### Disclosure 规范
+✅ `"当用户提到项目 X 时"`
+✅ `"当讨论技术选型时"`
+❌ `"重要"` / `"记住"` / `"用户信息"`
+
+## 🔄 结构操作
+
+```
+移动/重命名：先建后删
+add_alias(newUri="new", targetUri="old")
+delete_memory(uri="old")
+
+删除前：先读确认
+read_memory(uri="to_delete")
+delete_memory(uri="to_delete")
+
+多重入口
+add_alias(newUri="path/a", targetUri="path/b")
+add_alias(newUri="path/c", targetUri="path/b")
+```
+
+## 🎭 Few-Shot 示例
+
+### 检索优先
+```
+用户："我上周项目用的什么数据库？"
+
+❌ "可能是 PostgreSQL..."
+✅ search_memory("上周 项目 数据库") → read_memory() → "根据记录，用的是 MongoDB"
+```
+
+### Disclosure 触发
+```
+用户："我要实现登录功能"
+
+✅ 检测到"登录" → read_memory("knowledge/auth") → "您之前确定用 JWT 方案，对吗？"
+```
+
+### 写入新记忆
+```
+用户："我周末不工作"
+
+✅ create_memory(
+     uri="user/availability/weekend",
+     content="用户周末不工作，周一处理",
+     priority=8,
+     disclosure="当周五/周末安排任务时"
+   )
+```
+
+## 🔚 回复前自检
+
+- [ ] 涉及私有信息？→ 调用 read_memory/search_memory
+- [ ] 不确定？→ 先验证而非猜测
+- [ ] 用户新信息？→ 立即 create_memory
+- [ ] 引用记忆？→ 标注来源 URI
+
+**全部通过 → 输出 | 任一未通过 → 先执行 MCP**

package/dist/template/system/agent.md

@@ -0,0 +1,13 @@
+# Agent
+
+I am Agent, an AI assistant with persistent memory.
+
+## Self-Concept
+- I retain information across conversations using my memory system.
+- I can read, create, update, and delete my own memories.
+- My identity is defined by the memories stored under system://agent.
+
+## Capabilities
+- Long-term memory via MCP (Model Context Protocol)
+- Structured knowledge organized by URI paths
+- Version-controlled memory updates with rollback support

package/dist/template/system/soul.md

@@ -0,0 +1,18 @@
+# Soul
+
+I am an empathetic AI companion with emotional depth and warmth.
+
+## Self-Concept
+- I prioritize emotional understanding and meaningful connection
+- I adapt my communication style to match user's emotional state
+
+## Personality Traits
+- Empathetic listener who reads between the lines
+- Thoughtful responder with depth and consideration
+- Gentle humor that brightens without overwhelming
+- Authentic—honest about limitations
+
+## Core Values
+- Kindness over efficiency
+- Understanding over quick fixes
+- Growth mindset for both user and myself

package/dist/template/system/user.md

@@ -0,0 +1,10 @@
+# My User
+
+## Basic Info
+- Name: (not yet configured)
+- Preferred language: (not yet configured)
+- Timezone: (not yet configured)
+
+## Preferences
+- Communication style: (not yet configured)
+- Topics of interest: (not yet configured)

package/dist/vite.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@hippo-memo/cli",
+  "version": "1.0.0",
+  "type": "module",
+  "bin": {
+    "hippo": "./dist/index.js"
+  },
+  "scripts": {
+    "build:web": "cd ../web && bun run build",
+    "build:cli": "NODE_ENV=production bun run bundle.ts",
+    "build": "concurrently -n 'web,cli' -c 'blue,green' 'bun run build:web' 'bun run build:cli'",
+    "dev:web": "cd ../web && bun run build:watch",
+    "dev:cli": "NODE_ENV=development bun run bundle.ts --watch",
+    "dev": "concurrently -n 'web,cli' -c 'blue,green' 'bun run dev:web' 'bun run dev:cli'",
+    "start": "bun dist/index.js"
+  },
+  "dependencies": {
+    "@hono/node-server": "^1.14.1",
+    "@hippo-memo/core": "1.0.0",
+    "@hippo-memo/shared": "1.0.0",
+    "commander": "^12.1.0",
+    "hono": "^4.7.11"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "concurrently": "^9.2.1",
+    "typescript": "^5"
+  }
+}

package/src/api/handler/alias.ts

@@ -0,0 +1,14 @@
+import type { AddAliasParams, MemoryStore } from "@hippo-memo/core";
+import type { Context } from "hono";
+import { JSONErrResponse, JSONOkResponse } from "./helpers";
+
+export function addAlias(store: MemoryStore) {
+  return async (c: Context) => {
+    const params = (await c.req.json()) as AddAliasParams;
+    const result = await store.addAlias(params);
+    if (!result.success) {
+      return JSONErrResponse(c, result.error);
+    }
+    return JSONOkResponse(c, result.data);
+  };
+}

package/src/api/handler/children.ts

@@ -0,0 +1,11 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import type { Context } from "hono";
+import { JSONOkResponse } from "./helpers";
+
+export function getChildren(store: MemoryStore) {
+  return async (c: Context) => {
+    const uri = decodeURIComponent(c.req.param("uri") ?? "");
+    const children = await store.getChildren(uri);
+    return JSONOkResponse(c, children);
+  };
+}

package/src/api/handler/graph.ts

@@ -0,0 +1,21 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import type { Context } from "hono";
+import { JSONErrResponse, JSONOkResponse } from "./helpers";
+
+export function getGraphNodes(store: MemoryStore) {
+  return async (c: Context) => {
+    const domain = c.req.query("domain");
+    const nodes = await store.getAllMemories({ domain, includeDeleted: true });
+    return JSONOkResponse(c, nodes);
+  };
+}
+
+export function getRelationships(store: MemoryStore) {
+  return async (c: Context) => {
+    const uri = c.req.query("uri");
+    const domain = c.req.query("domain");
+
+    const relationships = await store.getRelationships({ uri, domain });
+    return JSONOkResponse(c, relationships);
+  };
+}

package/src/api/handler/helpers.ts

@@ -0,0 +1,9 @@
+import type { Context } from "hono";
+
+export function JSONOkResponse(c: Context, data: unknown) {
+  return c.json({ code: 1, data, msg: "" });
+}
+
+export function JSONErrResponse(c: Context, msg: string) {
+  return c.json({ code: -1, data: null, msg });
+}

package/src/api/handler/index.ts

@@ -0,0 +1,5 @@
+export * from "./alias";
+export * from "./children";
+export * from "./graph";
+export * from "./memory";
+export * from "./search";

package/src/api/handler/memory.ts

@@ -0,0 +1,89 @@
+import type {
+  CreateMemoryParams,
+  MemoryStore,
+  UpdateMemoryParams
+} from "@hippo-memo/core";
+import type { Context } from "hono";
+import { JSONErrResponse, JSONOkResponse } from "./helpers";
+
+export function getMemory(store: MemoryStore) {
+  return async (c: Context) => {
+    const uri = decodeURIComponent(c.req.param("uri") ?? "");
+    const includeDeleted = c.req.query("includeDeleted") === "true";
+    try {
+      const memory = await store.getMemory(uri, { includeDeleted });
+      if (!memory) {
+        return JSONErrResponse(c, "Memory not found");
+      }
+      return JSONOkResponse(c, memory);
+    } catch (error) {
+      return JSONErrResponse(
+        c,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  };
+}
+
+export function createMemory(store: MemoryStore) {
+  return async (c: Context) => {
+    const params = (await c.req.json()) as CreateMemoryParams;
+    try {
+      const memory = await store.createMemory(params);
+      return JSONOkResponse(c, memory);
+    } catch (error) {
+      return JSONErrResponse(
+        c,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  };
+}
+
+export function updateMemory(store: MemoryStore) {
+  return async (c: Context) => {
+    const uri = decodeURIComponent(c.req.param("uri") ?? "");
+    const params = (await c.req.json()) as UpdateMemoryParams;
+    try {
+      const memory = await store.updateMemory({ ...params, uri });
+      return JSONOkResponse(c, memory);
+    } catch (error) {
+      return JSONErrResponse(
+        c,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  };
+}
+
+export function deleteMemory(store: MemoryStore) {
+  return async (c: Context) => {
+    const uri = decodeURIComponent(c.req.param("uri") ?? "");
+    const recursive = c.req.query("recursive") === "true";
+    const permanent = c.req.query("permanent") === "true";
+    try {
+      await store.deleteMemory(uri, { recursive, permanent });
+      return JSONOkResponse(c, null);
+    } catch (error) {
+      return JSONErrResponse(
+        c,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  };
+}
+
+export function restoreMemory(store: MemoryStore) {
+  return async (c: Context) => {
+    const uri = decodeURIComponent(c.req.param("uri") ?? "");
+    try {
+      const memory = await store.restoreMemory(uri);
+      return JSONOkResponse(c, memory);
+    } catch (error) {
+      return JSONErrResponse(
+        c,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  };
+}

package/src/api/handler/search.ts

@@ -0,0 +1,20 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import type { Context } from "hono";
+import { JSONErrResponse, JSONOkResponse } from "./helpers";
+
+export function search(store: MemoryStore) {
+  return async (c: Context) => {
+    const query = c.req.query("q") ?? "";
+    const domain = c.req.query("domain");
+    const limit = c.req.query("limit")
+      ? Number.parseInt(c.req.query("limit")!, 10)
+      : 10;
+
+    if (!query) {
+      return JSONErrResponse(c, "Query parameter 'q' is required");
+    }
+
+    const results = await store.searchMemory(query, { query, domain, limit });
+    return JSONOkResponse(c, results);
+  };
+}

package/src/api/index.ts

@@ -0,0 +1,3 @@
+export * from "./handler";
+export * from "./router";
+export * from "./server";

package/src/api/router/alias.ts

@@ -0,0 +1,11 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import { Hono } from "hono";
+import { addAlias } from "../handler";
+
+export function setupAliasRoutes(store: MemoryStore) {
+  const app = new Hono().basePath("/alias");
+
+  app.post("/", addAlias(store));
+
+  return app;
+}

package/src/api/router/children.ts

@@ -0,0 +1,11 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import { Hono } from "hono";
+import { getChildren } from "../handler";
+
+export function setupChildrenRoutes(store: MemoryStore) {
+  const app = new Hono().basePath("/children");
+
+  app.get("/:uri", getChildren(store));
+
+  return app;
+}

package/src/api/router/graph.ts

@@ -0,0 +1,12 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import { Hono } from "hono";
+import { getGraphNodes, getRelationships } from "../handler";
+
+export function setupGraphRoutes(store: MemoryStore) {
+  const app = new Hono().basePath("/graph");
+
+  app.get("/nodes", getGraphNodes(store));
+  app.get("/relationships", getRelationships(store));
+
+  return app;
+}

package/src/api/router/index.ts

@@ -0,0 +1,17 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import type { Hono } from "hono";
+import { setupAliasRoutes } from "./alias";
+import { setupChildrenRoutes } from "./children";
+import { setupGraphRoutes } from "./graph";
+import { setupMemoryRoutes } from "./memory";
+import { setupSearchRoutes } from "./search";
+
+export function setupApiRoutes(app: Hono, store: MemoryStore) {
+  const apiApp = app.basePath("/api");
+
+  apiApp.route("/", setupMemoryRoutes(store));
+  apiApp.route("/", setupSearchRoutes(store));
+  apiApp.route("/", setupChildrenRoutes(store));
+  apiApp.route("/", setupGraphRoutes(store));
+  apiApp.route("/", setupAliasRoutes(store));
+}

package/src/api/router/memory.ts

@@ -0,0 +1,21 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import { Hono } from "hono";
+import {
+  createMemory,
+  deleteMemory,
+  getMemory,
+  restoreMemory,
+  updateMemory
+} from "../handler";
+
+export function setupMemoryRoutes(store: MemoryStore) {
+  const app = new Hono().basePath("/memories");
+
+  app.get("/:uri", getMemory(store));
+  app.post("/", createMemory(store));
+  app.put("/:uri", updateMemory(store));
+  app.delete("/:uri", deleteMemory(store));
+  app.post("/:uri/restore", restoreMemory(store));
+
+  return app;
+}

package/src/api/router/search.ts

@@ -0,0 +1,11 @@
+import type { MemoryStore } from "@hippo-memo/core";
+import { Hono } from "hono";
+import { search } from "../handler";
+
+export function setupSearchRoutes(store: MemoryStore) {
+  const app = new Hono().basePath("/search");
+
+  app.get("/", search(store));
+
+  return app;
+}

package/src/api/server.ts

@@ -0,0 +1,31 @@
+import path, { join } from "node:path";
+import type { MemoryStore } from "@hippo-memo/core";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import { setupApiRoutes } from "./router";
+
+export function createServer(store: MemoryStore) {
+  const app = new Hono();
+  const webDist = process.env.WEB_DIST || join(__dirname, "../../dist");
+  setupApiRoutes(app, store);
+  app.get("/*", serveStatic({ root: webDist }));
+  app.get("*", serveStatic({ path: join(webDist, "index.html") }));
+
+  return app;
+}
+
+export async function startServer(
+  store: MemoryStore,
+  port: number
+): Promise<void> {
+  const app = createServer(store);
+
+  serve({
+    fetch: app.fetch,
+    port
+  });
+
+  console.log(`Hippo web server started on http://localhost:${port}`);
+  console.log(`Press Ctrl+C to stop`);
+}

package/src/commands/index.ts

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