@theihtisham/agent-shadow-brain 7.1.0 → 7.1.4

package/dist/brain/feature-settings.js

@@ -0,0 +1,242 @@
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { matchesFileIdentity } from './file-identity.js';
+export const FEATURE_DEFINITIONS = [
+    {
+        id: 'contextAssembly',
+        label: 'Context packs',
+        description: 'Assemble project memories into a bounded, explained context pack.',
+        defaultEnabled: true,
+    },
+    {
+        id: 'crossProjectContext',
+        label: 'Cross-project context',
+        description: 'Allow context requests to include memories from other projects when explicitly selected.',
+        defaultEnabled: false,
+    },
+    {
+        id: 'automaticBriefing',
+        label: 'Session briefings',
+        description: 'Generate the automatic project briefing at session start.',
+        defaultEnabled: true,
+    },
+    {
+        id: 'liveActivity',
+        label: 'Live dashboard activity',
+        description: 'Show activity updates and the recent activity feed in the dashboard.',
+        defaultEnabled: true,
+    },
+    {
+        id: 'activityRecording',
+        label: 'Record agent activity',
+        description: 'Record bounded tool timing and explicitly reported session phases. Arguments, memory text, and credentials are not captured.',
+        defaultEnabled: true,
+    },
+];
+export const DEFAULT_FEATURE_FLAGS = Object.freeze({
+    contextAssembly: true,
+    crossProjectContext: false,
+    automaticBriefing: true,
+    liveActivity: true,
+    activityRecording: true,
+});
+export const FEATURE_SETTINGS_FILENAME = 'feature-settings.json';
+const FEATURE_IDS = new Set(FEATURE_DEFINITIONS.map(({ id }) => id));
+const ORIGINAL_FEATURE_IDS = ['contextAssembly', 'crossProjectContext', 'automaticBriefing', 'liveActivity'];
+const LOCK_TIMEOUT_MS = 3000;
+const LOCK_POLL_MS = 20;
+export class FeatureSettingsError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'FeatureSettingsError';
+    }
+}
+function errorCode(error) {
+    return error?.code;
+}
+function isRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isFeatureMap(value) {
+    return isRecord(value) && Object.entries(value).every(([key, enabled]) => FEATURE_IDS.has(key) && typeof enabled === 'boolean');
+}
+function defaultSnapshot() {
+    return { schemaVersion: 1, revision: 0, updatedAt: null, features: { ...DEFAULT_FEATURE_FLAGS } };
+}
+function parseSnapshot(raw) {
+    try {
+        const data = JSON.parse(raw);
+        if (isRecord(data) && data.schemaVersion === 1 && typeof data.revision === 'number' &&
+            Number.isSafeInteger(data.revision) && data.revision >= 1 &&
+            typeof data.updatedAt === 'string' && Number.isFinite(Date.parse(data.updatedAt)) &&
+            isFeatureMap(data.features) && ORIGINAL_FEATURE_IDS.every(id => Object.hasOwn(data.features, id)) &&
+            [FEATURE_IDS.size - 1, FEATURE_IDS.size].includes(Object.keys(data.features).length)) {
+            return {
+                schemaVersion: 1, revision: data.revision, updatedAt: data.updatedAt,
+                features: { ...DEFAULT_FEATURE_FLAGS, ...data.features },
+            };
+        }
+    }
+    catch { /* Use a safe diagnostic without stored contents. */ }
+    throw new FeatureSettingsError('FEATURE_SETTINGS_INVALID_STORE', 'Feature settings are malformed or use an unsupported schema.');
+}
+/** Read and patch the local feature settings file without accessing provider configuration. */
+export class FeatureSettingsStore {
+    constructor(options = {}) {
+        this.filePath = path.resolve(options.filePath ?? path.join(os.homedir(), '.shadow-brain', FEATURE_SETTINGS_FILENAME));
+        this.lockTimeoutMs = typeof options.lockTimeoutMs === 'number' && Number.isFinite(options.lockTimeoutMs)
+            ? Math.max(0, Math.min(options.lockTimeoutMs, 60000))
+            : LOCK_TIMEOUT_MS;
+    }
+    get() {
+        let raw;
+        try {
+            const info = fs.lstatSync(this.filePath, { throwIfNoEntry: false });
+            if (!info)
+                return defaultSnapshot();
+            if (!info.isFile() || info.isSymbolicLink() || info.nlink !== 1) {
+                throw new FeatureSettingsError('FEATURE_SETTINGS_INVALID_STORE', 'Feature settings must be a regular local file.');
+            }
+            raw = fs.readFileSync(this.filePath, 'utf8');
+        }
+        catch (error) {
+            if (error instanceof FeatureSettingsError)
+                throw error;
+            throw new FeatureSettingsError('FEATURE_SETTINGS_READ_FAILED', 'Could not read feature settings.');
+        }
+        return parseSnapshot(raw);
+    }
+    isEnabled(id) {
+        if (!FEATURE_IDS.has(id)) {
+            throw new FeatureSettingsError('FEATURE_SETTINGS_INVALID_PATCH', 'Unknown feature setting.');
+        }
+        return this.get().features[id];
+    }
+    async update(patch, expectedRevision) {
+        if (!isFeatureMap(patch) || (expectedRevision !== undefined &&
+            (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0))) {
+            throw new FeatureSettingsError('FEATURE_SETTINGS_INVALID_PATCH', 'Feature settings accept only known feature IDs and boolean values.');
+        }
+        const changes = { ...patch };
+        if (!Object.keys(changes).length)
+            return this.checkRevision(this.get(), expectedRevision);
+        try {
+            fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        }
+        catch {
+            throw new FeatureSettingsError('FEATURE_SETTINGS_WRITE_FAILED', 'Could not open the feature settings directory.');
+        }
+        const release = await this.acquireLock();
+        try {
+            const current = this.checkRevision(this.get(), expectedRevision);
+            if (Object.keys(changes).every(id => changes[id] === current.features[id]))
+                return current;
+            if (current.revision === Number.MAX_SAFE_INTEGER) {
+                throw new FeatureSettingsError('FEATURE_SETTINGS_INVALID_STORE', 'Feature settings revision has reached its limit.');
+            }
+            const next = {
+                schemaVersion: 1,
+                revision: current.revision + 1,
+                updatedAt: new Date().toISOString(),
+                features: { ...current.features, ...changes },
+            };
+            this.replace(next);
+            return next;
+        }
+        finally {
+            release();
+        }
+    }
+    checkRevision(snapshot, expectedRevision) {
+        if (expectedRevision !== undefined && expectedRevision !== snapshot.revision) {
+            throw new FeatureSettingsError('FEATURE_SETTINGS_CONFLICT', 'Feature settings changed. Refresh them and retry the update.');
+        }
+        return snapshot;
+    }
+    async acquireLock() {
+        const lock = this.filePath + '.lock';
+        const deadline = performance.now() + this.lockTimeoutMs;
+        for (;;) {
+            let fd;
+            try {
+                fd = fs.openSync(lock, 'wx', 0o600);
+            }
+            catch (error) {
+                if (errorCode(error) !== 'EEXIST') {
+                    throw new FeatureSettingsError('FEATURE_SETTINGS_LOCK_FAILED', 'Could not acquire the feature settings lock.');
+                }
+                const remaining = deadline - performance.now();
+                if (remaining <= 0)
+                    break;
+                await delay(Math.min(remaining, LOCK_POLL_MS));
+                if (performance.now() >= deadline)
+                    break;
+                continue;
+            }
+            let owner;
+            try {
+                owner = fs.fstatSync(fd, { bigint: true });
+            }
+            catch {
+                try {
+                    fs.closeSync(fd);
+                }
+                catch { /* Preserve the original lock error. */ }
+                throw new FeatureSettingsError('FEATURE_SETTINGS_LOCK_FAILED', 'Could not identify the feature settings lock.');
+            }
+            return () => {
+                try {
+                    fs.closeSync(fd);
+                    const current = fs.lstatSync(lock, { bigint: true, throwIfNoEntry: false });
+                    if (!matchesFileIdentity(lock, owner, current)) {
+                        throw new Error('Lock ownership changed.');
+                    }
+                    fs.unlinkSync(lock);
+                }
+                catch {
+                    throw new FeatureSettingsError('FEATURE_SETTINGS_LOCK_FAILED', 'Could not release the feature settings lock.');
+                }
+            };
+        }
+        throw new FeatureSettingsError('FEATURE_SETTINGS_LOCK_TIMEOUT', 'Timed out waiting for the feature settings lock.');
+    }
+    replace(snapshot) {
+        const temporary = this.filePath + '.' + randomUUID() + '.tmp';
+        let created = false;
+        try {
+            const fd = fs.openSync(temporary, 'wx', 0o600);
+            created = true;
+            try {
+                fs.writeFileSync(fd, JSON.stringify(snapshot, null, 2) + '\n');
+                fs.fsyncSync(fd);
+            }
+            finally {
+                fs.closeSync(fd);
+            }
+            fs.renameSync(temporary, this.filePath);
+            created = false;
+        }
+        catch {
+            throw new FeatureSettingsError('FEATURE_SETTINGS_WRITE_FAILED', 'Could not save feature settings.');
+        }
+        finally {
+            if (created) {
+                try {
+                    fs.unlinkSync(temporary);
+                }
+                catch { /* Preserve the original write error. */ }
+            }
+        }
+    }
+}
+export function getFeatureSettings() {
+    return new FeatureSettingsStore();
+}
+//# sourceMappingURL=feature-settings.js.map

package/dist/brain/feature-settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-settings.js","sourceRoot":"","sources":["../../src/brain/feature-settings.ts"],"names":[],"mappings":"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"}

package/dist/brain/file-identity.d.ts

@@ -0,0 +1,4 @@
+import * as fs from 'node:fs';
+/** Match a regular opened file to its current project or lock path. */
+export declare function matchesFileIdentity(filename: string, handle: fs.BigIntStats, named: fs.BigIntStats | undefined): boolean;
+//# sourceMappingURL=file-identity.d.ts.map

package/dist/brain/file-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-identity.d.ts","sourceRoot":"","sources":["../../src/brain/file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,uEAAuE;AACvE,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC,WAAW,GAAG,SAAS,GAAG,OAAO,CAiBxH"}

package/dist/brain/file-identity.js

@@ -0,0 +1,27 @@
+import * as fs from 'node:fs';
+/** Match a regular opened file to its current project or lock path. */
+export function matchesFileIdentity(filename, handle, named) {
+    if (!named?.isFile() || !handle.isFile() || handle.nlink !== 1n || named.nlink !== 1n || handle.ino === 0n || named.ino !== handle.ino)
+        return false;
+    if (named.dev === handle.dev)
+        return true;
+    // Some Windows Node releases report device zero for path stats, but expose the volume through an open handle.
+    if (process.platform !== 'win32' || named.dev !== 0n || handle.dev === 0n)
+        return false;
+    let fd;
+    try {
+        fd = fs.openSync(filename, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW ?? 0));
+        const reopened = fs.fstatSync(fd, { bigint: true });
+        const current = fs.lstatSync(filename, { bigint: true, throwIfNoEntry: false });
+        return reopened.isFile() && reopened.nlink === 1n && reopened.dev === handle.dev && reopened.ino === handle.ino &&
+            current?.isFile() === true && current.nlink === 1n && current.dev === named.dev && current.ino === named.ino;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
+}
+//# sourceMappingURL=file-identity.js.map

package/dist/brain/file-identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-identity.js","sourceRoot":"","sources":["../../src/brain/file-identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAE9B,uEAAuE;AACvE,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,MAAsB,EAAE,KAAiC;IAC7G,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,MAAM,CAAC,KAAK,KAAK,EAAE,IAAI,KAAK,CAAC,KAAK,KAAK,EAAE,IAAI,MAAM,CAAC,GAAG,KAAK,EAAE,IAAI,KAAK,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG;QAAE,OAAO,KAAK,CAAC;IACrJ,IAAI,KAAK,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAC1C,8GAA8G;IAC9G,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,KAAK,CAAC,GAAG,KAAK,EAAE,IAAI,MAAM,CAAC,GAAG,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACxF,IAAI,EAAsB,CAAC;IAC3B,IAAI,CAAC;QACH,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,EAAE,EAAE,CAAC,SAAS,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC,SAAS,CAAC,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC;QACnF,MAAM,QAAQ,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;QACpD,MAAM,OAAO,GAAG,EAAE,CAAC,SAAS,CAAC,QAAQ,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,cAAc,EAAE,KAAK,EAAE,CAAC,CAAC;QAChF,OAAO,QAAQ,CAAC,MAAM,EAAE,IAAI,QAAQ,CAAC,KAAK,KAAK,EAAE,IAAI,QAAQ,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG,IAAI,QAAQ,CAAC,GAAG,KAAK,MAAM,CAAC,GAAG;YAC7G,OAAO,EAAE,MAAM,EAAE,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,KAAK,EAAE,IAAI,OAAO,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,KAAK,KAAK,CAAC,GAAG,CAAC;IACjH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;YAAS,CAAC;QACT,IAAI,EAAE,KAAK,SAAS;YAAE,EAAE,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC;IACzC,CAAC;AACH,CAAC"}

package/dist/brain/global-brain.d.ts

@@ -1,4 +1,5 @@
 import { AgentTool, BrainTimelineEvent, GlobalBrainConfig, GlobalBrainStats, GlobalBrainStorageHealth, GlobalEntry, ScoredGlobalEntry } from '../types.js';
+import { type ContextSearchMemory } from './context-retrieval.js';
 type EntryInput = Omit<GlobalEntry, 'id' | 'createdAt' | 'lastAccessed' | 'accessCount'>;
 interface RecallOptions {
     projectId?: string;
@@ -7,7 +8,10 @@ interface RecallOptions {
     keywords?: string[];
     limit?: number;
     minImportance?: number;
+    /** Exclude curated memories before matching, corroboration, and candidate limits. */
+    excludeIds?: ReadonlySet<string>;
 }
+export declare function normalizeRecallKeywords(keywords: unknown): string[];
 /** Local JSON store shared by cooperating Global Brain processes. */
 export declare class GlobalBrain {
     private static instance;
@@ -24,6 +28,10 @@ export declare class GlobalBrain {
     private lastError;
     private constructor();
     static getInstance(config?: Partial<GlobalBrainConfig>): GlobalBrain;
+    /** Explicit independent store. Does not replace or consult the global singleton. */
+    static createIsolated(config: Partial<GlobalBrainConfig> & {
+        dbPath: string;
+    }): GlobalBrain;
     init(): Promise<void>;
     private initialize;
     /** Generate a stable project ID from absolute path. */
@@ -33,9 +41,10 @@ export declare class GlobalBrain {
     /** Queue a write. A failed attempt resolves false and retains the entry for a later sync. */
     write(entry: EntryInput): Promise<boolean>;
     /** Stage an entry for later sync and return its ID immediately. */
-    writeSync(entry: EntryInput): string;
+    writeSync(entry: EntryInput, id?: string): string;
     private requireWritable;
     private prepareEntry;
+    private requireSameExplicitEntry;
     private publishWrite;
     /** Recall matching entries across projects and agents. */
     recall(opts?: RecallOptions): GlobalEntry[];
@@ -43,6 +52,8 @@ export declare class GlobalBrain {
     recallScored(opts?: RecallOptions & {
         minConfidence?: number;
     }): ScoredGlobalEntry[];
+    /** Read the scoped fields used by context ranking without exposing mutable memory records. */
+    contextEntries(opts: Pick<RecallOptions, 'projectId' | 'minImportance' | 'excludeIds'>): IterableIterator<ContextSearchMemory>;
     private findMatches;
     private compareEntries;
     private recordRecall;
@@ -50,6 +61,12 @@ export declare class GlobalBrain {
     /** Bump an entry's access count without replacing its persisted snapshot. */
     touch(id: string): void;
     recallByIds(ids: string[]): GlobalEntry[];
+    /** Read one memory without exposing mutable in-memory state or recording a recall. */
+    getEntry(id: string): GlobalEntry | undefined;
+    /** Hash the actual read view, including staged entries, without committing or recording access. */
+    readFingerprint(projectId?: string): string;
+    /** Refresh the local read view without acknowledging or committing pending operations. */
+    refresh(): void;
     /** Chronological memory stream for dashboards and handoffs. */
     timeline(opts?: Pick<RecallOptions, 'projectId' | 'agentTool' | 'category' | 'limit'>): BrainTimelineEvent[];
     getStats(): GlobalBrainStats;

package/dist/brain/global-brain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"global-brain.d.ts","sourceRoot":"","sources":["../../src/brain/global-brain.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"global-brain.d.ts","sourceRoot":"","sources":["../../src/brain/global-brain.ts"],"names":[],"mappings":"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"}

package/dist/brain/global-brain.js

@@ -2,8 +2,11 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
+import { isDeepStrictEqual } from 'node:util';
 import { setTimeout as delay } from 'node:timers/promises';
 import { getBrainBus } from './brain-bus.js';
+import { contextSearchMemory } from './context-retrieval.js';
+import { matchesFileIdentity } from './file-identity.js';
 const DEFAULT_DB_PATH = path.join(os.homedir(), '.shadow-brain', 'global.json');
 const LOCK_TIMEOUT_MS = 5000;
 const LOCK_POLL_MS = 20;
@@ -89,7 +92,7 @@ function hydrateEntry(entry) {
 function normalizeText(value) {
     return value.trim().replace(/\s+/g, ' ').toLowerCase();
 }
-function normalizeKeywords(keywords) {
+export function normalizeRecallKeywords(keywords) {
     if (!Array.isArray(keywords))
         return [];
     const unique = new Set();
@@ -148,6 +151,12 @@ export class GlobalBrain {
         GlobalBrain.instance ?? (GlobalBrain.instance = new GlobalBrain(config));
         return GlobalBrain.instance;
     }
+    /** Explicit independent store. Does not replace or consult the global singleton. */
+    static createIsolated(config) {
+        if (typeof config.dbPath !== 'string' || !config.dbPath.trim())
+            throw new TypeError('An explicit memory-store path is required.');
+        return new GlobalBrain(config);
+    }
     async init() {
         this.initialize();
     }
@@ -211,9 +220,17 @@ export class GlobalBrain {
         });
     }
     /** Stage an entry for later sync and return its ID immediately. */
-    writeSync(entry) {
+    writeSync(entry, id) {
         this.requireWritable();
-        const stored = this.prepareEntry(entry);
+        if (id !== undefined && (typeof id !== 'string' || !/^[0-9a-f]{8}-(?:[0-9a-f]{4}-){3}[0-9a-f]{12}$/u.test(id))) {
+            throw new TypeError('An explicit memory ID must be a UUID.');
+        }
+        const stored = this.prepareEntry(entry, id);
+        const existing = this.entries.get(stored.id);
+        if (existing) {
+            this.requireSameExplicitEntry(existing, stored);
+            return stored.id;
+        }
         this.pendingOperations.push({ kind: 'add', entry: stored, queued: false });
         this.entries.set(stored.id, hydrateEntry(structuredClone(stored)));
         return stored.id;
@@ -224,12 +241,12 @@ export class GlobalBrain {
         if (this.shuttingDown)
             throw new Error('GlobalBrain is shutting down');
     }
-    prepareEntry(entry) {
+    prepareEntry(entry, id = crypto.randomUUID()) {
         const now = new Date();
         // Snapshot caller input now so later mutations or serialization errors cannot block a commit.
         try {
             const data = JSON.parse(JSON.stringify({
-                ...entry, id: crypto.randomUUID(), createdAt: now, lastAccessed: now, accessCount: 0,
+                ...entry, id, createdAt: now, lastAccessed: now, accessCount: 0,
             }));
             if (hasUniqueKeys([data], 'id', ['projectId', 'projectName', 'agentTool', 'category', 'content'])) {
                 return data;
@@ -238,6 +255,14 @@ export class GlobalBrain {
         catch { /* Report an invalid input without exposing its contents. */ }
         throw new StorageError('STORE_INVALID_ENTRY', 'The memory entry cannot be stored as JSON.');
     }
+    requireSameExplicitEntry(previous, next) {
+        const stable = ({ createdAt, lastAccessed, accessCount, ...entry }) => ({
+            ...entry, importance: boundedSignal(entry.importance), metadata: isRecord(entry.metadata) ? entry.metadata : {},
+        });
+        if (!isDeepStrictEqual(stable(previous), stable(next))) {
+            throw new StorageError('STORE_INVALID_ENTRY', 'This memory ID is already assigned to a different record.');
+        }
+    }
     publishWrite(entry) {
         try {
             getBrainBus().publish({
@@ -260,7 +285,7 @@ export class GlobalBrain {
     recall(opts = {}) {
         if (!this.initialized)
             return [];
-        const keywords = normalizeKeywords(opts.keywords);
+        const keywords = normalizeRecallKeywords(opts.keywords);
         const result = this.findMatches(opts, keywords)
             .sort((a, b) => b.relevance - a.relevance || this.compareEntries(a.entry, b.entry))
             .slice(0, nonNegativeInt(opts.limit, 20))
@@ -272,7 +297,7 @@ export class GlobalBrain {
     recallScored(opts = {}) {
         if (!this.initialized)
             return [];
-        const keywords = normalizeKeywords(opts.keywords);
+        const keywords = normalizeRecallKeywords(opts.keywords);
         const candidates = this.findMatches(opts, keywords);
         const evidence = new Map();
         for (const { entry } of candidates) {
@@ -280,6 +305,8 @@ export class GlobalBrain {
                 evidence.set(evidenceKey(entry), new Set());
         }
         for (const entry of this.entries.values()) {
+            if (opts.excludeIds?.has(entry.id))
+                continue;
             evidence.get(evidenceKey(entry))?.add(entry.agentTool);
         }
         const now = Date.now();
@@ -298,10 +325,25 @@ export class GlobalBrain {
         this.recordRecall(result.length);
         return result;
     }
+    /** Read the scoped fields used by context ranking without exposing mutable memory records. */
+    *contextEntries(opts) {
+        if (!this.initialized)
+            return;
+        const minImportance = boundedSignal(opts.minImportance);
+        for (const entry of this.entries.values()) {
+            if (opts.projectId && entry.projectId !== opts.projectId)
+                continue;
+            if (opts.excludeIds?.has(entry.id) || entry.importance < minImportance)
+                continue;
+            yield contextSearchMemory(entry);
+        }
+    }
     findMatches(opts, keywords) {
         const minImportance = boundedSignal(opts.minImportance);
         const matches = [];
         for (const entry of this.entries.values()) {
+            if (opts.excludeIds?.has(entry.id))
+                continue;
             if (opts.projectId && entry.projectId !== opts.projectId)
                 continue;
             if (opts.agentTool && entry.agentTool !== opts.agentTool)
@@ -392,6 +434,27 @@ export class GlobalBrain {
         }
         return out;
     }
+    /** Read one memory without exposing mutable in-memory state or recording a recall. */
+    getEntry(id) {
+        const entry = this.entries.get(id);
+        return entry ? structuredClone(entry) : undefined;
+    }
+    /** Hash the actual read view, including staged entries, without committing or recording access. */
+    readFingerprint(projectId) {
+        const hash = crypto.createHash('sha256');
+        for (const entry of this.entries.values()) {
+            if (projectId !== undefined && entry.projectId !== projectId)
+                continue;
+            hash.update(JSON.stringify(entry));
+            hash.update('\n');
+        }
+        return hash.digest('hex');
+    }
+    /** Refresh the local read view without acknowledging or committing pending operations. */
+    refresh() {
+        this.initialize();
+        this.refreshSnapshot();
+    }
     /** Chronological memory stream for dashboards and handoffs. */
     timeline(opts = {}) {
         if (!this.initialized)
@@ -541,7 +604,8 @@ export class GlobalBrain {
     refreshSnapshot() {
         try {
             const { data, sizeMB } = this.readLatestSnapshot();
-            this.adoptSnapshot(data, sizeMB, this.hydrateEntries(data));
+            const view = this.pendingOperations.length ? this.mergeOperations(data, this.pendingOperations) : data;
+            this.adoptSnapshot(view, sizeMB, this.hydrateEntries(view));
             if (this.lastError?.code !== 'STORE_LOCK_FAILED')
                 this.lastError = null;
         }
@@ -556,7 +620,10 @@ export class GlobalBrain {
         for (const operation of operations) {
             switch (operation.kind) {
                 case 'add': {
-                    if (!entries.has(operation.entry.id))
+                    const previous = entries.get(operation.entry.id);
+                    if (previous)
+                        this.requireSameExplicitEntry(previous, operation.entry);
+                    else
                         entries.set(operation.entry.id, operation.entry);
                     break;
                 }
@@ -650,7 +717,7 @@ export class GlobalBrain {
                 // A failed token write can leave partial bytes. Check the exclusive file's identity.
                 try {
                     const current = fs.lstatSync(lockPath, { bigint: true });
-                    if (identity && current.dev === identity.dev && current.ino === identity.ino)
+                    if (identity && matchesFileIdentity(lockPath, identity, current))
                         fs.unlinkSync(lockPath);
                 }
                 catch { /* report the lock initialization error */ }