@ngo-a/native-memory-citations 2026.6.7 → 2026.6.9

package/README.md

@@ -13,6 +13,25 @@ access; it is operator-controlled retrieval with an audit trail.
 
 ![Architecture](https://raw.githubusercontent.com/NGO-A/native-memory-citations/master/docs/architecture.svg)
 
+## Operating modes
+
+The plugin runs in one of two modes, selected by the `mode` configuration key.
+
+- **`bounded` (default).** The behavior described throughout this README: read-only
+ retrieval, keyword/substring search, extractive cited answers, no network calls, no
+ model calls, and no changes to host configuration. This is what a default install
+ does, and what every guarantee in this document refers to.
+- **`enhanced` (opt-in).** Layers the three pillars of agentic memory - a local
+ knowledge graph, semantic and reranked recall, session-snapshot injection, and
+ observation tagging - on top of the bounded core, reusing the same access boundary,
+ redaction, and citation guarantees. Every enhanced capability is disabled by default
+ even in enhanced mode and is turned on explicitly, per feature.
+
+Leaving configuration at its defaults keeps the plugin in bounded mode; an upgrade
+changes nothing until you opt in. Enhanced-mode capabilities are introduced
+incrementally beginning with the 2026.6.9 release - see
+[Enhanced mode](#enhanced-mode-opt-in).
+
 ## Key capabilities
 
 - Operator-defined search scope, limited to workspace-relative roots.
@@ -27,18 +46,22 @@ access; it is operator-controlled retrieval with an audit trail.
 
 From npm (recommended):
 
- openclaw plugins install @ngo-a/native-memory-citations
+```sh
+openclaw plugins install @ngo-a/native-memory-citations
+```
 
 From a local checkout (development):
 
- openclaw plugins install ./native-memory-citations
+```sh
+openclaw plugins install ./native-memory-citations
+```
 
 Reload the Gateway after installing so the plugin host exposes the tools.
 
 ## Requirements
 
 - Node.js 22.19.0 or newer.
-- OpenClaw 2026.5.17 or newer (declared as a peer dependency).
+- OpenClaw 2026.6.8 or newer (declared as a peer dependency).
 - A local OpenClaw workspace containing text memory files.
 
 Supported memory file types are `.md`, `.txt`, `.json`, `.jsonl`, `.yaml`, and
@@ -53,9 +76,9 @@ identity files, and tool references must be handled within clear boundaries.
 
 ## Tools
 
-- `native_memory_search` — search the approved roots and return snippets with source paths, line numbers, and file SHA-256 hashes.
-- `native_memory_fetch` — fetch a cited source by `sourceId` or a safe path, optionally checking an expected citation hash.
-- `native_memory_answer` — build an extractive answer from cited snippets, and state plainly when no cited memory is found.
+- `native_memory_search` - search the approved roots and return snippets with source paths, line numbers, and file SHA-256 hashes.
+- `native_memory_fetch` - fetch a cited source by `sourceId` or a safe path, optionally checking an expected citation hash.
+- `native_memory_answer` - build an extractive answer from cited snippets, and state plainly when no cited memory is found.
 
 ## Default scope
 
@@ -185,6 +208,103 @@ marks the result with `stale: true` and a `staleMessage` explaining the hash
 mismatch. Because hashes cover the full file, appending to a daily journal marks
 earlier citations stale even when the cited lines themselves are unchanged.
 
+## Enhanced mode (opt-in)
+
+Enhanced mode layers the three pillars of agentic memory - storage, injection, and
+recall - on top of the bounded core, while reusing the same access boundary,
+redaction, and citation guarantees. It is opt-in and default-off: setting
+`mode: "enhanced"` turns on the framework, and each pillar is then enabled
+individually. Doing nothing leaves the plugin in bounded mode.
+
+> **Availability (2026.6.9).** Enhanced mode is delivered incrementally. This release
+> ships the bounded-mode guardrails, the enhanced config schema, plugin health checks,
+> the deterministic zero-LLM knowledge-graph sidecar, and the enhanced lifecycle
+> scaffolding. The richer recall, model-based, and wiki pillars - and full runtime
+> dispatch/soak validation of the lifecycle hooks - are still pending (see Forthcoming).
+> On any version, an unset or default configuration behaves exactly as bounded mode.
+
+### What 2026.6.9 ships
+
+- **Bounded mode (default)** - unchanged guardrails and behavior (everything above).
+- **Enhanced config schema + plugin health checks** - all enhanced keys are
+ schema-declared (so `openclaw doctor --fix` will not prune them), and the plugin
+ registers health checks visible to `openclaw doctor`.
+- **Knowledge graph, zero-LLM** (`graph.enabled`). `native_memory_extract` writes typed
+ entity links (for example `works_at`, `invested_in`, `founded`) from your authorized
+ memory files into `memory/graph.jsonl` with no model call; `native_memory_graph`
+ queries it with a hard depth cap and cycle prevention. This pillar is functional in
+ this release.
+- **Enhanced lifecycle scaffolding** (`injection.enabled`, `observations.enabled`,
+ `recall.snapshotFirst`). The code paths are present: `session_start` writes a capped
+ session snapshot, `before_prompt_build` injects it, and `agent_end` appends to
+ `memory/observations.jsonl` within `observations.maxBytes`. They require their host hook gates
+ (`hooks.allowPromptInjection` for injection, `hooks.allowConversationAccess` for the
+ observation append). On external-CLI runners or any other harness where in-process
+ lifecycle hooks do not dispatch, these hook-dependent features degrade cleanly: the
+ turn is unaffected and the three core cited-memory tools still work. **Runtime hook
+ dispatch and soak validation are still pending - treat these as experimental until
+ validated on the embedded runner.**
+
+### Forthcoming (not in 2026.6.9)
+
+- Semantic recall fusion through the host `memory_search`, RRF reranking, intent
+ classification, and snapshot-first recall inside `native_memory_search` /
+ `native_memory_answer`.
+- Model-based observation extraction (the current path appends without a model) and its
+ fail-open-under-slow-model validation. When it ships, the default will use the
+ host's configured summarization/fast model, not a provider-specific model name.
+- The `memory-wiki` bridge.
+- External gateway-perf, package-gauntlet, and long-soak validation lanes.
+
+### Dreaming requirement
+
+Enhanced mode builds on OpenClaw's built-in dream cycle (Light -> REM -> Deep
+consolidation), which is **off by default in OpenClaw**. When you enable enhanced
+mode, the plugin enables dreaming for you and prints a notice explaining that it
+*continues* - and does not replace - OpenClaw's dreaming, and that disabling dreaming
+while enhanced mode is on will degrade or silently break these features. Bounded mode
+never touches the dreaming setting. (In `2026.6.9` the guard's code path ships; its
+host-config mutation on real startup is part of the dispatch validation still pending.)
+
+### Configuration (enhanced keys)
+
+All keys default off/false; an absent block means bounded mode. Every key is part of
+the plugin schema, so `openclaw doctor --fix` will not prune it. Keys for forthcoming
+pillars - `recall.semantic`, `recall.rerank`, `recall.intentClassifier`,
+`observations.model` and model-based `observations.extraction`, and `wikiBridge.enabled`
+- are accepted by the schema but have no effect until those pillars ship. Omit
+`observations.model` to use the host's configured summarization/fast model when
+model-based extraction is implemented; if no host model is available, observation
+tagging falls back to the no-model append path.
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `mode` | string | `"bounded"` | `"bounded"` or `"enhanced"`. |
+| `graph.enabled` | boolean | `false` | Enable knowledge-graph extraction and the graph tools. |
+| `graph.edgeTypes` | string[] | built-in set | Typed edges to extract. |
+| `graph.maxDepth` | number | `3` | Hard cap on multi-hop traversal depth. |
+| `recall.semantic` | boolean | `false` | Add semantic retrieval to search/answer. |
+| `recall.rerank` | boolean | `false` | Rerank retrieved results by relevance. |
+| `recall.snapshotFirst` | boolean | `false` | Check the session snapshot before deeper search. |
+| `recall.intentClassifier` | boolean | `false` | Classify query intent to steer retrieval. |
+| `injection.enabled` | boolean | `false` | Inject a capped session snapshot into context. |
+| `injection.tokenCap` | number | `1300` | Maximum tokens injected per session. |
+| `observations.enabled` | boolean | `false` | Tag per-turn observations. |
+| `observations.model` | string | host default | Optional model profile for future extraction; when omitted, use the host's configured summarization/fast model. |
+| `observations.extraction` | boolean | `true` | When `false`, record raw entries with no model call. |
+| `observations.maxBytes` | number | `1048576` | Maximum retained size for `memory/observations.jsonl` in enhanced mode. |
+| `dreaming.autoEnable` | boolean | `true` | In enhanced mode, enable host dreaming if it is off. |
+| `dreaming.enforce` | boolean | `true` | Re-warn at startup if dreaming is disabled in enhanced mode. |
+| `dreaming.blockToolsWhenOff` | boolean | `false` | If `true`, dreaming-dependent tools error instead of degrading when dreaming is off. |
+| `wikiBridge.enabled` | boolean | `false` | Enrich a separately installed `memory-wiki` vault, if present. |
+
+### Compatibility
+
+Enhanced mode requires a newer OpenClaw floor than bounded mode; the package declares
+the required version per release. Hook-dependent features require a host harness that
+dispatches in-process lifecycle hooks; external CLI runners and other non-dispatching
+harnesses keep the core tools working and simply do not run those enhanced hooks.
+
 ## Security model
 
 The plugin enforces a two-layer model.

package/dist/core.d.ts

@@ -3,6 +3,65 @@ export type PluginConfig = {
     allowedRoots?: string[];
     sharedMode?: boolean;
     maxFileBytes?: number;
+    mode?: "bounded" | "enhanced";
+    dreaming?: {
+        autoEnable?: boolean;
+        enforce?: boolean;
+        blockToolsWhenOff?: boolean;
+    };
+    graph?: {
+        enabled?: boolean;
+        edgeTypes?: GraphEdgeType[];
+        maxDepth?: number;
+    };
+    recall?: {
+        semantic?: boolean;
+        rerank?: boolean;
+        snapshotFirst?: boolean;
+        intentClassifier?: boolean;
+    };
+    injection?: {
+        enabled?: boolean;
+        tokenCap?: number;
+    };
+    observations?: {
+        enabled?: boolean;
+        model?: string;
+        extraction?: boolean;
+        maxBytes?: number;
+    };
+    wikiBridge?: {
+        enabled?: boolean;
+    };
+};
+export type GraphEdgeType = "works_at" | "invested_in" | "founded" | "advises" | "attended" | "mentions";
+export type GraphEdge = {
+    from: string;
+    type: GraphEdgeType;
+    to: string;
+    sourceFile: string;
+    sourceLine: number;
+    extractedAt: string;
+};
+export type GraphExtractResult = {
+    enabled: boolean;
+    mode: "bounded" | "enhanced";
+    graphPath: string;
+    edgeCount: number;
+    skipped?: string;
+};
+export type GraphPath = {
+    nodes: string[];
+    edges: GraphEdge[];
+};
+export type GraphQueryResult = {
+    enabled: boolean;
+    mode: "bounded" | "enhanced";
+    query: string;
+    maxDepth: number;
+    edgeCount: number;
+    paths: GraphPath[];
+    skipped?: string;
 };
 export type SearchHit = {
     sourceId: string;
@@ -38,6 +97,9 @@ export type MemoryLogger = {
     error?: (message: string) => void;
 };
 export declare function workspaceFromConfig(config?: PluginConfig): string;
+export declare function modeFromConfig(config?: PluginConfig): "bounded" | "enhanced";
+export declare function isEnhancedMode(config?: PluginConfig): boolean;
+export declare function graphEnabled(config?: PluginConfig): boolean;
 export declare function allowedRoots(config?: PluginConfig): string[];
 export declare function toSafePath(config: PluginConfig, requested: string): Promise<string>;
 export declare function sourceIdForPath(config: PluginConfig, absolutePath: string): string;
@@ -49,6 +111,13 @@ export declare function searchMemory(query: string, options?: {
     signal?: AbortSignal;
     logger?: MemoryLogger;
 }): Promise<SearchHit[]>;
+export declare function extractMemoryGraph(config?: PluginConfig, options?: {
+    logger?: MemoryLogger;
+}): Promise<GraphExtractResult>;
+export declare function queryMemoryGraph(query: string, options?: {
+    maxDepth?: number;
+    config?: PluginConfig;
+}): Promise<GraphQueryResult>;
 export declare function fetchMemorySource(input: {
     sourceId?: string;
     filePath?: string;

package/dist/core.js

@@ -1,4 +1,4 @@
-import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { mkdir, readdir, readFile, realpath, stat, writeFile } from "node:fs/promises";
 import { createHash } from "node:crypto";
 import os from "node:os";
 import path from "node:path";
@@ -17,6 +17,8 @@ const DEFAULT_MAX_FILE_BYTES = 1024 * 1024;
 const SCAN_CONCURRENCY = 8;
 const HIGH_ENTROPY_TOKEN_MIN_LENGTH = 24;
 const HIGH_ENTROPY_TOKEN_MIN_BITS_PER_CHAR = 4;
+const DEFAULT_GRAPH_EDGE_TYPES = ["works_at", "invested_in", "founded", "advises", "attended", "mentions"];
+const GRAPH_EXTRACTED_AT = "1970-01-01T00:00:00.000Z";
 const STOPWORDS = new Set([
     "the",
     "a",
@@ -93,6 +95,22 @@ function defaultWorkspace() {
 export function workspaceFromConfig(config = {}) {
     return path.resolve(config.workspace?.trim() || defaultWorkspace());
 }
+export function modeFromConfig(config = {}) {
+    return config.mode === "enhanced" ? "enhanced" : "bounded";
+}
+export function isEnhancedMode(config = {}) {
+    return modeFromConfig(config) === "enhanced";
+}
+export function graphEnabled(config = {}) {
+    return isEnhancedMode(config) && config.graph?.enabled === true;
+}
+function graphPath(config = {}) {
+    return path.join(workspaceFromConfig(config), "memory", "graph.jsonl");
+}
+function enabledGraphEdgeTypes(config = {}) {
+    const configured = config.graph?.edgeTypes?.length ? config.graph.edgeTypes : DEFAULT_GRAPH_EDGE_TYPES;
+    return new Set(configured.filter((type) => DEFAULT_GRAPH_EDGE_TYPES.includes(type)));
+}
 export function allowedRoots(config = {}) {
     const roots = config.allowedRoots && config.allowedRoots.length > 0
         ? config.allowedRoots
@@ -231,6 +249,14 @@ function publicHit(hit) {
         sha256: hit.sha256,
     };
 }
+function graphSourceRoots(config) {
+    const workspace = workspaceFromConfig(config);
+    return [path.join(workspace, "memory"), path.join(workspace, "MEMORY.md")];
+}
+function isDerivedMemoryArtifact(config, file) {
+    const sourceId = sourceIdForPath(config, file);
+    return sourceId === "memory/graph.jsonl" || sourceId === "memory/observations.jsonl";
+}
 async function collectFiles(root, logger) {
     const info = await stat(root).catch(() => null);
     if (!info) {
@@ -432,6 +458,173 @@ async function searchMemoryInternal(query, options = {}) {
 export async function searchMemory(query, options = {}) {
     return (await searchMemoryInternal(query, options)).map(publicHit);
 }
+function normalizeEntity(value) {
+    return value
+        .replace(/[`*_()[\]{}]/g, "")
+        .replace(/\s+/g, " ")
+        .replace(/[.,;:!?]+$/g, "")
+        .trim();
+}
+function addEdge(edges, seen, edge) {
+    const normalized = {
+        ...edge,
+        from: normalizeEntity(edge.from),
+        to: normalizeEntity(edge.to),
+        extractedAt: GRAPH_EXTRACTED_AT,
+    };
+    if (!normalized.from || !normalized.to || normalized.from === normalized.to) {
+        return;
+    }
+    const key = `${normalized.from}\0${normalized.type}\0${normalized.to}\0${normalized.sourceFile}\0${normalized.sourceLine}`;
+    if (seen.has(key)) {
+        return;
+    }
+    seen.add(key);
+    edges.push(normalized);
+}
+function extractEdgesFromLine(line, sourceFile, sourceLine, allowedTypes) {
+    const edges = [];
+    const seen = new Set();
+    const cleaned = line.replace(/^\s*(?:[-*]|\d+[.)])\s+/, "").trim();
+    const properNoun = "([A-Z][\\w@.+-]*(?:\\s+[A-Z][\\w@.+-]*){0,5})";
+    const target = "([^.;\\n]{2,120})";
+    const patterns = [
+        { type: "works_at", re: new RegExp(`${properNoun}\\s+(?:works|worked)\\s+(?:at|for)\\s+${target}`, "i") },
+        { type: "invested_in", re: new RegExp(`${properNoun}\\s+(?:invested in|backs|backed)\\s+${target}`, "i") },
+        { type: "founded", re: new RegExp(`${properNoun}\\s+(?:founded|co-founded|started)\\s+${target}`, "i") },
+        { type: "advises", re: new RegExp(`${properNoun}\\s+(?:advises|advised|mentors|mentor(?:ed)?)\\s+${target}`, "i") },
+        { type: "attended", re: new RegExp(`${properNoun}\\s+(?:attended|went to)\\s+${target}`, "i") },
+        { type: "mentions", re: new RegExp(`${properNoun}\\s+(?:mentions|mentioned|discusses|discussed)\\s+${target}`, "i") },
+    ];
+    for (const pattern of patterns) {
+        if (!allowedTypes.has(pattern.type)) {
+            continue;
+        }
+        const match = cleaned.match(pattern.re);
+        if (match?.[1] && match[2]) {
+            addEdge(edges, seen, { from: match[1], type: pattern.type, to: match[2], sourceFile, sourceLine });
+        }
+    }
+    return edges;
+}
+async function readGraphEdges(config) {
+    const text = await readFile(graphPath(config), "utf8").catch(() => "");
+    if (!text.trim()) {
+        return [];
+    }
+    const edges = [];
+    for (const line of text.split(/\r?\n/g)) {
+        if (!line.trim()) {
+            continue;
+        }
+        const parsed = JSON.parse(line);
+        if (typeof parsed.from === "string"
+            && DEFAULT_GRAPH_EDGE_TYPES.includes(parsed.type)
+            && typeof parsed.to === "string"
+            && typeof parsed.sourceFile === "string"
+            && typeof parsed.sourceLine === "number"
+            && typeof parsed.extractedAt === "string") {
+            edges.push(parsed);
+        }
+    }
+    return edges;
+}
+export async function extractMemoryGraph(config = {}, options = {}) {
+    const mode = modeFromConfig(config);
+    const target = sourceIdForPath(config, graphPath(config));
+    if (!graphEnabled(config)) {
+        return {
+            enabled: false,
+            mode,
+            graphPath: target,
+            edgeCount: 0,
+            skipped: mode === "enhanced" ? "graph.enabled is false" : "mode is bounded",
+        };
+    }
+    const allowedTypes = enabledGraphEdgeTypes(config);
+    const fileSizeLimit = maxFileBytes(config);
+    const files = (await Promise.all(graphSourceRoots(config).map((root) => collectFiles(root, options.logger)))).flat();
+    const edges = [];
+    const seen = new Set();
+    for (const file of files.sort()) {
+        if (isDerivedMemoryArtifact(config, file)) {
+            continue;
+        }
+        const loaded = await loadFile(file, fileSizeLimit, options.logger);
+        if (!loaded) {
+            continue;
+        }
+        const sourceFile = sourceIdForPath(config, file);
+        loaded.rawLines.forEach((line, index) => {
+            for (const edge of extractEdgesFromLine(line, sourceFile, index + 1, allowedTypes)) {
+                addEdge(edges, seen, edge);
+            }
+        });
+    }
+    edges.sort((a, b) => a.from.localeCompare(b.from)
+        || a.type.localeCompare(b.type)
+        || a.to.localeCompare(b.to)
+        || a.sourceFile.localeCompare(b.sourceFile)
+        || a.sourceLine - b.sourceLine);
+    const file = graphPath(config);
+    await mkdir(path.dirname(file), { recursive: true });
+    await writeFile(file, `${edges.map((edge) => JSON.stringify(edge)).join("\n")}${edges.length ? "\n" : ""}`, "utf8");
+    return { enabled: true, mode, graphPath: target, edgeCount: edges.length };
+}
+export async function queryMemoryGraph(query, options = {}) {
+    const config = options.config ?? {};
+    const mode = modeFromConfig(config);
+    const maxDepth = clampInt(options.maxDepth ?? config.graph?.maxDepth, 3, 1, 6);
+    if (!graphEnabled(config)) {
+        return {
+            enabled: false,
+            mode,
+            query,
+            maxDepth,
+            edgeCount: 0,
+            paths: [],
+            skipped: mode === "enhanced" ? "graph.enabled is false" : "mode is bounded",
+        };
+    }
+    const edges = await readGraphEdges(config);
+    const q = normalizeEntity(query).toLowerCase();
+    const starts = new Set();
+    for (const edge of edges) {
+        if (edge.from.toLowerCase().includes(q) || edge.to.toLowerCase().includes(q)) {
+            starts.add(edge.from);
+            starts.add(edge.to);
+        }
+    }
+    const adjacency = new Map();
+    for (const edge of edges) {
+        adjacency.set(edge.from, [...(adjacency.get(edge.from) ?? []), edge]);
+        adjacency.set(edge.to, [...(adjacency.get(edge.to) ?? []), { ...edge, from: edge.to, to: edge.from }]);
+    }
+    const paths = [];
+    const queue = Array.from(starts).sort().map((node) => ({ nodes: [node], edges: [] }));
+    const seenPaths = new Set();
+    while (queue.length > 0 && paths.length < 50) {
+        const current = queue.shift();
+        if (current.edges.length > 0) {
+            const key = current.nodes.join("\0");
+            if (!seenPaths.has(key)) {
+                seenPaths.add(key);
+                paths.push(current);
+            }
+        }
+        if (current.edges.length >= maxDepth) {
+            continue;
+        }
+        const last = current.nodes[current.nodes.length - 1] ?? "";
+        for (const edge of adjacency.get(last) ?? []) {
+            if (current.nodes.includes(edge.to)) {
+                continue;
+            }
+            queue.push({ nodes: [...current.nodes, edge.to], edges: [...current.edges, edge] });
+        }
+    }
+    return { enabled: true, mode, query, maxDepth, edgeCount: edges.length, paths };
+}
 export async function fetchMemorySource(input, config = {}) {
     const requested = input.sourceId || input.filePath;
     if (!requested) {

package/dist/enhanced.d.ts

@@ -0,0 +1,48 @@
+import { type PluginConfig } from "./core.js";
+type PluginApiLike = {
+    pluginConfig?: PluginConfig;
+    config?: OpenClawConfigLike;
+    logger?: {
+        debug?: (message: string) => void;
+        info?: (message: string) => void;
+        warn?: (message: string) => void;
+        error?: (message: string) => void;
+    };
+    registerHook?: (events: string | string[], handler: (event: unknown, ctx: unknown) => unknown, opts?: unknown) => void;
+    on?: (event: string, handler: (event: unknown, ctx: unknown) => unknown, opts?: unknown) => void;
+    runtime?: {
+        config?: {
+            current?: () => unknown;
+            mutateConfigFile?: (params: {
+                afterWrite: {
+                    mode: "auto" | "none" | "restart" | "reload";
+                };
+                mutate: (draft: Record<string, unknown>) => void;
+            }) => Promise<unknown>;
+        };
+    };
+};
+type OpenClawConfigLike = {
+    memory?: {
+        dreaming?: {
+            enabled?: boolean;
+        };
+    };
+    plugins?: {
+        entries?: Record<string, {
+            config?: {
+                dreaming?: {
+                    enabled?: boolean;
+                };
+            };
+        } | unknown>;
+    };
+};
+declare function setDreamingEnabledOnConfig(draft: Record<string, unknown>): void;
+export declare function registerEnhancedLifecycle(api: PluginApiLike): void;
+export declare const enhancedLifecycleForTest: {
+    DREAMING_NOTICE: string;
+    PLUGIN_ID: string;
+    setDreamingEnabledOnConfig: typeof setDreamingEnabledOnConfig;
+};
+export {};