wicked-brain 0.5.0 → 0.7.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "Digital brain as skills for AI coding CLIs — no vector DB, no embeddings, no infrastructure",
   "keywords": [
@@ -32,7 +32,7 @@
   },
   "dependencies": {
     "better-sqlite3": "^12.0.0",
-    "wicked-bus": "^1.0.0"
+    "wicked-bus": "^1.1.0"
   },
   "files": [
     "install.mjs",

package/server/bin/wicked-brain-server.mjs

@@ -7,6 +7,7 @@ import { FileWatcher } from "../lib/file-watcher.mjs";
 import { SqliteSearch } from "../lib/sqlite-search.mjs";
 import { LspClient } from "../lib/lsp-client.mjs";
 import { emitEvent, waitForBus } from "../lib/bus.mjs";
+import { startMemorySubscriber } from "../lib/memory-subscriber.mjs";
 
 // Parse args
 const args = argv.slice(2);
@@ -74,11 +75,17 @@ try {
 // LSP client — pass source path so language servers are rooted at the project, not the brain dir
 const lsp = new LspClient(brainPath, db, sourcePath);
 
+// Auto-memorize subscriber handle (set after bus init in server.listen callback)
+let memorySubscriber = null;
+
 // Graceful shutdown
 async function shutdown() {
   console.log("Shutting down...");
   try { unlinkSync(pidPath); } catch {}
   watcher.stop();
+  if (memorySubscriber) {
+    try { await memorySubscriber.stop(); } catch {}
+  }
   await lsp.shutdown();
   db.close();
   exit(0);
@@ -238,8 +245,15 @@ try {
 server.listen(port, async () => {
   console.log(`wicked-brain-server running on port ${port} (brain: ${brainId}, pid: ${pid})`);
   watcher.start();
-  await waitForBus();
+  const busReady = await waitForBus();
   emitEvent("wicked.server.started", "brain.system", {
     brain_id: brainId, port, pid,
   });
+  if (busReady) {
+    try {
+      memorySubscriber = await startMemorySubscriber({ brainPath, brainId, db });
+    } catch (err) {
+      console.error(`[memory-subscriber] failed to start: ${err.message}`);
+    }
+  }
 });

package/server/lib/bus.mjs

@@ -65,6 +65,16 @@ export function busAvailable() {
   return available;
 }
 
+/** Alias for busAvailable() — preferred name going forward. */
+export function isBusAvailable() {
+  return available;
+}
+
+/** Returns the open bus DB handle, or null if unavailable. Reuses the connection opened at init. */
+export function getBusDb() {
+  return available ? busDb : null;
+}
+
 /**
  * Wait for bus initialization to complete.
  * Only needed if you must know availability before the first emit.

package/server/lib/memory-promoter.mjs

@@ -0,0 +1,105 @@
+/**
+ * Promotion policy for auto-memorizing wicked.fact.extracted bus events.
+ *
+ * Pure function — no I/O, no side effects. Returns either a memory descriptor
+ * (frontmatter + content + safeName + contentHash) or a skip reason.
+ *
+ * @module lib/memory-promoter
+ */
+
+import { createHash } from "node:crypto";
+
+const IMPORTANCE_BY_TYPE = { decision: 7, discovery: 4 };
+const TTL_BY_TYPE = { decision: null, discovery: 14 };
+const ALLOWED_TYPES = new Set(["decision", "discovery"]);
+const MIN_CONTENT_LENGTH = 15;
+const MAX_TAGS = 15;
+
+/** Stable normalization for content hashing — collapses whitespace, lowercases. */
+export function computeContentHash(content) {
+  const normalized = String(content || "").trim().replace(/\s+/g, " ").toLowerCase();
+  return createHash("sha256").update(normalized).digest("hex");
+}
+
+/** Slugify text for filenames: lowercase, alnum + dashes, collapsed, trimmed, capped. */
+export function slugify(text, maxLen = 60) {
+  const slug = String(text || "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  return slug.slice(0, maxLen).replace(/-+$/g, "");
+}
+
+function tierFromImportance(importance) {
+  if (importance >= 7) return "semantic";
+  if (importance >= 4) return "episodic";
+  return "working";
+}
+
+/**
+ * Apply the auto-memorize promotion policy to a bus event.
+ * @param {object} event
+ * @returns {{memory: object|null, skip: boolean, reason?: string}}
+ */
+export function promoteFact(event) {
+  if (!event || event.event_type !== "wicked.fact.extracted") {
+    return { memory: null, skip: true, reason: "wrong event_type" };
+  }
+  const payload = event.payload || {};
+  const type = payload.type;
+  if (!ALLOWED_TYPES.has(type)) {
+    return { memory: null, skip: true, reason: `type ${type} not auto-promoted` };
+  }
+  const content = typeof payload.content === "string" ? payload.content : null;
+  if (!content) {
+    return { memory: null, skip: true, reason: "missing payload.content" };
+  }
+  const trimmed = content.trim();
+  if (trimmed.length < MIN_CONTENT_LENGTH) {
+    return { memory: null, skip: true, reason: "content too short" };
+  }
+
+  const importance = IMPORTANCE_BY_TYPE[type];
+  const tier = tierFromImportance(importance);
+  const ttlDays = TTL_BY_TYPE[type];
+  const contentHash = computeContentHash(trimmed);
+
+  const sourceDomain = event.domain || "unknown";
+  const source = `bus:${sourceDomain}`;
+
+  const emittedAt = event.emitted_at || Date.now();
+  const sessionOrigin = payload.session_id || new Date(emittedAt).toISOString();
+
+  const entityList = Array.isArray(payload.entities) ? payload.entities.map(String) : [];
+  // Tags = entities + the type label, deduped, capped at MAX_TAGS
+  const tagSet = new Set();
+  for (const e of entityList) {
+    if (e) tagSet.add(e);
+    if (tagSet.size >= MAX_TAGS) break;
+  }
+  if (tagSet.size < MAX_TAGS) tagSet.add(type);
+  const contains = Array.from(tagSet).slice(0, MAX_TAGS);
+
+  const frontmatter = {
+    type,
+    tier,
+    confidence: 0.3,
+    importance,
+    content_hash: contentHash,
+    source,
+    ttl_days: ttlDays,
+    session_origin: sessionOrigin,
+    contains,
+    entities: { systems: entityList, people: [] },
+    indexed_at: new Date().toISOString(),
+  };
+
+  const slugBase = slugify(trimmed.slice(0, 60));
+  const safeName = `${slugBase || "memory"}-${contentHash.slice(0, 8)}.md`;
+
+  return {
+    memory: { frontmatter, content: trimmed, safeName, contentHash },
+    skip: false,
+  };
+}

package/server/lib/memory-subscriber.mjs

@@ -0,0 +1,117 @@
+/**
+ * Auto-memorize subscriber: bridges wicked-bus fact events into brain memories.
+ *
+ * Subscribes to `wicked.fact.extracted` via wicked-bus durable cursors,
+ * runs each event through the promoter policy, dedups by content hash,
+ * and writes a memory file. The brain file watcher picks it up and indexes it.
+ *
+ * @module lib/memory-subscriber
+ */
+
+import { writeFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { getBusDb, isBusAvailable, emitEvent } from "./bus.mjs";
+import { promoteFact } from "./memory-promoter.mjs";
+
+/**
+ * Start the auto-memorize subscriber.
+ * Returns the subscription handle (with .stop()) or null if the bus is unavailable.
+ * Dynamic-imports wicked-bus so the server still loads when the package is absent
+ * (matches the graceful-degradation pattern used by bus.mjs).
+ *
+ * @param {object} opts
+ * @param {string} opts.brainPath  absolute brain directory
+ * @param {string} opts.brainId
+ * @param {object} opts.db         brain SqliteSearch instance (for findByContentHash)
+ */
+export async function startMemorySubscriber({ brainPath, brainId, db }) {
+  if (!isBusAvailable()) return null;
+  const busDb = getBusDb();
+  if (!busDb) return null;
+
+  let subscribe;
+  try {
+    ({ subscribe } = await import("wicked-bus"));
+  } catch {
+    return null;
+  }
+
+  const memoryDir = join(brainPath, "memory");
+
+  const sub = subscribe({
+    db: busDb,
+    plugin: "wicked-brain",
+    filter: "wicked.fact.extracted",
+    cursor_init: "latest",
+    pollIntervalMs: 15000,
+    maxRetries: 3,
+    backoffMs: [1000, 5000, 30000],
+    handler: async (event) => {
+      const result = promoteFact(event);
+      if (result.skip) return;
+
+      // Dedup by stable content_hash
+      const existing = db.findByContentHash(result.memory.contentHash);
+      if (existing) return;
+
+      const filePath = join(memoryDir, result.memory.safeName);
+      if (existsSync(filePath)) return; // filename collision — skip
+
+      const fileContent = renderMemoryFile(result.memory);
+      writeFileSync(filePath, fileContent, "utf-8");
+
+      emitEvent("wicked.memory.stored", "brain.memory", {
+        path: `memory/${result.memory.safeName}`,
+        type: result.memory.frontmatter.type,
+        tier: result.memory.frontmatter.tier,
+        source: result.memory.frontmatter.source,
+        brain_id: brainId,
+      });
+    },
+    onError: (err, event) => {
+      console.error(`[memory-subscriber] handler error on event ${event?.event_id}: ${err.message}`);
+    },
+    onDeadLetter: (event, reason) => {
+      console.error(`[memory-subscriber] dead-lettered event ${event?.event_id}: ${reason}`);
+      emitEvent("wicked.memory.dead_lettered", "brain.memory", {
+        event_id: event?.event_id,
+        reason,
+        brain_id: brainId,
+      });
+    },
+  });
+
+  return sub;
+}
+
+/**
+ * Render a memory descriptor as a markdown file with YAML-ish frontmatter.
+ * Minimal serializer — no YAML lib. Matches the format used by wicked-brain:memory.
+ */
+export function renderMemoryFile(memory) {
+  const fm = memory.frontmatter;
+  const lines = ["---"];
+  for (const [key, value] of Object.entries(fm)) {
+    if (value === null) { lines.push(`${key}: null`); continue; }
+    if (Array.isArray(value)) {
+      lines.push(`${key}:`);
+      for (const item of value) lines.push(`  - ${item}`);
+      continue;
+    }
+    if (typeof value === "object") {
+      lines.push(`${key}:`);
+      for (const [k, v] of Object.entries(value)) {
+        if (Array.isArray(v)) {
+          lines.push(`  ${k}: [${v.map(x => JSON.stringify(x)).join(", ")}]`);
+        } else {
+          lines.push(`  ${k}: ${JSON.stringify(v)}`);
+        }
+      }
+      continue;
+    }
+    if (typeof value === "string") { lines.push(`${key}: ${JSON.stringify(value)}`); continue; }
+    lines.push(`${key}: ${value}`);
+  }
+  lines.push("---", "", memory.content, "");
+  return lines.join("\n");
+}

package/server/lib/sqlite-search.mjs

@@ -59,7 +59,8 @@ export class SqliteSearch {
         content TEXT NOT NULL,
         frontmatter TEXT,
         brain_id TEXT NOT NULL,
-        indexed_at INTEGER NOT NULL
+        indexed_at INTEGER NOT NULL,
+        content_hash TEXT
       );
 
       CREATE VIRTUAL TABLE IF NOT EXISTS documents_fts USING fts5(
@@ -153,11 +154,29 @@ export class SqliteSearch {
       currentVersion = 2;
     }
 
+    // Migration 3: add content_hash column + index for memory dedup
+    if (currentVersion < 3) {
+      try { this.#db.prepare(`SELECT content_hash FROM documents LIMIT 0`).get(); } catch {
+        this.#db.exec(`ALTER TABLE documents ADD COLUMN content_hash TEXT`);
+      }
+      this.#db.exec(`CREATE INDEX IF NOT EXISTS idx_documents_content_hash ON documents(content_hash)`);
+      currentVersion = 3;
+    }
+
     // Persist the current version
     this.#db.exec(`DELETE FROM _schema_version`);
     this.#db.prepare(`INSERT INTO _schema_version (version) VALUES (?)`).run(currentVersion);
   }
 
+  /** Extract a single field value from a raw frontmatter string (no YAML dep). */
+  #extractFrontmatterField(frontmatterStr, fieldName) {
+    if (!frontmatterStr) return null;
+    const re = new RegExp(`^${fieldName}:\\s*(.+)$`, "m");
+    const m = frontmatterStr.match(re);
+    if (!m) return null;
+    return m[1].trim().replace(/^["']|["']$/g, "");
+  }
+
   /** Returns the current schema version number. */
   schemaVersion() {
     try {
@@ -180,16 +199,18 @@ export class SqliteSearch {
     const frontmatter = doc.frontmatter ?? SqliteSearch.#extractFrontmatter(content);
     const brainId = this.#brainId;
     const indexedAt = Date.now();
+    const contentHash = this.#extractFrontmatterField(frontmatter, "content_hash");
 
     const upsertDoc = this.#db.prepare(`
-      INSERT INTO documents (id, path, content, frontmatter, brain_id, indexed_at)
-      VALUES (?, ?, ?, ?, ?, ?)
+      INSERT INTO documents (id, path, content, frontmatter, brain_id, indexed_at, content_hash)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
       ON CONFLICT(id) DO UPDATE SET
         path = excluded.path,
         content = excluded.content,
         frontmatter = excluded.frontmatter,
         brain_id = excluded.brain_id,
-        indexed_at = excluded.indexed_at
+        indexed_at = excluded.indexed_at,
+        content_hash = excluded.content_hash
     `);
 
     const deleteFts = this.#db.prepare(`DELETE FROM documents_fts WHERE id = ?`);
@@ -205,7 +226,7 @@ export class SqliteSearch {
     `);
 
     const run = this.#db.transaction(() => {
-      upsertDoc.run(id, path, content, frontmatter, brainId, indexedAt);
+      upsertDoc.run(id, path, content, frontmatter, brainId, indexedAt, contentHash);
       deleteFts.run(id);
       insertFts.run(id, path, content, brainId);
       deleteLinks.run(id);
@@ -783,6 +804,18 @@ export class SqliteSearch {
     `).all(...sinceParams, limit);
   }
 
+  /**
+   * Find the first document with a matching content_hash, or null.
+   * Used by the auto-memorize subscriber for dedup.
+   */
+  findByContentHash(hash) {
+    if (!hash) return null;
+    const row = this.#db.prepare(`
+      SELECT id, path FROM documents WHERE content_hash = ? LIMIT 1
+    `).get(hash);
+    return row || null;
+  }
+
   close() {
     this.#db.close();
   }

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-brain-server",
-  "version": "0.5.0",
+  "version": "0.7.1",
   "type": "module",
   "description": "SQLite FTS5 search server for wicked-brain digital knowledge bases",
   "keywords": [

package/skills/wicked-brain-memory/SKILL.md

@@ -35,10 +35,12 @@ project root.
 
 - **mode** (required): `store` or `recall`
 - **content** (store mode): the memory content to store
-- **type** (store mode, optional): `decision`, `pattern`, `preference`, `gotcha`, or `discovery`. Auto-detected if omitted.
+- **type** (store mode, optional): `decision`, `pattern` (alias: `procedural`), `preference`, `gotcha`, or `discovery`. Auto-detected if omitted. `procedural` is an input alias only — storage frontmatter always writes `type: pattern`.
 - **ttl_days** (store mode, optional): number of days before this memory expires. Defaults by type.
+- **importance** (store mode, optional): `low`, `medium`, or `high`. Overrides the type default. Bands: low = 1-3, medium = 4-6, high = 7-10. Used to derive the initial tier (see Step 2b).
+- **tier** (store mode, optional): explicit tier override (`working`, `episodic`, `semantic`). Takes precedence over `importance`.
 - **query** (recall mode): search term for finding memories
-- **filter_type** (recall mode, optional): filter by memory type
+- **filter_type** (recall mode, optional): filter by memory type. `procedural` is normalized to `pattern`.
 - **filter_tier** (recall mode, optional): filter by tier (`working`, `episodic`, `semantic`)
 
 ## Store Mode
@@ -47,11 +49,15 @@ project root.
 
 If type is not provided, classify the content:
 - Contains "decided", "chose", "will use", "going with" → `decision`
-- Contains "pattern", "always", "tends to", "convention" → `pattern`
+- Contains "pattern", "always", "tends to", "convention" → `pattern` (if the caller explicitly passed `type: procedural`, normalize to `pattern` before continuing)
 - Contains "prefer", "like", "want", "should always" → `preference`
 - Contains "watch out", "careful", "gotcha", "trap", "bug" → `gotcha`
 - Otherwise → `discovery`
 
+#### Type aliases
+
+- `procedural` → `pattern` (normalize on input; storage always writes `type: pattern`)
+
 ### Step 2: Apply type defaults
 
 | Type | Default importance | Default ttl_days |
@@ -62,7 +68,14 @@ If type is not provided, classify the content:
 | gotcha | 5 | 30 |
 | discovery | 4 | 14 |
 
-Agent-provided overrides take precedence.
+Agent-provided overrides take precedence. An explicit `importance` arg overrides the type default.
+
+### Step 2b: Resolve initial tier from importance
+
+- If `tier` is explicitly passed → use that, skip the rest.
+- Else if `importance` is `high` (or numeric importance >= 7) → `semantic`
+- Else if `importance` is `low` (or numeric importance <= 3) → `working`
+- Else (medium, or 4-6) → `episodic`
 
 ### Step 3: Generate tags with synonym expansion
 
@@ -88,7 +101,7 @@ Write to `{brain_path}/memory/{safe_name}.md`:
 ```yaml
 ---
 type: {detected or provided type}
-tier: working
+tier: {resolved tier from Step 2b}
 confidence: 0.5
 importance: {from type defaults or override}
 ttl_days: {from type defaults or override, null if permanent}
@@ -112,14 +125,14 @@ indexed_at: "{ISO 8601 timestamp}"
 - **episodic**: Specific events or decisions from past sessions. Medium longevity. Use for "we decided X on date Y" or "this happened in project Z".
 - **semantic**: Generalized patterns and facts extracted from experience. Permanent by default. Use for stable conventions, recurring patterns, and distilled knowledge that transcends any single session.
 
-New memories always start at `tier: working`. Consolidation (wicked-brain:consolidate) promotes them to `episodic` or `semantic` based on access frequency and age.
+New memories start at the tier resolved from importance (default `episodic` for medium importance, `working` for low, `semantic` for high). Consolidation (wicked-brain:consolidate) still promotes them across tiers based on access frequency and age.
 
 #### Complete example
 
 ```yaml
 ---
 type: decision
-tier: working
+tier: semantic
 confidence: 0.9
 importance: 7
 ttl_days: null
@@ -151,7 +164,7 @@ The server's file watcher will auto-index this file.
 Append to `{brain_path}/_meta/log.jsonl`:
 
 ```json
-{"ts":"{ISO}","op":"memory_store","path":"memory/{safe_name}.md","type":"{type}","tier":"working","author":"agent:memory"}
+{"ts":"{ISO}","op":"memory_store","path":"memory/{safe_name}.md","type":"{type}","tier":"{resolved tier}","author":"agent:memory"}
 ```
 
 ### Step 7: Emit bus event
@@ -161,7 +174,7 @@ npx wicked-bus emit \
   --type "wicked.memory.stored" \
   --domain "wicked-brain" \
   --subdomain "brain.memory" \
-  --payload '{"path":"memory/{safe_name}.md","type":"{type}","tier":"working","brain_id":"{brain_id}"}' 2>/dev/null || true
+  --payload '{"path":"memory/{safe_name}.md","type":"{type}","tier":"{resolved tier}","brain_id":"{brain_id}"}' 2>/dev/null || true
 ```
 
 Fire-and-forget — if the bus is not installed, silently skip.
@@ -187,7 +200,7 @@ consolidation. Use a consistent session_id for the entire conversation.
 
 ### Step 2: Filter results
 
-Filter to paths starting with `memory/`. If filter_type or filter_tier provided, read frontmatter and filter accordingly.
+Filter to paths starting with `memory/`. If filter_type or filter_tier provided, read frontmatter and filter accordingly. Normalize `filter_type: procedural` to `pattern` before matching, so it matches memories stored with `type: pattern`.
 
 ### Step 3: Apply tier weighting