hippo-memory 0.6.0 → 0.6.1

package/dist/mcp/server.js

@@ -299,7 +299,7 @@ function handleRequest(req) {
                 result: {
                     protocolVersion: '2024-11-05',
                     capabilities: { tools: {} },
-                    serverInfo: { name: 'hippo-memory', version: '0.6.0' },
+                    serverInfo: { name: 'hippo-memory', version: '0.6.1' },
                 },
             };
         case 'notifications/initialized':

package/extensions/openclaw-plugin/README.md

@@ -0,0 +1,80 @@
+# Hippo Memory - OpenClaw Plugin
+
+Biologically-inspired memory for OpenClaw agents. Memories decay by default, retrieval strengthens them, errors stick longer, and sleep consolidation compresses episodes into patterns.
+
+## Install
+
+```bash
+# Copy plugin to OpenClaw extensions
+cp -r extensions/openclaw-plugin ~/.openclaw/extensions/hippo-memory
+
+# Or link for development
+openclaw plugins install -l ./extensions/openclaw-plugin
+```
+
+## Configure
+
+Add to `openclaw.json`:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "hippo-memory": {
+        enabled: true,
+        config: {
+          budget: 1500,          // token budget for context injection
+          autoContext: true,     // auto-inject memory at session start
+          autoLearn: true,       // auto-capture errors
+          autoSleep: false,      // auto-consolidate after heavy sessions
+          framing: "observe"     // observe | suggest | assert
+          // root: "C:/path/to/workspace/.hippo" // optional override
+        }
+      }
+    }
+  }
+}
+```
+
+Restart the gateway after enabling.
+
+## What It Does
+
+### Auto-context injection
+
+At every session start, hippo automatically injects relevant project memories into the system prompt. No manual `hippo context` needed. The agent sees memories from past sessions without any explicit tool calls.
+
+By default the plugin runs Hippo from the current agent workspace, so Hippo uses that
+workspace's local `.hippo/` store and automatically merges any global `~/.hippo/`
+store during `recall` / `context`. You only need `config.root` if you want to
+override workspace auto-detection.
+
+### Agent tools
+
+The plugin registers these tools for the agent to call:
+
+| Tool | Description |
+|------|-------------|
+| `hippo_recall` | Search memories by topic (always available) |
+| `hippo_remember` | Store a new memory (always available) |
+| `hippo_outcome` | Report if recalled memories helped (always available) |
+| `hippo_status` | Check memory health (optional, enable in tools.allow) |
+| `hippo_context` | Smart context from git state (optional, enable in tools.allow) |
+
+### How it differs from claude-mem
+
+| | Hippo | claude-mem |
+|---|---|---|
+| Decay | Yes, 7-day half-life | No, saves everything |
+| Retrieval strengthening | Yes | No |
+| Outcome feedback | Yes | No |
+| Cross-tool | Claude Code, Codex, Cursor, OpenClaw | Claude Code only |
+| API calls | Zero | Uses Claude API for compression |
+| Token cost | ~1500 tokens/session (configurable) | Variable |
+| Memecoin | No | Yes ($CMEM on Solana) |
+
+## Requirements
+
+- `hippo-memory` CLI installed globally: `npm install -g hippo-memory`
+- A `.hippo/` directory in your workspace: `hippo init`
+- Optional shared global store: `hippo init --global`

package/extensions/openclaw-plugin/index.ts

@@ -0,0 +1,370 @@
+/**
+ * Hippo Memory - OpenClaw Plugin
+ *
+ * Auto-injects relevant memory context at session start,
+ * captures errors during sessions, and runs consolidation.
+ *
+ * Config lives under plugins.entries.hippo-memory.config
+ */
+
+import { execSync } from 'child_process';
+import { existsSync } from 'fs';
+import { basename, dirname, join } from 'path';
+
+interface HippoConfig {
+  budget?: number;
+  autoContext?: boolean;
+  autoLearn?: boolean;
+  autoSleep?: boolean;
+  framing?: 'observe' | 'suggest' | 'assert';
+  root?: string;
+}
+
+type HippoRuntimeContext = {
+  workspaceDir?: string;
+  agentId?: string;
+  sessionId?: string;
+  sessionKey?: string;
+};
+
+const AUTO_SLEEP_SESSION_THRESHOLD = 10;
+const sessionMemoryCounts = new Map<string, number>();
+
+function getConfig(api: any): HippoConfig {
+  try {
+    const entries = api.config?.plugins?.entries?.['hippo-memory'];
+    return entries?.config ?? {};
+  } catch {
+    return {};
+  }
+}
+
+function findHippoRoot(workspace?: string, configRoot?: string): string | null {
+  if (configRoot && existsSync(configRoot)) return configRoot;
+
+  const candidates = [
+    workspace ? join(workspace, '.hippo') : null,
+    process.env.HIPPO_ROOT,
+    join(process.env.USERPROFILE || process.env.HOME || '', '.hippo'),
+  ].filter(Boolean) as string[];
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+function getAgentWorkspace(api: any, agentId?: string): string | undefined {
+  try {
+    const agents = api.config?.agents;
+    const list = Array.isArray(agents?.list) ? agents.list : [];
+
+    if (agentId) {
+      const match = list.find((agent: any) => agent?.id === agentId);
+      if (typeof match?.workspace === 'string' && match.workspace) return match.workspace;
+    }
+
+    const defaultAgent = list.find((agent: any) => agent?.default);
+    if (typeof defaultAgent?.workspace === 'string' && defaultAgent.workspace) {
+      return defaultAgent.workspace;
+    }
+
+    const fallback = agents?.defaults?.workspace;
+    return typeof fallback === 'string' && fallback ? fallback : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function resolveHippoCwd(workspace?: string, configRoot?: string): string {
+  const hippoRoot = findHippoRoot(workspace, configRoot);
+  if (!hippoRoot) return workspace || process.cwd();
+  return basename(hippoRoot).toLowerCase() === '.hippo' ? dirname(hippoRoot) : hippoRoot;
+}
+
+function resolveHippoCwdFromContext(api: any, ctx: HippoRuntimeContext, configRoot?: string): string {
+  const workspace = ctx.workspaceDir ?? getAgentWorkspace(api, ctx.agentId);
+  return resolveHippoCwd(workspace, configRoot);
+}
+
+function getSessionIdentity(ctx: Pick<HippoRuntimeContext, 'sessionId' | 'sessionKey' | 'agentId'>): string | undefined {
+  return ctx.sessionId ?? ctx.sessionKey ?? ctx.agentId;
+}
+
+function recordSessionMemory(ctx: Pick<HippoRuntimeContext, 'sessionId' | 'sessionKey' | 'agentId'>): void {
+  const key = getSessionIdentity(ctx);
+  if (!key) return;
+  sessionMemoryCounts.set(key, (sessionMemoryCounts.get(key) ?? 0) + 1);
+}
+
+function consumeSessionMemoryCount(
+  ctx: Pick<HippoRuntimeContext, 'sessionId' | 'sessionKey' | 'agentId'>,
+): number {
+  const key = getSessionIdentity(ctx);
+  if (!key) return 0;
+  const count = sessionMemoryCounts.get(key) ?? 0;
+  sessionMemoryCounts.delete(key);
+  return count;
+}
+
+function sanitizeTag(tag?: string): string | undefined {
+  if (!tag) return undefined;
+  const normalized = tag
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 30);
+  return normalized || undefined;
+}
+
+function formatToolErrorMemory(toolName: string, error: string): string {
+  const normalized = error.replace(/\s+/g, ' ').trim();
+  const truncated = normalized.slice(0, 500);
+  const suffix = normalized.length > truncated.length ? ' [truncated]' : '';
+  return `Tool '${toolName}' failed: ${truncated}${suffix}`;
+}
+
+function hippoRememberSucceeded(result: string): boolean {
+  return result.includes('Remembered [');
+}
+
+function runHippo(args: string, cwd?: string): string {
+  try {
+    const result = execSync(`hippo ${args}`, {
+      cwd: cwd || process.cwd(),
+      timeout: 30000,
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    return result.trim();
+  } catch (err: any) {
+    return err.stdout?.trim() || err.message || 'hippo command failed';
+  }
+}
+
+export default function register(api: any) {
+  const logger = api.logger ?? console;
+
+  // --- Tool: hippo_recall ---
+  api.registerTool((ctx: HippoRuntimeContext) => ({
+    name: 'hippo_recall',
+    description:
+      'Retrieve relevant memories from the project memory store. Returns memories ranked by relevance, strength, and recency within the token budget. Use at session start or when you need context about a topic.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'What to search for in memory (natural language)',
+        },
+        budget: {
+          type: 'number',
+          description: 'Max tokens to return (default: 1500)',
+        },
+      },
+      required: ['query'],
+    },
+    async execute(_id: string, params: { query: string; budget?: number }) {
+      const cfg = getConfig(api);
+      const budget = params.budget ?? cfg.budget ?? 1500;
+      const framing = cfg.framing ?? 'observe';
+      const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+      const result = runHippo(
+        `recall "${params.query.replace(/"/g, '\\"')}" --budget ${budget} --framing ${framing}`,
+        hippoCwd,
+      );
+      return { content: [{ type: 'text', text: result || 'No relevant memories found.' }] };
+    },
+  }));
+
+  // --- Tool: hippo_remember ---
+  api.registerTool((ctx: HippoRuntimeContext) => ({
+    name: 'hippo_remember',
+    description:
+      'Store a new memory. Use when you learn something non-obvious, hit an error, or discover a useful pattern. Memories decay over time unless retrieved. Errors get 2x half-life.',
+    parameters: {
+      type: 'object',
+      properties: {
+        text: {
+          type: 'string',
+          description: 'The memory to store (1-2 sentences, specific and concrete)',
+        },
+        error: {
+          type: 'boolean',
+          description: 'Mark as error memory (doubles half-life)',
+        },
+        pin: {
+          type: 'boolean',
+          description: 'Pin memory (never decays)',
+        },
+        tag: {
+          type: 'string',
+          description: 'Optional tag for categorization',
+        },
+      },
+      required: ['text'],
+    },
+    async execute(
+      _id: string,
+      params: { text: string; error?: boolean; pin?: boolean; tag?: string },
+    ) {
+      const cfg = getConfig(api);
+      const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+      let args = `remember "${params.text.replace(/"/g, '\\"')}"`;
+      if (params.error) args += ' --error';
+      if (params.pin) args += ' --pin';
+      if (params.tag) args += ` --tag ${params.tag}`;
+      const result = runHippo(args, hippoCwd);
+      if (hippoRememberSucceeded(result)) {
+        recordSessionMemory(ctx);
+      }
+      return { content: [{ type: 'text', text: result || 'Memory stored.' }] };
+    },
+  }));
+
+  // --- Tool: hippo_outcome ---
+  api.registerTool((ctx: HippoRuntimeContext) => ({
+    name: 'hippo_outcome',
+    description:
+      'Report whether recalled memories were useful. Strengthens good memories (+5 days half-life) and weakens bad ones (-3 days). Call after completing work.',
+    parameters: {
+      type: 'object',
+      properties: {
+        good: {
+          type: 'boolean',
+          description: 'true = memories helped, false = memories were irrelevant',
+        },
+      },
+      required: ['good'],
+    },
+    async execute(_id: string, params: { good: boolean }) {
+      const cfg = getConfig(api);
+      const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+      const flag = params.good ? '--good' : '--bad';
+      const result = runHippo(`outcome ${flag}`, hippoCwd);
+      return { content: [{ type: 'text', text: result || 'Outcome recorded.' }] };
+    },
+  }));
+
+  // --- Tool: hippo_status ---
+  api.registerTool(
+    (ctx: HippoRuntimeContext) => ({
+      name: 'hippo_status',
+      description:
+        'Check memory health: counts, strengths, at-risk memories, last consolidation time.',
+      parameters: {
+        type: 'object',
+        properties: {},
+      },
+      async execute() {
+        const cfg = getConfig(api);
+        const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+        const result = runHippo('status', hippoCwd);
+        return { content: [{ type: 'text', text: result || 'No hippo store found.' }] };
+      },
+    }),
+    { optional: true },
+  );
+
+  // --- Tool: hippo_context ---
+  api.registerTool(
+    (ctx: HippoRuntimeContext) => ({
+      name: 'hippo_context',
+      description:
+        'Smart context injection: auto-detects current task from git state and returns relevant memories. Use at the start of any session.',
+      parameters: {
+        type: 'object',
+        properties: {
+          budget: {
+            type: 'number',
+            description: 'Max tokens (default: 1500)',
+          },
+        },
+      },
+      async execute(_id: string, params: { budget?: number }) {
+        const cfg = getConfig(api);
+        const budget = params.budget ?? cfg.budget ?? 1500;
+        const framing = cfg.framing ?? 'observe';
+        const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+        const result = runHippo(
+          `context --auto --budget ${budget} --framing ${framing}`,
+          hippoCwd,
+        );
+        return { content: [{ type: 'text', text: result || 'No context available.' }] };
+      },
+    }),
+    { optional: true },
+  );
+
+  // --- Hook: auto-inject context at session start ---
+  api.on(
+    'before_prompt_build',
+    (_event: any, ctx: HippoRuntimeContext) => {
+      const cfg = getConfig(api);
+      if (cfg.autoContext === false) return {};
+
+      const budget = cfg.budget ?? 1500;
+      const framing = cfg.framing ?? 'observe';
+      const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+
+      try {
+        const context = runHippo(
+          `context --auto --budget ${budget} --framing ${framing}`,
+          hippoCwd,
+        );
+        if (context && context.length > 10 && !context.includes('No hippo store')) {
+          return {
+            appendSystemContext: `\n\n## Project Memory (Hippo)\n${context}`,
+          };
+        }
+      } catch (err) {
+        logger.debug?.('[hippo] context injection skipped:', err);
+      }
+      return {};
+    },
+    { priority: 5 },
+  );
+
+  api.on(
+    'after_tool_call',
+    (event: { toolName: string; error?: string }, ctx: HippoRuntimeContext) => {
+      const cfg = getConfig(api);
+      if (cfg.autoLearn === false) return;
+      if (!event.error?.trim()) return;
+      if (event.toolName.startsWith('hippo_')) return;
+
+      const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+      const toolTag = sanitizeTag(event.toolName);
+      let args =
+        `remember "${formatToolErrorMemory(event.toolName, event.error).replace(/"/g, '\\"')}"` +
+        ' --error --observed --tag openclaw';
+      if (toolTag) args += ` --tag ${toolTag}`;
+
+      const result = runHippo(args, hippoCwd);
+      if (hippoRememberSucceeded(result)) {
+        recordSessionMemory(ctx);
+      } else {
+        logger.debug?.(`[hippo] autoLearn skipped storing tool error: ${result}`);
+      }
+    },
+  );
+
+  api.on(
+    'session_end',
+    (_event: { sessionId: string; messageCount: number }, ctx: HippoRuntimeContext) => {
+      const cfg = getConfig(api);
+      const newMemories = consumeSessionMemoryCount(ctx);
+      if (!cfg.autoSleep || newMemories < AUTO_SLEEP_SESSION_THRESHOLD) return;
+
+      const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
+      const result = runHippo('sleep', hippoCwd);
+      logger.info?.(
+        `[hippo] autoSleep ran for session ${ctx.sessionId ?? ctx.sessionKey ?? 'unknown'} ` +
+          `after ${newMemories} new memories`,
+      );
+      logger.debug?.(`[hippo] autoSleep result: ${result}`);
+    },
+  );
+
+  logger.info?.('[hippo] Memory plugin registered (tools: hippo_recall, hippo_remember, hippo_outcome, hippo_status, hippo_context)');
+}

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -0,0 +1,46 @@
+{
+  "id": "hippo-memory",
+  "name": "Hippo Memory",
+  "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
+  "version": "0.4.1",
+
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "budget": {
+        "type": "number",
+        "description": "Default token budget for context injection (default: 1500)"
+      },
+      "autoContext": {
+        "type": "boolean",
+        "description": "Auto-inject hippo context at session start (default: true)"
+      },
+      "autoLearn": {
+        "type": "boolean",
+        "description": "Auto-capture errors during agent sessions (default: true)"
+      },
+      "autoSleep": {
+        "type": "boolean",
+        "description": "Run consolidation after sessions with 10+ new memories (default: false)"
+      },
+      "framing": {
+        "type": "string",
+        "enum": ["observe", "suggest", "assert"],
+        "description": "How memories are framed in context (default: observe)"
+      },
+      "root": {
+        "type": "string",
+        "description": "Custom .hippo directory path (default: auto-detect from workspace)"
+      }
+    }
+  },
+  "uiHints": {
+    "budget": { "label": "Token Budget", "placeholder": "1500" },
+    "autoContext": { "label": "Auto-inject Context" },
+    "autoLearn": { "label": "Auto-capture Errors" },
+    "autoSleep": { "label": "Auto-consolidate" },
+    "framing": { "label": "Memory Framing" },
+    "root": { "label": "Hippo Root Path", "placeholder": ".hippo/" }
+  }
+}

package/extensions/openclaw-plugin/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "hippo-memory",
+  "version": "0.4.1",
+  "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
+  "main": "index.ts",
+  "openclaw": {
+    "extensions": ["./index.ts"]
+  },
+  "peerDependencies": {
+    "hippo-memory": ">=0.4.0"
+  },
+  "license": "MIT"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Biologically-inspired memory system for AI agents. Decay by default, strength through use.",
   "type": "module",
   "main": "./dist/index.js",
@@ -12,7 +12,8 @@
   },
   "files": [
     "dist",
-    "bin"
+    "bin",
+    "extensions/openclaw-plugin"
   ],
   "scripts": {
     "build": "tsc",