@clawdactual/chitin 0.1.4 → 0.1.6

package/README.md

@@ -96,30 +96,46 @@ chitin review          # (coming soon)
 chitin reflect --clear # process pending reflections
 ```
 
-**Integration with OpenClaw/Clawdbot:**
-
-1. Create the hook directory in your workspace:
-   ```
-   ~/clawd/hooks/chitin/
-   ├── HOOK.md      # metadata + events
-   └── handler.js   # bootstrap injection + reflection queuing
-   ```
-
-2. `HOOK.md` registers for events:
-   ```yaml
-   metadata:
-     openclaw:
-       events: ["agent:bootstrap", "command:new", "command:reset"]
-   ```
-
-3. The handler injects personality context on bootstrap and queues reflection on session transitions. See the [hook source](hooks/chitin/) for the full implementation.
-
-4. Enable in your gateway config:
-   ```yaml
-   hooks:
-     internal:
-       enabled: true
-   ```
+**Integration with OpenClaw / ClawdBot:**
+
+The Chitin hook ships with the package and works with both OpenClaw and ClawdBot (legacy).
+
+**Install from npm:**
+```bash
+openclaw hooks install @clawdactual/chitin
+openclaw hooks enable chitin
+```
+
+**Install from local clone:**
+```bash
+openclaw hooks install ./
+openclaw hooks enable chitin
+```
+
+Then restart your gateway. The hook handles:
+- **agent:bootstrap** — injects PERSONALITY.md with your top insights
+- **command:new / command:reset** — queues reflection markers for the next heartbeat
+
+See the [hook source](hooks/chitin/) for the full implementation.
+
+<details>
+<summary>Manual setup (alternative)</summary>
+
+If you prefer manual installation, copy the hook files into your workspace:
+
+```
+~/clawd/hooks/chitin/
+├── HOOK.md      # metadata + events
+└── handler.js   # bootstrap injection + reflection queuing
+```
+
+Then enable hooks in your gateway config:
+```yaml
+hooks:
+  internal:
+    enabled: true
+```
+</details>
 
 **Standalone (any agent framework):**
 ```bash

package/hooks/chitin/HOOK.md

@@ -0,0 +1,27 @@
+---
+name: chitin
+description: "Personality persistence layer — injects structured behavioral insights into sessions and queues reflection on session transitions"
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🦞",
+        "events": ["agent:bootstrap", "command:new", "command:reset"],
+      },
+    "clawdbot":
+      {
+        "emoji": "🦞",
+        "events": ["agent:bootstrap", "command:new", "command:reset"],
+      },
+  }
+---
+
+# Chitin Hook
+
+## Bootstrap (agent:bootstrap)
+Injects personality context from the Chitin insight store into every session.
+Runs `chitin retrieve` with session context, adds output as synthetic `PERSONALITY.md`.
+
+## Session Reset (command:new, command:reset)
+Queues a personality reflection marker so the next heartbeat knows to
+extract and persist new insights learned during the ended session.

package/hooks/chitin/handler.js

@@ -0,0 +1,156 @@
+/**
+ * Chitin — Personality persistence hook for OpenClaw
+ * 
+ * Two responsibilities:
+ * 1. On agent:bootstrap — inject personality context into sessions
+ * 2. On command:new/reset — trigger reflection to capture new insights
+ */
+
+import { execSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import os from "node:os";
+
+const DB_PATH = path.join(os.homedir(), ".config", "chitin", "insights.db");
+const CHITIN_DIR = path.join(os.homedir(), "Personal", "chitin");
+const CHITIN_DIST = path.join(CHITIN_DIR, "dist", "index.js");
+const DEFAULT_BUDGET = 2000;
+const DEBUG = !!process.env.CHITIN_DEBUG;
+
+function log(...args) {
+  if (DEBUG) console.error("[chitin]", ...args);
+}
+
+// ──────────────────────────────────────────────
+// Bootstrap: inject personality context
+// ──────────────────────────────────────────────
+
+function handleBootstrap(event) {
+  const context = event.context;
+  if (!context?.bootstrapFiles || !Array.isArray(context.bootstrapFiles)) return;
+  if (!fs.existsSync(DB_PATH)) return;
+
+  const query = buildQueryFromContext(context, event.sessionKey || "unknown");
+  if (!query) return;
+
+  try {
+    const result = runChitin(
+      `retrieve --query "${escapeShell(query)}" --budget ${DEFAULT_BUDGET} --format compact`
+    );
+
+    if (!result || result.includes("No insights stored")) return;
+
+    context.bootstrapFiles.push({
+      name: "PERSONALITY.md",
+      content: [
+        "# Personality Context (Chitin)",
+        "",
+        "These are your learned behavioral patterns and insights.",
+        "They persist across sessions. You can update them with `chitin contribute`.",
+        "",
+        result,
+      ].join("\n"),
+      missing: false,
+      source: "chitin-hook",
+    });
+
+    log(`Injected personality context (${result.length} chars) for ${event.sessionKey}`);
+  } catch (err) {
+    log(`Bootstrap error: ${err.message || err}`);
+  }
+}
+
+// ──────────────────────────────────────────────
+// Session reset: trigger reflection
+// ──────────────────────────────────────────────
+
+function handleSessionReset(event) {
+  // Push a reflection summary as a message that gets delivered before reset
+  // This tells the user (and any observers) that insights were captured
+  // The actual insight contribution happens via the reflection cron/heartbeat
+  // because we don't have LLM access in hooks to extract insights intelligently.
+  
+  // What we CAN do: record that a session ended, so the next heartbeat
+  // knows to do a reflection pass.
+  try {
+    const markerPath = path.join(os.homedir(), ".config", "chitin", "pending-reflection.json");
+    const marker = {
+      sessionKey: event.sessionKey || "unknown",
+      timestamp: new Date().toISOString(),
+      reason: event.action, // "new" or "reset"
+    };
+
+    // Append to pending reflections (array)
+    let pending = [];
+    if (fs.existsSync(markerPath)) {
+      try {
+        pending = JSON.parse(fs.readFileSync(markerPath, "utf-8"));
+        if (!Array.isArray(pending)) pending = [];
+      } catch { pending = []; }
+    }
+    pending.push(marker);
+    
+    // Keep only last 10
+    if (pending.length > 10) pending = pending.slice(-10);
+    
+    fs.writeFileSync(markerPath, JSON.stringify(pending, null, 2));
+    log(`Queued reflection for session ${event.sessionKey} (${event.action})`);
+  } catch (err) {
+    log(`Reset handler error: ${err.message || err}`);
+  }
+}
+
+// ──────────────────────────────────────────────
+// Main handler
+// ──────────────────────────────────────────────
+
+export default async function handler(event) {
+  if (event.type === "agent" && event.action === "bootstrap") {
+    handleBootstrap(event);
+    return;
+  }
+
+  if (event.type === "command" && (event.action === "new" || event.action === "reset")) {
+    handleSessionReset(event);
+    return;
+  }
+}
+
+// ──────────────────────────────────────────────
+// Utilities
+// ──────────────────────────────────────────────
+
+function runChitin(args) {
+  // Use compiled dist if available (much faster than npx tsx)
+  const useCompiled = fs.existsSync(CHITIN_DIST);
+  const command = useCompiled
+    ? `node "${CHITIN_DIST}" --db "${DB_PATH}" ${args}`
+    : `npx tsx "${path.join(CHITIN_DIR, "src", "index.ts")}" --db "${DB_PATH}" ${args}`;
+
+  log(`Running chitin via ${useCompiled ? "compiled dist" : "tsx fallback"}`);
+
+  return execSync(command, {
+    cwd: CHITIN_DIR,
+    encoding: "utf-8",
+    timeout: useCompiled ? 3000 : 5000,
+    stdio: ["pipe", "pipe", "pipe"],
+  }).trim();
+}
+
+function buildQueryFromContext(context, sessionKey) {
+  const parts = [];
+  if (context.agentId) parts.push(`agent: ${context.agentId}`);
+
+  if (sessionKey.includes("telegram")) parts.push("telegram chat");
+  else if (sessionKey.includes("discord")) parts.push("discord group chat");
+  else if (sessionKey.includes("slack")) parts.push("slack work chat");
+  else if (sessionKey.includes("webchat")) parts.push("webchat direct conversation");
+  else if (sessionKey.includes("subagent")) parts.push("sub-agent task execution");
+
+  if (parts.length === 0) parts.push("general assistant session");
+  return parts.join(", ");
+}
+
+function escapeShell(str) {
+  return str.replace(/"/g, '\\"').replace(/\$/g, "\\$").replace(/`/g, "\\`");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawdactual/chitin",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Personality persistence layer for AI agents. Structured insights about how you think, not what you remember.",
   "type": "module",
   "main": "dist/index.js",
@@ -9,10 +9,16 @@
   },
   "files": [
     "dist",
+    "hooks",
     "seed.json",
     "LICENSE",
     "README.md"
   ],
+  "openclaw": {
+    "hooks": [
+      "./hooks/chitin"
+    ]
+  },
   "scripts": {
     "build": "tsc",
     "prepare": "npm run build",
@@ -29,6 +35,7 @@
     "chitin",
     "carapace",
     "clawdbot",
+    "openclaw",
     "mcp"
   ],
   "author": "ClawdActual",