@ngo-a/native-memory-citations 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NGO-A
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# Native Memory Citations
+
+Native OpenClaw plugin for cited local memory search and retrieval.
+Native means OpenClaw-native plugin, not native system memory.
+
+## Tools
+
+- `native_memory_search`: search approved memory roots and return snippets with source paths, line numbers, and file SHA-256 hashes.
+- `native_memory_fetch`: fetch a cited source by `sourceId` or safe path, optionally checking an expected citation hash.
+- `native_memory_answer`: build an extractive answer from cited memory snippets; says when no cited memory is found.
+
+## Default Scope
+
+By default, the plugin searches:
+
+- `memory/`
+- `MEMORY.md`
+- `USER.md`
+- `IDENTITY.md`
+- `TOOLS.md`
+
+Set `sharedMode: true` in plugin config to exclude the private `MEMORY.md` from
+the default root set. Setting `allowedRoots` explicitly overrides the default
+set entirely and supersedes `sharedMode`.
+
+Custom `allowedRoots` entries must be workspace-relative visible paths. Empty
+entries, `.`, `..`, paths containing `..`, absolute paths, and hidden path
+segments such as `memory/.dreams` are rejected.
+
+## Build, Generate, Validate
+
+The manifest (`openclaw.plugin.json`) is generated from the `defineToolPlugin`
+metadata in `src/index.ts`. Do not hand-edit it; regenerate after changing the
+plugin id, name, description, `configSchema`, or any tool name:
+
+```bash
+npm install
+npm test
+npm run plugin:build
+npm run plugin:validate
+```
+
+In CI, fail on stale generated metadata without rewriting files:
+
+```bash
+npm run plugin:build:check
+npm run plugin:validate
+npm test
+```
+
+## Config
+
+Plugin config is read from the plugin's entry in the OpenClaw Gateway config.
+All keys are optional:
+
+```json
+{
+  "workspace": "/home/ad/.openclaw/workspace",
+  "allowedRoots": ["memory", "USER.md", "TOOLS.md"],
+  "sharedMode": true,
+  "maxFileBytes": 1048576
+}
+```
+
+If `workspace` is omitted, the plugin uses `$OPENCLAW_WORKSPACE`, then
+`~/.openclaw/workspace`. There is no hardcoded user-specific default.
+
+## Notes
+
+This v1 is intentionally local-file based. It is portable and dependency-light.
+A future version can add vector search while keeping the same public tool names.
+Search is keyword/substring based with an mtime/size line cache, bounded scan
+concurrency, and `AbortSignal` checks during scan.
+
+Returned snippets, fetched content, match lines, and extractive answers are
+redacted for common secret patterns such as bearer tokens, API keys, GitHub
+tokens, password/secret/token assignment lines, credential URLs, JWTs, cloud
+keys, and private key blocks. The named pattern list is best-effort labeling,
+not the security boundary; returned text also masks sufficiently long
+high-entropy tokens when no named pattern matches. Redaction is defense-in-depth,
+not the access boundary; the access boundary is allowed roots, hidden-path
+rejection, symlink/realpath checks, file-type filtering, and size limits.
+Redaction does not mutate source files and does not affect citation hashes,
+which are computed from original file text.
+
+## Citation Integrity
+
+Search hits include `sha256`, computed from the full text file used for line
+splitting and citation line numbers. Fetch results include the current `sha256`
+for the same full-file content.
+
+To detect stale citations, pass the hash from a prior search hit:
+
+```json
+{
+  "sourceId": "memory/2026-06-17.md",
+  "lineStart": 12,
+  "lineEnd": 14,
+  "expectedSha256": "..."
+}
+```
+
+If the file changed, fetch still returns the current content for inspection, but
+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.
+
+## Install
+
+```bash
+openclaw plugins install ./native-memory-citations # current/private local checkout
+openclaw plugins install clawhub:ngo-a/native-memory-citations # future publish mode
+openclaw plugins install @ngo-a/native-memory-citations # npm publish mode
+```
+
+Reload the Gateway after installing so the plugin host exposes the tools.
+
+## Security Model
+
+See [SECURITY.md](./SECURITY.md): `allowedRoots` is trusted operator config;
+a symlink that escapes a root, and any caller-supplied fetch path, is untrusted
+and re-checked with `realpath`; symlinks found while walking directories during
+search are skipped. Fetch also rejects hidden path segments, non-text files, and
+files larger than `maxFileBytes`. Citation hashes let callers detect when a
+previous path-and-line citation may now point at changed content. Returned text
+is redacted before it leaves the plugin; named secret patterns provide nicer
+labels, while the high-entropy backstop handles unknown token formats. Redaction
+is not an authorization or access-control boundary.
+
+## Publish
+
+Deferred until distribution mode. When publishing: remove `private`, add the
+`files` allowlist and `prepublishOnly` script, then
+`clawhub package publish ngo-a/native-memory-citations` (or `npm publish`).
+
+## License
+
+[MIT](./LICENSE)
+
+## Changelog
+
+See [CHANGELOG.md](./CHANGELOG.md).

package/dist/core.d.ts

@@ -0,0 +1,65 @@
+export type PluginConfig = {
+    workspace?: string;
+    allowedRoots?: string[];
+    sharedMode?: boolean;
+    maxFileBytes?: number;
+};
+export type SearchHit = {
+    sourceId: string;
+    path: string;
+    lineStart: number;
+    lineEnd: number;
+    score: number;
+    snippet: string;
+    matchLine: number;
+    matchText: string;
+    sha256: string;
+};
+export type FetchResult = {
+    sourceId: string;
+    path: string;
+    lineStart: number;
+    lineEnd: number;
+    citation: string;
+    content: string;
+    sha256: string;
+    stale?: boolean;
+    staleMessage?: string;
+};
+export type AnswerResult = {
+    answer: string;
+    citations: SearchHit[];
+    known: boolean;
+};
+export type MemoryLogger = {
+    debug?: (message: string) => void;
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+};
+export declare function workspaceFromConfig(config?: PluginConfig): string;
+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;
+export declare function pathForSourceId(config: PluginConfig, sourceId: string): Promise<string>;
+export declare function searchMemory(query: string, options?: {
+    limit?: number;
+    contextLines?: number;
+    config?: PluginConfig;
+    signal?: AbortSignal;
+    logger?: MemoryLogger;
+}): Promise<SearchHit[]>;
+export declare function fetchMemorySource(input: {
+    sourceId?: string;
+    filePath?: string;
+    lineStart?: number;
+    lineEnd?: number;
+    maxChars?: number;
+    expectedSha256?: string;
+}, config?: PluginConfig): Promise<FetchResult>;
+export declare function answerFromMemory(query: string, options?: {
+    limit?: number;
+    config?: PluginConfig;
+    signal?: AbortSignal;
+    logger?: MemoryLogger;
+}): Promise<AnswerResult>;

package/dist/core.js

@@ -0,0 +1,545 @@
+import { readdir, readFile, realpath, stat } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_PRIVATE_ROOTS = ["memory", "MEMORY.md", "USER.md", "IDENTITY.md", "TOOLS.md"];
+const DEFAULT_SHARED_ROOTS = ["memory", "USER.md", "IDENTITY.md", "TOOLS.md"];
+const TEXT_EXTENSIONS = new Set([".md", ".txt", ".json", ".jsonl", ".yaml", ".yml"]);
+const ANSWER_MIN_SCORE = 3;
+const ANSWER_MIN_TERM_RATIO = 0.5;
+const MAX_REGION_LINES = 25;
+const FILE_CACHE_MAX = 512;
+const MAX_LINE_CHARS = 2000;
+const MAX_SNIPPET_CHARS = 4000;
+const DEFAULT_FETCH_CHARS = 8000;
+const MAX_FETCH_CHARS = 20000;
+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 STOPWORDS = new Set([
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "but",
+    "if",
+    "of",
+    "to",
+    "in",
+    "on",
+    "for",
+    "from",
+    "is",
+    "it",
+    "its",
+    "at",
+    "by",
+    "as",
+    "with",
+    "this",
+    "that",
+    "what",
+    "which",
+    "who",
+    "how",
+    "why",
+    "when",
+    "where",
+    "do",
+    "does",
+    "did",
+    "can",
+    "could",
+    "should",
+    "would",
+    "will",
+    "you",
+    "your",
+    "i",
+    "my",
+    "me",
+    "we",
+    "our",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+]);
+const fileCache = new Map();
+function clampInt(value, fallback, min, max) {
+    const n = Math.floor(value ?? fallback);
+    if (!Number.isFinite(n)) {
+        return fallback;
+    }
+    return Math.min(max, Math.max(min, n));
+}
+function maxFileBytes(config = {}) {
+    const n = Math.floor(config.maxFileBytes ?? DEFAULT_MAX_FILE_BYTES);
+    if (!Number.isFinite(n)) {
+        return DEFAULT_MAX_FILE_BYTES;
+    }
+    return Math.max(1024, n);
+}
+function defaultWorkspace() {
+    const fromEnv = process.env.OPENCLAW_WORKSPACE?.trim();
+    if (fromEnv) {
+        return fromEnv;
+    }
+    return path.join(os.homedir(), ".openclaw", "workspace");
+}
+export function workspaceFromConfig(config = {}) {
+    return path.resolve(config.workspace?.trim() || defaultWorkspace());
+}
+export function allowedRoots(config = {}) {
+    const roots = config.allowedRoots && config.allowedRoots.length > 0
+        ? config.allowedRoots
+        : config.sharedMode
+            ? DEFAULT_SHARED_ROOTS
+            : DEFAULT_PRIVATE_ROOTS;
+    const workspace = workspaceFromConfig(config);
+    return roots.map((root) => {
+        const trimmed = root.trim();
+        const segments = trimmed.split(/[\\/]+/g);
+        if (!trimmed
+            || trimmed === "."
+            || trimmed === ".."
+            || path.isAbsolute(trimmed)
+            || segments.some((segment) => segment === "..")
+            || segments.some((segment) => segment.startsWith("."))) {
+            throw new Error(`Invalid allowedRoots entry: ${root}`);
+        }
+        return path.resolve(workspace, trimmed);
+    });
+}
+function within(target, roots) {
+    return roots.some((root) => target === root || target.startsWith(`${root}${path.sep}`));
+}
+async function realpathOrSelf(p) {
+    return realpath(p).catch(() => p);
+}
+export async function toSafePath(config, requested) {
+    const workspace = workspaceFromConfig(config);
+    const resolved = path.resolve(workspace, requested);
+    const roots = allowedRoots(config);
+    if (!within(resolved, roots)) {
+        throw new Error(`Path is outside allowed memory roots: ${requested}`);
+    }
+    const realTarget = await realpathOrSelf(resolved);
+    const realRoots = await Promise.all(roots.map(realpathOrSelf));
+    if (!within(realTarget, realRoots)) {
+        throw new Error(`Path resolves via symlink outside allowed memory roots: ${requested}`);
+    }
+    return resolved;
+}
+export function sourceIdForPath(config, absolutePath) {
+    return path.relative(workspaceFromConfig(config), absolutePath).split(path.sep).join("/");
+}
+export async function pathForSourceId(config, sourceId) {
+    return toSafePath(config, sourceId);
+}
+function hasHiddenPathSegment(sourceId) {
+    return sourceId.split("/").some((segment) => segment.startsWith("."));
+}
+function isTextFile(file) {
+    return TEXT_EXTENSIONS.has(path.extname(file));
+}
+function sha256Text(text) {
+    return createHash("sha256").update(text, "utf8").digest("hex");
+}
+function isBeginMarker(line) {
+    return /^\s*-----BEGIN [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----\s*$/.test(line);
+}
+function isEndMarker(line) {
+    return /^\s*-----END [A-Z0-9 ]*PRIVATE KEY(?: BLOCK)?-----\s*$/.test(line);
+}
+function shannonEntropy(value) {
+    const counts = new Map();
+    for (const char of value) {
+        counts.set(char, (counts.get(char) ?? 0) + 1);
+    }
+    let entropy = 0;
+    for (const count of counts.values()) {
+        const p = count / value.length;
+        entropy -= p * Math.log2(p);
+    }
+    return entropy;
+}
+function redactHighEntropyTokens(line) {
+    return line.replace(/[A-Za-z0-9_+=-]{24,}/g, (token) => {
+        if (token.length >= HIGH_ENTROPY_TOKEN_MIN_LENGTH
+            && shannonEntropy(token) >= HIGH_ENTROPY_TOKEN_MIN_BITS_PER_CHAR) {
+            return "[REDACTED_HIGH_ENTROPY]";
+        }
+        return token;
+    });
+}
+function redactSingleLineSecrets(line) {
+    return redactHighEntropyTokens(line
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi, "Bearer [REDACTED]")
+        .replace(/\b(?:sk-proj-|sk-)[A-Za-z0-9_-]{16,}\b/g, "[REDACTED_OPENAI_KEY]")
+        .replace(/\bgh[psuor]_[A-Za-z0-9_]{20,}\b/g, "[REDACTED_GITHUB_TOKEN]")
+        .replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "[REDACTED_GITHUB_TOKEN]")
+        .replace(/\b(AccountKey|SharedAccessKey)=[^;\s]+/gi, "$1=[REDACTED]")
+        .replace(/\bsig=[^&\s]+/gi, "sig=[REDACTED]")
+        .replace(/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, "[REDACTED_AWS_KEY_ID]")
+        .replace(/\bxox[baprs]-[A-Za-z0-9-]{10,}\b/g, "[REDACTED_SLACK_TOKEN]")
+        .replace(/\bAIza[0-9A-Za-z_-]{35}\b/g, "[REDACTED_GOOGLE_KEY]")
+        .replace(/\beyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, "[REDACTED_JWT]")
+        .replace(/\b([a-z][a-z0-9+.-]*:\/\/[^\s:@/]+):[^\s:@/]+@/gi, "$1:[REDACTED]@")
+        .replace(/\b([A-Za-z0-9_.-]*(?:API[_-]?KEY|SECRET|TOKEN|PASSWORD|CLIENT[_-]?SECRET)[A-Za-z0-9_.-]*\s*[:=]\s*)([^\s"'`]+|"[^"\n]+"|'[^'\n]+')/gi, "$1[REDACTED]"));
+}
+function buildRedactedLines(rawLines) {
+    const mask = new Array(rawLines.length).fill(false);
+    let open = -1;
+    for (let i = 0; i < rawLines.length; i += 1) {
+        if (isBeginMarker(rawLines[i] ?? "")) {
+            open = i;
+            mask[i] = true;
+            continue;
+        }
+        if (open >= 0) {
+            mask[i] = true;
+            if (isEndMarker(rawLines[i] ?? "")) {
+                open = -1;
+            }
+        }
+    }
+    for (let j = 0; j < rawLines.length; j += 1) {
+        if (isEndMarker(rawLines[j] ?? "") && !mask[j]) {
+            let k = j;
+            while (k >= 0 && (rawLines[k] ?? "").trim() !== "") {
+                mask[k] = true;
+                k -= 1;
+            }
+        }
+    }
+    return rawLines.map((line, index) => mask[index] ? "[REDACTED_PRIVATE_KEY]" : redactSingleLineSecrets(line));
+}
+function publicHit(hit) {
+    return {
+        sourceId: hit.sourceId,
+        path: hit.path,
+        lineStart: hit.lineStart,
+        lineEnd: hit.lineEnd,
+        score: hit.score,
+        snippet: hit.snippet,
+        matchLine: hit.matchLine,
+        matchText: hit.matchText,
+        sha256: hit.sha256,
+    };
+}
+async function collectFiles(root, logger) {
+    const info = await stat(root).catch(() => null);
+    if (!info) {
+        return [];
+    }
+    if (info.isFile()) {
+        return TEXT_EXTENSIONS.has(path.extname(root)) ? [root] : [];
+    }
+    if (!info.isDirectory()) {
+        return [];
+    }
+    const entries = await readdir(root, { withFileTypes: true });
+    const files = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") || entry.name === "node_modules") {
+            continue;
+        }
+        const child = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            files.push(...await collectFiles(child, logger));
+        }
+        else if (entry.isFile() && TEXT_EXTENSIONS.has(path.extname(entry.name))) {
+            files.push(child);
+        }
+        else if (entry.isSymbolicLink()) {
+            logger?.warn?.(`native-memory-citations: skipped symlink during search: ${child}`);
+        }
+    }
+    return files;
+}
+function terms(query) {
+    return Array.from(new Set(query
+        .toLowerCase()
+        .split(/[^a-z0-9_@.+-]+/g)
+        .map((term) => term.trim())
+        .filter((term) => term.length >= 2 && !STOPWORDS.has(term))));
+}
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function buildMatchers(queryTerms) {
+    return queryTerms.map((term) => {
+        const weight = term.length >= 5 ? 3 : 1;
+        if (term.length >= 4) {
+            return { test: (lower) => lower.includes(term), weight };
+        }
+        const re = new RegExp(`(?:^|[^a-z0-9])${escapeRegExp(term)}(?:[^a-z0-9]|$)`);
+        return { test: (lower) => re.test(lower), weight };
+    });
+}
+function scoreLine(line, matchers) {
+    const lower = line.toLowerCase();
+    let score = 0;
+    for (const matcher of matchers) {
+        if (matcher.test(lower)) {
+            score += matcher.weight;
+        }
+    }
+    return score;
+}
+async function loadFile(file, maxFileBytes, logger) {
+    const info = await stat(file).catch(() => null);
+    if (!info || !info.isFile()) {
+        fileCache.delete(file);
+        return null;
+    }
+    if (info.size > maxFileBytes) {
+        fileCache.delete(file);
+        logger?.warn?.(`native-memory-citations: skipped oversized file: ${file}`);
+        return null;
+    }
+    const cached = fileCache.get(file);
+    if (cached && cached.mtimeMs === info.mtimeMs && cached.size === info.size) {
+        fileCache.delete(file);
+        fileCache.set(file, cached);
+        return cached;
+    }
+    const rawText = await readFile(file, "utf8").catch(() => "");
+    if (!rawText.trim()) {
+        fileCache.delete(file);
+        return null;
+    }
+    const rawLines = rawText.split(/\r?\n/g);
+    const loaded = {
+        mtimeMs: info.mtimeMs,
+        size: info.size,
+        rawText,
+        rawLines,
+        redactedLines: buildRedactedLines(rawLines),
+        sha256: sha256Text(rawText),
+    };
+    fileCache.set(file, loaded);
+    if (fileCache.size > FILE_CACHE_MAX) {
+        const oldest = fileCache.keys().next().value;
+        if (oldest !== undefined) {
+            fileCache.delete(oldest);
+        }
+    }
+    return loaded;
+}
+function mergeRegions(matches, contextLines, lineCount) {
+    const regions = [];
+    let current = null;
+    for (const match of matches) {
+        const start = Math.max(0, match.index - contextLines);
+        const end = Math.min(lineCount - 1, match.index + contextLines);
+        const currentLineCount = current ? current.end - current.start + 1 : 0;
+        if (current && start <= current.end + 1 && currentLineCount < MAX_REGION_LINES) {
+            current.end = Math.max(current.end, end);
+            current.score += match.score;
+            if (match.score > current.anchorScore) {
+                current.anchorScore = match.score;
+                current.anchorIndex = match.index;
+            }
+        }
+        else {
+            if (current) {
+                regions.push(current);
+            }
+            current = { start, end, score: match.score, anchorIndex: match.index, anchorScore: match.score };
+        }
+    }
+    if (current) {
+        regions.push(current);
+    }
+    return regions;
+}
+async function searchMemoryInternal(query, options = {}) {
+    const config = options.config ?? {};
+    const queryTerms = terms(query);
+    options.signal?.throwIfAborted();
+    const matchers = buildMatchers(queryTerms);
+    if (matchers.length === 0) {
+        return [];
+    }
+    const limit = clampInt(options.limit, 8, 1, 50);
+    const contextLines = clampInt(options.contextLines, 2, 0, 8);
+    const fileSizeLimit = maxFileBytes(config);
+    const files = (await Promise.all(allowedRoots(config).map((root) => collectFiles(root, options.logger)))).flat();
+    const hits = [];
+    for (let i = 0; i < files.length; i += SCAN_CONCURRENCY) {
+        options.signal?.throwIfAborted();
+        const batch = files.slice(i, i + SCAN_CONCURRENCY);
+        const batchHits = await Promise.all(batch.map(async (file) => {
+            options.signal?.throwIfAborted();
+            const loaded = await loadFile(file, fileSizeLimit, options.logger);
+            if (!loaded) {
+                return [];
+            }
+            const { rawLines, redactedLines, sha256 } = loaded;
+            const matches = [];
+            for (let index = 0; index < rawLines.length; index += 1) {
+                if (index % 512 === 0) {
+                    options.signal?.throwIfAborted();
+                }
+                const score = scoreLine(rawLines[index] ?? "", matchers);
+                if (score > 0) {
+                    matches.push({ index, score });
+                }
+            }
+            if (matches.length === 0) {
+                return [];
+            }
+            const sourceId = sourceIdForPath(config, file);
+            return mergeRegions(matches, contextLines, rawLines.length).map((region) => {
+                const rawSnippet = rawLines.slice(region.start, region.end + 1).join("\n").slice(0, MAX_SNIPPET_CHARS).trim();
+                const redactedSnippet = redactedLines
+                    .slice(region.start, region.end + 1)
+                    .join("\n")
+                    .slice(0, MAX_SNIPPET_CHARS)
+                    .trim();
+                const distinctTerms = matchedTermCount(rawSnippet, matchers);
+                const rawMatchText = (rawLines[region.anchorIndex] ?? "").slice(0, MAX_LINE_CHARS).trim();
+                return {
+                    sourceId,
+                    path: sourceId,
+                    lineStart: region.start + 1,
+                    lineEnd: region.end + 1,
+                    score: distinctTerms * 100 + Math.min(region.score, 50),
+                    snippet: redactedSnippet,
+                    matchLine: region.anchorIndex + 1,
+                    matchText: (redactedLines[region.anchorIndex] ?? "").slice(0, MAX_LINE_CHARS).trim(),
+                    sha256,
+                    rawSnippet,
+                    rawMatchText,
+                };
+            });
+        }));
+        for (const fileHits of batchHits) {
+            hits.push(...fileHits);
+        }
+    }
+    const sortedHits = hits
+        .sort((a, b) => b.score - a.score || a.path.localeCompare(b.path) || a.lineStart - b.lineStart)
+        .slice(0, limit);
+    options.logger?.debug?.(`native-memory-citations: scanned ${files.length} files, returned ${sortedHits.length} hits`);
+    return sortedHits;
+}
+export async function searchMemory(query, options = {}) {
+    return (await searchMemoryInternal(query, options)).map(publicHit);
+}
+export async function fetchMemorySource(input, config = {}) {
+    const requested = input.sourceId || input.filePath;
+    if (!requested) {
+        throw new Error("sourceId or filePath is required");
+    }
+    const file = await toSafePath(config, requested);
+    const sourceId = sourceIdForPath(config, file);
+    if (hasHiddenPathSegment(sourceId)) {
+        throw new Error(`Path includes a hidden memory segment: ${sourceId}`);
+    }
+    if (!isTextFile(file)) {
+        throw new Error(`Path is not an approved text memory file: ${sourceId}`);
+    }
+    const info = await stat(file).catch(() => null);
+    const fileSizeLimit = maxFileBytes(config);
+    if (!info || !info.isFile()) {
+        throw new Error(`Path is not a readable memory file: ${sourceId}`);
+    }
+    if (info.size > fileSizeLimit) {
+        throw new Error(`Memory file exceeds maxFileBytes: ${sourceId}`);
+    }
+    const loaded = await loadFile(file, fileSizeLimit);
+    if (!loaded) {
+        throw new Error(`Path is not a readable memory file: ${sourceId}`);
+    }
+    const { rawLines, redactedLines, sha256 } = loaded;
+    const lineStart = clampInt(input.lineStart, 1, 1, rawLines.length);
+    const lineEnd = clampInt(input.lineEnd, rawLines.length, lineStart, rawLines.length);
+    const maxChars = clampInt(input.maxChars, DEFAULT_FETCH_CHARS, 256, MAX_FETCH_CHARS);
+    const content = redactedLines.slice(lineStart - 1, lineEnd).join("\n").slice(0, maxChars);
+    const expectedSha256 = input.expectedSha256?.trim().toLowerCase();
+    const stale = Boolean(expectedSha256 && expectedSha256 !== sha256);
+    return {
+        sourceId,
+        path: sourceId,
+        lineStart,
+        lineEnd,
+        citation: `${sourceId}:${lineStart}`,
+        content,
+        sha256,
+        ...(stale
+            ? {
+                stale: true,
+                staleMessage: `Citation hash mismatch for ${sourceId}: expected ${expectedSha256}, current ${sha256}`,
+            }
+            : {}),
+    };
+}
+function extractSentences(snippet, matchers) {
+    return snippet
+        .split(/(?<=[.!?])\s+|\n+/g)
+        .map((sentence) => sentence.trim())
+        .filter(Boolean)
+        .map((sentence, index) => ({ sentence, index, score: scoreLine(sentence, matchers) }))
+        .filter((item) => item.score > 0)
+        .sort((a, b) => b.score - a.score || a.index - b.index)
+        .map((item) => item.sentence)
+        .slice(0, 2);
+}
+function matchedTermCount(snippet, matchers) {
+    const lower = snippet.toLowerCase();
+    return matchers.filter((matcher) => matcher.test(lower)).length;
+}
+function requiredMatchedTerms(queryTerms) {
+    if (queryTerms.length <= 1) {
+        return queryTerms.length;
+    }
+    return Math.min(queryTerms.length, Math.max(2, Math.ceil(queryTerms.length * ANSWER_MIN_TERM_RATIO)));
+}
+export async function answerFromMemory(query, options = {}) {
+    const queryTerms = terms(query);
+    const matchers = buildMatchers(queryTerms);
+    const hits = await searchMemoryInternal(query, {
+        limit: options.limit ?? 6,
+        contextLines: 2,
+        config: options.config,
+        signal: options.signal,
+        logger: options.logger,
+    });
+    const distinctTermsMatched = matchers.filter((matcher) => hits.some((hit) => matcher.test(hit.rawSnippet.toLowerCase()))).length;
+    const requiredDistinctTerms = requiredMatchedTerms(queryTerms);
+    const topScore = hits[0]?.score ?? 0;
+    const supportingHits = hits.filter((hit) => matchedTermCount(hit.rawSnippet, matchers) >= requiredDistinctTerms);
+    const hasSupportingHit = supportingHits.length > 0;
+    const confident = hits.length > 0
+        && topScore >= ANSWER_MIN_SCORE
+        && distinctTermsMatched >= requiredDistinctTerms
+        && hasSupportingHit;
+    if (!confident) {
+        return {
+            answer: "I did not find a sufficiently specific cited memory source for that.",
+            citations: [],
+            known: false,
+        };
+    }
+    const points = [];
+    for (const hit of supportingHits.slice(0, 1)) {
+        const sentences = extractSentences(hit.snippet, matchers);
+        const text = hit.matchText || sentences[0] || hit.snippet.split(/\n+/g).find(Boolean) || "";
+        if (text.trim()) {
+            points.push(`- ${text.trim()} [${hit.path}:${hit.matchLine}]`);
+        }
+    }
+    return {
+        answer: points.length > 0
+            ? points.join("\n")
+            : `Found cited memory, but no concise extractive answer could be formed. Start with ${supportingHits[0]?.path}:${supportingHits[0]?.matchLine ?? supportingHits[0]?.lineStart}.`,
+        citations: supportingHits.map(publicHit),
+        known: true,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("openclaw/plugin-sdk/tool-plugin").DefinedToolPluginEntry;
+export default _default;

package/dist/index.js

@@ -0,0 +1,72 @@
+import { Type } from "typebox";
+import { defineToolPlugin } from "openclaw/plugin-sdk/tool-plugin";
+import { answerFromMemory, fetchMemorySource, searchMemory } from "./core.js";
+// Declared config schema. Without this, OpenClaw applies a strict empty-object
+// schema and rejects every config key below. The generated manifest is produced
+// from this by `openclaw plugins build`; do not hand-edit it.
+const configSchema = Type.Object({
+    workspace: Type.Optional(Type.String({
+        description: "Absolute path to the OpenClaw workspace. Defaults to $OPENCLAW_WORKSPACE or ~/.openclaw/workspace.",
+    })),
+    allowedRoots: Type.Optional(Type.Array(Type.String(), {
+        description: "Workspace-relative memory roots to search. Overrides the built-in default set.",
+    })),
+    sharedMode: Type.Optional(Type.Boolean({ description: "When true, exclude the private MEMORY.md from the default root set." })),
+    maxFileBytes: Type.Optional(Type.Number({
+        description: "Per-file size cap in bytes. Files larger than this are skipped. Default 1048576.",
+    })),
+}, { additionalProperties: false });
+export default defineToolPlugin({
+    id: "native-memory-citations",
+    name: "Native Memory Citations",
+    description: "Search and fetch local OpenClaw memory with source citations and extractive cited answers.",
+    configSchema,
+    tools: (tool) => [
+        tool({
+            name: "native_memory_search",
+            label: "Memory Search (cited)",
+            description: "Search approved local memory roots and return snippets with source paths and line numbers.",
+            parameters: Type.Object({
+                query: Type.String({ description: "Search query." }),
+                limit: Type.Optional(Type.Number({ description: "Maximum hits to return. Default 8, max 50." })),
+                contextLines: Type.Optional(Type.Number({ description: "Context lines around each hit. Default 2, max 8." })),
+            }),
+            execute: async ({ query, limit, contextLines }, config, context) => {
+                context.signal?.throwIfAborted();
+                return searchMemory(query, { limit, contextLines, config, signal: context.signal, logger: context.api.logger });
+            },
+        }),
+        tool({
+            name: "native_memory_fetch",
+            label: "Memory Fetch (cited)",
+            description: "Fetch cited local memory content by sourceId/path and optional line range.",
+            parameters: Type.Object({
+                sourceId: Type.Optional(Type.String({ description: "Source id returned by native_memory_search." })),
+                filePath: Type.Optional(Type.String({ description: "Workspace-relative path inside an allowed memory root." })),
+                lineStart: Type.Optional(Type.Number({ description: "1-based starting line." })),
+                lineEnd: Type.Optional(Type.Number({ description: "1-based ending line." })),
+                maxChars: Type.Optional(Type.Number({ description: "Maximum characters returned. Default 8000." })),
+                expectedSha256: Type.Optional(Type.String({
+                    description: "Optional SHA-256 from a prior citation. When it differs from the current file hash, the result is marked stale.",
+                })),
+            }),
+            execute: async (input, config, context) => {
+                context.signal?.throwIfAborted();
+                return fetchMemorySource(input, config);
+            },
+        }),
+        tool({
+            name: "native_memory_answer",
+            label: "Memory Answer (cited)",
+            description: "Answer from approved local memory using extractive snippets with citations. Says when no cited memory is found.",
+            parameters: Type.Object({
+                query: Type.String({ description: "Question to answer from local memory." }),
+                limit: Type.Optional(Type.Number({ description: "Maximum cited search hits to consider. Default 6." })),
+            }),
+            execute: async ({ query, limit }, config, context) => {
+                context.signal?.throwIfAborted();
+                return answerFromMemory(query, { limit, config, signal: context.signal, logger: context.api.logger });
+            },
+        }),
+    ],
+});

package/openclaw.plugin.json

@@ -0,0 +1,41 @@
+{
+  "id": "native-memory-citations",
+  "activation": {
+    "onStartup": true
+  },
+  "name": "Native Memory Citations",
+  "description": "Search and fetch local OpenClaw memory with source citations and extractive cited answers.",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "workspace": {
+        "type": "string",
+        "description": "Absolute path to the OpenClaw workspace. Defaults to $OPENCLAW_WORKSPACE or ~/.openclaw/workspace."
+      },
+      "allowedRoots": {
+        "type": "array",
+        "items": {
+          "type": "string"
+        },
+        "description": "Workspace-relative memory roots to search. Overrides the built-in default set."
+      },
+      "sharedMode": {
+        "type": "boolean",
+        "description": "When true, exclude the private MEMORY.md from the default root set."
+      },
+      "maxFileBytes": {
+        "type": "number",
+        "description": "Per-file size cap in bytes. Files larger than this are skipped. Default 1048576."
+      }
+    },
+    "additionalProperties": false
+  },
+  "version": "0.1.0",
+  "contracts": {
+    "tools": [
+      "native_memory_search",
+      "native_memory_fetch",
+      "native_memory_answer"
+    ]
+  }
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@ngo-a/native-memory-citations",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Native OpenClaw plugin for cited local memory search and retrieval.",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "NGO-A <ngo-a@users.noreply.github.com>",
+  "homepage": "https://github.com/NGO-A/native-memory-citations#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NGO-A/native-memory-citations.git"
+  },
+  "bugs": {
+    "url": "https://github.com/NGO-A/native-memory-citations/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "memory",
+    "citations",
+    "search",
+    "retrieval"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "plugin:build": "npm run build && openclaw plugins build --entry ./dist/index.js",
+    "plugin:build:check": "npm run build && openclaw plugins build --entry ./dist/index.js --check",
+    "plugin:validate": "npm run plugin:build && openclaw plugins validate --entry ./dist/index.js",
+    "test": "vitest run --dir src --no-file-parallelism"
+  },
+  "dependencies": {
+    "typebox": "1.1.39"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.0",
+    "openclaw": "2026.6.8",
+    "typescript": "^5.9.0",
+    "vitest": "^3.2.0"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.5.17"
+  }
+}