openclaw-hybrid-memory 2026.4.21 → 2026.4.30

package/README.md

@@ -1,6 +1,6 @@
 # OpenClaw memory-hybrid plugin
 
-Your OpenClaw agent forgets after each session. This plugin gives it **lasting memory**: structured facts (SQLite + FTS5) and semantic search (LanceDB), with auto-capture, auto-recall, TTL-based decay, **dynamic memory tiering (hot/warm/cold)**, LLM auto-classification, graph-based spreading activation for zero-LLM recall, and an optional credential vault. **Progressive disclosure** lets you inject a lightweight memory index instead of full texts—the agent uses `memory_recall` to fetch only what it needs, saving tokens. One install, one config—then your agent remembers preferences, decisions, and context across conversations.
+Your OpenClaw agent forgets after each session. This plugin gives it **lasting memory**: structured facts (SQLite + FTS5) and semantic search (LanceDB), with auto-capture, auto-recall, TTL-based decay, **dynamic memory tiering (hot/warm/cold)**, LLM auto-classification, graph-based spreading activation for zero-LLM recall, **contacts and organizations** (multilingual PERSON/ORG extraction with **franc** + LLM when graph is on; agent tool `memory_directory`), and an optional credential vault. **Progressive disclosure** lets you inject a lightweight memory index instead of full texts—the agent uses `memory_recall` to fetch only what it needs, saving tokens. One install, one config—then your agent remembers preferences, decisions, and context across conversations.
 
 Part of the [OpenClaw Hybrid Memory](https://github.com/markus-lassfolk/openclaw-hybrid-memory) v3 deployment.
 
@@ -43,7 +43,7 @@ Or with npm directly: `npm i openclaw-hybrid-memory` in your OpenClaw extensions
 
 **Manual install from a `.tgz`:** npm packages never ship `node_modules`; after `tar -xzf` you must run **`npm install --omit=dev`** or **`npm ci --omit=dev`** (plain `npm ci` also installs devDependencies). The published artifact includes **`npm-shrinkwrap.json`** (npm strips `package-lock.json` from published tarballs by design; `npm ci` uses the shrinkwrap the same way). Let the command finish—**`postinstall`** installs and rebuilds **`@lancedb/lancedb`** for your platform.
 
-**2. Configure.** Set your OpenAI API key and enable the plugin. Easiest: run `openclaw hybrid-mem install` to merge full defaults (memory slot, compaction prompts, nightly session-distillation job) into `~/.openclaw/openclaw.json`, then set `plugins.entries["openclaw-hybrid-memory"].config.embedding.apiKey` to your key.
+**2. Configure.** Set your OpenAI API key and enable the plugin. Easiest: run `openclaw hybrid-mem install` to merge full defaults (memory slot, compaction prompts, nightly session-distillation job) into `~/.openclaw/openclaw.json`, then set `plugins.entries["openclaw-hybrid-memory"].config.embedding.apiKey` to your key. The same command copies the bundled **hybrid-memory AgentSkill** folder to `{workspace}/skills/hybrid-memory/` (`SKILL.md` plus `references/`, e.g. memory optimization guide—OpenClaw’s highest-precedence skill location; see [Skills](https://docs.openclaw.ai/tools/skills)) and merges a **managed section** into `{workspace}/TOOLS.md` (guidance only—[Agent workspace](https://docs.openclaw.ai/concepts/agent-workspace)). The TOOLS block is delimited by HTML comments so `install` / `upgrade` can refresh it without overwriting your other notes. Workspace root is `OPENCLAW_WORKSPACE` (if set to a valid path), `agents.defaults.workspace`, `agent.workspace`, or `~/.openclaw/workspace` by default.
 
 **3. Restart the gateway** and run **`openclaw hybrid-mem verify [--fix]`** to confirm SQLite, LanceDB, and the embedding API. Use `--fix` to add any missing config (e.g. embedding block, nightly job) and to normalize isolated `hybrid-mem:*` cron jobs by removing explicit top-level `sessionKey` values so OpenClaw uses per-job `cron:<jobId>` session isolation. Verify also warns if **`hybrid-mem:*` cron job models** disagree with **`agents.defaults.model.primary`** (see [SESSION-DISTILLATION.md](../../docs/SESSION-DISTILLATION.md) § *Maintenance cron session isolation and model alignment*).
 
@@ -63,7 +63,11 @@ Or with npm directly: `npm i openclaw-hybrid-memory` in your OpenClaw extensions
 
 ## Agent tool names
 
-Every tool this plugin registers uses **underscore** names (for example `memory_store`, `memory_recall`, `memory_record_episode`). LLM providers that validate tool definitions (notably **Anthropic**) require names to match `^[a-zA-Z0-9_-]{1,128}$` — **periods are not allowed**. Do not document or prompt for dotted aliases such as `memory.store`; they are not valid in those APIs.
+Every tool this plugin registers uses **underscore** names (for example `memory_store`, `memory_recall`, `memory_directory`, `memory_record_episode`). LLM providers that validate tool definitions (notably **Anthropic**) require names to match `^[a-zA-Z0-9_-]{1,128}$` — **periods are not allowed**. Do not document or prompt for dotted aliases such as `memory.store`; they are not valid in those APIs.
+
+## Entity layer (contacts, organizations, NER)
+
+When **`graph.enabled`** is true, new facts are enriched asynchronously with **PERSON** and **ORG** mentions (language hint via **franc**, extraction via LLM). Data lives in SQLite (`organizations`, `contacts`, `fact_entity_mentions`, `org_fact_links`). The **`memory_directory`** tool exposes **`list_contacts`** and **`org_view`** for structured lists—use **`memory_recall`** for ranked semantic search. Backfill older facts with **`openclaw hybrid-mem enrich-entities`**. See [GRAPH-MEMORY.md](../../docs/GRAPH-MEMORY.md#person-and-organization-enrichment-entity-layer) and [MULTILINGUAL-SUPPORT.md](../../docs/MULTILINGUAL-SUPPORT.md).
 
 ## Event Bus
 
@@ -144,6 +148,31 @@ Installing at this level means Node's module resolution finds it by traversing u
 
 Then set `embedding.provider: "onnx"` in your plugin config. Models are auto-downloaded from HuggingFace on first use. `onnxruntime-node` is not listed as a dependency of this package — it is a ~513 MB optional native binary that most users do not need. The plugin detects its absence and shows a clear error if you configure the `onnx` provider without installing it.
 
+## Recall Timing Diagnostics
+
+Set `autoRecall.recallTiming` to:
+
+- `off` (default): no structured recall timing events
+- `basic`: completed events with duration/counters
+- `verbose`: started+completed events plus ISO timestamps
+
+Example:
+
+```json
+"autoRecall": {
+  "enabled": true,
+  "recallTiming": "basic"
+}
+```
+
+Operator workflow:
+
+```bash
+openclaw logs --follow | rg 'memory-hybrid: recall span='
+```
+
+The recall logs include a shared `span` plus `phase`, `event`, `duration_ms`, and counts (for example `hits`, `fts_rows`, `merged_rows`) so you can attribute latency across FTS, embedding, LanceDB/vector search, merge, and stage-level orchestration.
+
 ## Credits
 
 Based on the design in **[Give Your Clawdbot Permanent Memory](https://clawdboss.ai/posts/give-your-clawdbot-permanent-memory)** (Clawdboss.ai). The plugin has since been extended with auto-capture, auto-recall, decay/TTL, auto-classify, token caps, consolidation, verify/uninstall CLI, and more — see the [repo README](../../README.md) and [docs/](../../docs/).

package/api/memory-plugin-api.ts

@@ -108,6 +108,8 @@ export interface MemoryPluginAPI {
   // --- Refs (lifecycle / degradation) ---
   restartPendingClearedRef: { value: boolean };
   recallInFlightRef: { value: number };
+  /** Last prompt used for before_agent_start recall; used to re-match memories after compaction (#957). */
+  lastAutoRecallPromptRef: { value: string | null };
 
   // --- WAL & search (raw; caller binds wal where needed) ---
   walWrite: WalWriteFn;

package/api/plugin-runtime.ts

@@ -97,6 +97,8 @@ export interface PluginRuntime {
   restartPendingClearedRef: { value: boolean };
   /** Count of in-flight recall operations (degradation / back-pressure). */
   recallInFlightRef: { value: number };
+  /** Last user prompt used for interactive auto-recall (issue #957 post-compaction reinjection). */
+  lastAutoRecallPromptRef: { value: string | null };
   /** Last progressive index fact IDs (1-based position → fact id). */
   lastProgressiveIndexIds: string[];
 

package/backends/facts-db/entity-layer.ts

@@ -0,0 +1,359 @@
+/**
+ * Organizations, contacts, and NER mention persistence (#985–#987).
+ */
+
+import { randomUUID } from "node:crypto";
+import type { DatabaseSync } from "node:sqlite";
+
+import { createTransaction } from "../../utils/sqlite-transaction.js";
+
+export type EntityMentionLabel = "PERSON" | "ORG";
+
+type FactEntityMentionRow = {
+  id: string;
+  factId: string;
+  label: EntityMentionLabel;
+  surfaceText: string;
+  normalizedSurface: string;
+  startOffset: number;
+  endOffset: number;
+  confidence: number;
+  detectedLang: string | null;
+  source: string;
+  contactId: string | null;
+  organizationId: string | null;
+};
+
+export type OrganizationRow = {
+  id: string;
+  canonicalKey: string;
+  displayName: string;
+  aliasesJson: string | null;
+};
+
+export type ContactRow = {
+  id: string;
+  normalizedKey: string;
+  displayName: string;
+  email: string | null;
+  notes: string | null;
+  aliasesJson: string | null;
+  primaryOrgId: string | null;
+};
+
+export function normalizeEntityKey(name: string): string {
+  return name.normalize("NFKD").replace(/\p{M}/gu, "").toLowerCase().replace(/\s+/g, " ").trim();
+}
+
+/** Escape `%`, `_`, and `\` for SQLite `LIKE ... ESCAPE '\'` literal matching. */
+export function escapeLikeLiteralForBackslashEscape(s: string): string {
+  return s.replace(/\\/g, "\\\\").replace(/%/g, "\\%").replace(/_/g, "\\_");
+}
+
+export function migrateEntityLayerTables(db: DatabaseSync): void {
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS organizations (
+      id TEXT PRIMARY KEY,
+      canonical_key TEXT NOT NULL UNIQUE,
+      display_name TEXT NOT NULL,
+      aliases_json TEXT,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_org_canonical ON organizations(canonical_key);
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS contacts (
+      id TEXT PRIMARY KEY,
+      normalized_key TEXT NOT NULL,
+      display_name TEXT NOT NULL,
+      email TEXT,
+      notes TEXT,
+      aliases_json TEXT,
+      primary_org_id TEXT REFERENCES organizations(id) ON DELETE SET NULL,
+      created_at INTEGER NOT NULL,
+      updated_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_contacts_org ON contacts(primary_org_id);
+  `);
+  // One row per normalized display key (upsertContact assumes uniqueness).
+  db.exec("CREATE UNIQUE INDEX IF NOT EXISTS idx_contacts_normalized_key_unique ON contacts(normalized_key)");
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS fact_entity_mentions (
+      id TEXT PRIMARY KEY,
+      fact_id TEXT NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+      label TEXT NOT NULL,
+      surface_text TEXT NOT NULL,
+      normalized_surface TEXT NOT NULL,
+      start_offset INTEGER NOT NULL,
+      end_offset INTEGER NOT NULL,
+      confidence REAL NOT NULL DEFAULT 0.8,
+      detected_lang TEXT,
+      source TEXT NOT NULL DEFAULT 'llm',
+      contact_id TEXT REFERENCES contacts(id) ON DELETE SET NULL,
+      organization_id TEXT REFERENCES organizations(id) ON DELETE SET NULL,
+      created_at INTEGER NOT NULL
+    );
+    CREATE INDEX IF NOT EXISTS idx_fem_fact ON fact_entity_mentions(fact_id);
+    CREATE INDEX IF NOT EXISTS idx_fem_org ON fact_entity_mentions(organization_id);
+    CREATE INDEX IF NOT EXISTS idx_fem_contact ON fact_entity_mentions(contact_id);
+    CREATE INDEX IF NOT EXISTS idx_fem_label ON fact_entity_mentions(label);
+  `);
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS org_fact_links (
+      org_id TEXT NOT NULL REFERENCES organizations(id) ON DELETE CASCADE,
+      fact_id TEXT NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+      reason TEXT NOT NULL DEFAULT 'ner_mention',
+      created_at INTEGER NOT NULL,
+      PRIMARY KEY (org_id, fact_id, reason)
+    );
+    CREATE INDEX IF NOT EXISTS idx_org_fact_org ON org_fact_links(org_id);
+    CREATE INDEX IF NOT EXISTS idx_org_fact_fact ON org_fact_links(fact_id);
+  `);
+}
+
+function upsertOrganization(db: DatabaseSync, displayName: string): { id: string; created: boolean } | null {
+  const canonicalKey = normalizeEntityKey(displayName);
+  if (!canonicalKey) {
+    return null;
+  }
+  const existing = db.prepare("SELECT id FROM organizations WHERE canonical_key = ?").get(canonicalKey) as
+    | { id: string }
+    | undefined;
+  if (existing) {
+    const now = Math.floor(Date.now() / 1000);
+    db.prepare("UPDATE organizations SET display_name = ?, updated_at = ? WHERE id = ?").run(
+      displayName.trim(),
+      now,
+      existing.id,
+    );
+    return { id: existing.id, created: false };
+  }
+  const id = randomUUID();
+  const now = Math.floor(Date.now() / 1000);
+  db.prepare(
+    `INSERT INTO organizations (id, canonical_key, display_name, aliases_json, created_at, updated_at)
+     VALUES (?, ?, ?, NULL, ?, ?)`,
+  ).run(id, canonicalKey, displayName.trim(), now, now);
+  return { id, created: true };
+}
+
+function upsertContact(
+  db: DatabaseSync,
+  displayName: string,
+  primaryOrgId: string | null,
+): { id: string; created: boolean } | null {
+  const nk = normalizeEntityKey(displayName);
+  if (!nk) {
+    return null;
+  }
+  const existing = db.prepare("SELECT id, primary_org_id FROM contacts WHERE normalized_key = ? LIMIT 1").get(nk) as
+    | { id: string; primary_org_id: string | null }
+    | undefined;
+  const now = Math.floor(Date.now() / 1000);
+  if (existing) {
+    if (primaryOrgId && !existing.primary_org_id) {
+      db.prepare("UPDATE contacts SET primary_org_id = ?, updated_at = ?, display_name = ? WHERE id = ?").run(
+        primaryOrgId,
+        now,
+        displayName.trim(),
+        existing.id,
+      );
+    } else {
+      db.prepare("UPDATE contacts SET updated_at = ?, display_name = ? WHERE id = ?").run(
+        now,
+        displayName.trim(),
+        existing.id,
+      );
+    }
+    return { id: existing.id, created: false };
+  }
+  const id = randomUUID();
+  db.prepare(
+    `INSERT INTO contacts (id, normalized_key, display_name, email, notes, aliases_json, primary_org_id, created_at, updated_at)
+     VALUES (?, ?, ?, NULL, NULL, NULL, ?, ?, ?)`,
+  ).run(id, nk, displayName.trim(), primaryOrgId, now, now);
+  return { id, created: true };
+}
+
+export function replaceFactEntityMentions(
+  db: DatabaseSync,
+  factId: string,
+  mentions: Array<{
+    label: EntityMentionLabel;
+    surfaceText: string;
+    normalizedSurface: string;
+    startOffset: number;
+    endOffset: number;
+    confidence: number;
+    detectedLang: string | null;
+    source: string;
+  }>,
+): void {
+  const tx = createTransaction(db, () => {
+    db.prepare("DELETE FROM fact_entity_mentions WHERE fact_id = ?").run(factId);
+    db.prepare("DELETE FROM org_fact_links WHERE fact_id = ? AND reason = 'ner_mention'").run(factId);
+
+    const now = Math.floor(Date.now() / 1000);
+    const ins = db.prepare(
+      `INSERT INTO fact_entity_mentions (
+        id, fact_id, label, surface_text, normalized_surface, start_offset, end_offset,
+        confidence, detected_lang, source, contact_id, organization_id, created_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    );
+    const insOrgLink = db.prepare(
+      `INSERT OR IGNORE INTO org_fact_links (org_id, fact_id, reason, created_at) VALUES (?, ?, 'ner_mention', ?)`,
+    );
+
+    const orgIds: string[] = [];
+    const personRows: Array<{ surface: string; contactId: string }> = [];
+
+    for (const m of mentions) {
+      let contactId: string | null = null;
+      let organizationId: string | null = null;
+
+      if (m.label === "ORG") {
+        const org = upsertOrganization(db, m.surfaceText);
+        if (org) {
+          organizationId = org.id;
+          orgIds.push(org.id);
+          insOrgLink.run(org.id, factId, now);
+        }
+      } else if (m.label === "PERSON") {
+        const con = upsertContact(db, m.surfaceText, null);
+        if (con) {
+          contactId = con.id;
+          personRows.push({ surface: m.surfaceText, contactId: con.id });
+        }
+      }
+
+      ins.run(
+        randomUUID(),
+        factId,
+        m.label,
+        m.surfaceText,
+        m.normalizedSurface,
+        m.startOffset,
+        m.endOffset,
+        m.confidence,
+        m.detectedLang,
+        m.source,
+        contactId,
+        organizationId,
+        now,
+      );
+    }
+
+    // If same fact mentions both a person and an org, set primary_org on contacts (weak v1 heuristic).
+    if (orgIds.length > 0 && personRows.length > 0) {
+      const primaryOrg = orgIds[0];
+      for (const p of personRows) {
+        db.prepare("UPDATE contacts SET primary_org_id = COALESCE(primary_org_id, ?), updated_at = ? WHERE id = ?").run(
+          primaryOrg,
+          now,
+          p.contactId,
+        );
+      }
+    }
+
+    db.prepare("UPDATE facts SET entity_enrichment_at = ? WHERE id = ?").run(now, factId);
+  });
+  tx();
+}
+
+export function getOrganizationByKeyOrName(db: DatabaseSync, query: string): OrganizationRow | null {
+  const nk = normalizeEntityKey(query);
+  if (!nk) return null;
+  const byKey = db.prepare("SELECT * FROM organizations WHERE canonical_key = ?").get(nk) as
+    | Record<string, unknown>
+    | undefined;
+  if (byKey) return rowToOrg(byKey);
+  const like = `%${escapeLikeLiteralForBackslashEscape(nk)}%`;
+  const byName = db
+    .prepare(
+      "SELECT * FROM organizations WHERE canonical_key LIKE ? ESCAPE '\\' ORDER BY length(display_name) ASC LIMIT 1",
+    )
+    .get(like) as Record<string, unknown> | undefined;
+  return byName ? rowToOrg(byName) : null;
+}
+
+function rowToOrg(row: Record<string, unknown>): OrganizationRow {
+  return {
+    id: row.id as string,
+    canonicalKey: row.canonical_key as string,
+    displayName: row.display_name as string,
+    aliasesJson: (row.aliases_json as string | null) ?? null,
+  };
+}
+
+export function listContactsForOrg(db: DatabaseSync, orgId: string, limit: number): ContactRow[] {
+  const rows = db
+    .prepare(
+      `SELECT * FROM contacts
+       WHERE primary_org_id = ?
+       ORDER BY display_name COLLATE NOCASE
+       LIMIT ?`,
+    )
+    .all(orgId, limit) as Array<Record<string, unknown>>;
+  return rows.map(rowToContact);
+}
+
+export function listContactsByNamePrefix(db: DatabaseSync, prefix: string, limit: number): ContactRow[] {
+  const p = prefix.trim().toLowerCase();
+  if (!p) {
+    const rows = db.prepare(`SELECT * FROM contacts ORDER BY display_name COLLATE NOCASE LIMIT ?`).all(limit) as Array<
+      Record<string, unknown>
+    >;
+    return rows.map(rowToContact);
+  }
+  const esc = escapeLikeLiteralForBackslashEscape(p);
+  const pat = `${esc}%`;
+  const normalizedPrefix = normalizeEntityKey(prefix);
+  const escNormalized = escapeLikeLiteralForBackslashEscape(normalizedPrefix);
+  const patNormalized = `${escNormalized}%`;
+  const rows = db
+    .prepare(
+      `SELECT * FROM contacts
+       WHERE lower(display_name) LIKE ? ESCAPE '\\' OR normalized_key LIKE ? ESCAPE '\\'
+       ORDER BY display_name COLLATE NOCASE
+       LIMIT ?`,
+    )
+    .all(pat, patNormalized, limit) as Array<Record<string, unknown>>;
+  return rows.map(rowToContact);
+}
+
+function rowToContact(row: Record<string, unknown>): ContactRow {
+  return {
+    id: row.id as string,
+    normalizedKey: row.normalized_key as string,
+    displayName: row.display_name as string,
+    email: (row.email as string | null) ?? null,
+    notes: (row.notes as string | null) ?? null,
+    aliasesJson: (row.aliases_json as string | null) ?? null,
+    primaryOrgId: (row.primary_org_id as string | null) ?? null,
+  };
+}
+
+export function listFactIdsForOrg(db: DatabaseSync, orgId: string, limit: number): string[] {
+  const rows = db
+    .prepare(`SELECT DISTINCT fact_id FROM org_fact_links WHERE org_id = ? ORDER BY created_at DESC LIMIT ?`)
+    .all(orgId, limit) as Array<{ fact_id: string }>;
+  return rows.map((r) => r.fact_id);
+}
+
+export function listFactsNeedingEnrichment(db: DatabaseSync, limit: number, minTextLen: number): string[] {
+  const rows = db
+    .prepare(
+      `SELECT f.id FROM facts f
+       WHERE f.superseded_at IS NULL
+         AND length(f.text) >= ?
+         AND f.entity_enrichment_at IS NULL
+       ORDER BY f.created_at DESC
+       LIMIT ?`,
+    )
+    .all(minTextLen, limit) as Array<{ id: string }>;
+  return rows.map((r) => r.id);
+}

package/backends/facts-db.ts

@@ -63,6 +63,17 @@ import {
   migrateScanCursorsTable as migrateScanCursorsTableHelper,
   updateScanCursor as updateScanCursorHelper,
 } from "./facts-db/scan-cursors.js";
+import {
+  replaceFactEntityMentions,
+  getOrganizationByKeyOrName as lookupOrganizationByKeyOrName,
+  listContactsForOrg as entityLayerListContactsForOrg,
+  listContactsByNamePrefix as entityLayerListContactsByNamePrefix,
+  listFactIdsForOrg as entityLayerListFactIdsForOrg,
+  listFactsNeedingEnrichment as entityLayerListFactsNeedingEnrichment,
+  type ContactRow,
+  type OrganizationRow,
+} from "./facts-db/entity-layer.js";
+import type { ExtractedMention } from "../services/entity-enrichment.js";
 export {
   MEMORY_LINK_TYPES,
   type MemoryLinkType,
@@ -5441,4 +5452,49 @@ export class FactsDB extends BaseSqliteStore {
       return 0;
     }
   }
+
+  // --- Entity layer: NER mentions, organizations, contacts (#985–#987) ---
+
+  /** Replace stored NER rows for a fact (typically after LLM extraction). */
+  applyEntityEnrichment(factId: string, mentions: ExtractedMention[], detectedLang: string): void {
+    replaceFactEntityMentions(
+      this.liveDb,
+      factId,
+      mentions.map((m) => ({
+        label: m.label,
+        surfaceText: m.surfaceText,
+        normalizedSurface: m.normalizedSurface,
+        startOffset: m.startOffset,
+        endOffset: m.endOffset,
+        confidence: m.confidence,
+        detectedLang,
+        source: "llm",
+      })),
+    );
+  }
+
+  /** Resolve an organization by canonical key or fuzzy display name. */
+  lookupOrganization(query: string): OrganizationRow | null {
+    return lookupOrganizationByKeyOrName(this.liveDb, query);
+  }
+
+  /** Contacts with primary_org_id = org. */
+  listContactsForOrganization(orgId: string, limit: number): ContactRow[] {
+    return entityLayerListContactsForOrg(this.liveDb, orgId, limit);
+  }
+
+  /** List contacts by optional name prefix (empty = recent alphabetical cap). */
+  listContactsByNamePrefix(prefix: string, limit: number): ContactRow[] {
+    return entityLayerListContactsByNamePrefix(this.liveDb, prefix, limit);
+  }
+
+  /** Fact ids linked to an org via NER/org_fact_links. */
+  listFactIdsLinkedToOrg(orgId: string, limit: number): string[] {
+    return entityLayerListFactIdsForOrg(this.liveDb, orgId, limit);
+  }
+
+  /** Facts not yet processed by entity enrichment (see `facts.entity_enrichment_at`). */
+  listFactIdsNeedingEntityEnrichment(limit: number, minTextLen = 24): string[] {
+    return entityLayerListFactsNeedingEnrichment(this.liveDb, limit, minTextLen);
+  }
 }

package/backends/migrations/facts-migrations.ts

@@ -1,6 +1,7 @@
 import type { DatabaseSync } from "node:sqlite";
 import { createTransaction } from "../../utils/sqlite-transaction.js";
 import { normalizedHash } from "../../utils/tags.js";
+import { migrateEntityLayerTables } from "../facts-db/entity-layer.js";
 /**
  * Procedure feedback loop — version tracking and failure logging (#782).
  * procedure_versions: per-version success/failure counts and avoidance notes.
@@ -1101,6 +1102,27 @@ export function runFactsMigrations(db: DatabaseSync): void {
 
   // Token budget trim: index-backed ordering (Issue #838)
   migrateTrimBudgetIndex(db);
+
+  // Contacts, organizations, NER mentions (#985–#987)
+  migrateEntityLayerTables(db);
+  migrateFactsEntityEnrichmentAt(db);
+}
+
+/** Track completion of NER/contact-org enrichment per fact (avoids re-LLM when zero entities). */
+function migrateFactsEntityEnrichmentAt(db: DatabaseSync): void {
+  const cols = db.prepare("PRAGMA table_info(facts)").all() as Array<{ name: string }>;
+  if (!cols.some((c) => c.name === "entity_enrichment_at")) {
+    db.exec("ALTER TABLE facts ADD COLUMN entity_enrichment_at INTEGER");
+  }
+  db.exec(`
+    UPDATE facts
+    SET entity_enrichment_at = COALESCE(
+      (SELECT MIN(created_at) FROM fact_entity_mentions WHERE fact_id = facts.id),
+      created_at
+    )
+    WHERE entity_enrichment_at IS NULL
+      AND EXISTS (SELECT 1 FROM fact_entity_mentions m WHERE m.fact_id = facts.id)
+  `);
 }
 
 /** Supports SQL ORDER BY for trimToBudget without full in-memory sort of all facts (Issue #838). */

package/cli/cmd-config.ts

@@ -12,7 +12,13 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 
-import { hybridConfigSchema, PRESET_OVERRIDES, type ConfigMode } from "../config.js";
+import {
+  getCronModelConfig,
+  getLLMModelPreference,
+  hybridConfigSchema,
+  PRESET_OVERRIDES,
+  type ConfigMode,
+} from "../config.js";
 import { capturePluginError } from "../services/error-reporter.js";
 import { PLUGIN_ID, getRestartPendingPath } from "../utils/constants.js";
 import type { HandlerContext } from "./handlers.js";
@@ -73,18 +79,29 @@ function setNested(obj: Record<string, unknown>, path: string, value: unknown):
   if (last === "__proto__" || last === "constructor" || last === "prototype") {
     return false;
   }
-  const v =
-    value === "true" || value === "enabled"
-      ? true
-      : value === "false" || value === "disabled"
-        ? false
-        : value === "null"
-          ? null
-          : /^-?\d+$/.test(String(value))
-            ? Number.parseInt(String(value), 10)
-            : /^-?\d*\.\d+$/.test(String(value))
-              ? Number.parseFloat(String(value))
-              : value;
+  const rawStr = String(value).trim();
+  let v: unknown = value;
+  if ((rawStr.startsWith("[") && rawStr.endsWith("]")) || (rawStr.startsWith("{") && rawStr.endsWith("}"))) {
+    try {
+      v = JSON.parse(rawStr) as unknown;
+    } catch {
+      v = value;
+    }
+  }
+  if (v === value && typeof v === "string") {
+    v =
+      v === "true" || v === "enabled"
+        ? true
+        : v === "false" || v === "disabled"
+          ? false
+          : v === "null"
+            ? null
+            : /^-?\d+$/.test(v)
+              ? Number.parseInt(v, 10)
+              : /^-?\d*\.\d+$/.test(v)
+                ? Number.parseFloat(v)
+                : v;
+  }
   (cur as any)[last] = v;
   return true;
 }
@@ -173,6 +190,27 @@ export function runConfigViewForCli(ctx: HandlerContext, sink: VerifyCliSink): v
   log(`  Cost tracking: ${on(rawEnabled("costTracking", cfg.costTracking?.enabled ?? false))}`);
   log("");
 
+  log("LLM tiers (keep cheap models first; heavy only for quality-critical steps)");
+  try {
+    const cronCfg = getCronModelConfig(cfg);
+    const nano = getLLMModelPreference(cronCfg, "nano");
+    const def = getLLMModelPreference(cronCfg, "default");
+    const heavy = getLLMModelPreference(cronCfg, "heavy");
+    const fmt = (arr: string[]) =>
+      arr.length === 0 ? "—" : arr.length === 1 ? arr[0] : `${arr[0]} (+${arr.length - 1} more)`;
+    log(`  nano (HyDE, classify, summarize): ${fmt(nano)}`);
+    log(`  default (maintenance, dream cycle if nightlyCycle.model unset): ${fmt(def)}`);
+    log(`  heavy (distill, self-correction, hard tasks): ${fmt(heavy)}`);
+    if (cfg.nightlyCycle?.model?.trim()) {
+      log(`  nightlyCycle.model (overrides dream / MEMORY_INDEX LLM): ${cfg.nightlyCycle.model.trim()}`);
+    }
+    const extTier = cfg.distill?.extractionModelTier ?? "default";
+    log(`  distill.extractionModelTier (session extraction): ${extTier}`);
+  } catch {
+    log("  (could not resolve tiers — check plugin config)");
+  }
+  log("");
+
   log("Advanced");
   log(`  Query expansion: ${on(cfg.queryExpansion.enabled)}`);
   log(`  Retrieval directives: ${on(cfg.autoRecall.retrievalDirectives?.enabled ?? false)}`);
@@ -191,6 +229,7 @@ export function runConfigViewForCli(ctx: HandlerContext, sink: VerifyCliSink): v
 
   log("To change a setting: openclaw hybrid-mem config-set <key> <value>");
   log("Example (toggle): openclaw hybrid-mem config-set nightlyCycle enabled");
+  log("Example (LLM tier lists as JSON): openclaw hybrid-mem config-set llm.nano '[\"azure-foundry/gpt-4.1-nano\"]'");
   log("Help for a key: openclaw hybrid-mem help config-set <key>");
 }