memoir-cli 3.12.0 → 3.14.0

package/src/mcp.js

@@ -24,11 +24,17 @@ import {
   addQuestion,
   getMachineId,
 } from './session/state.js';
+import { appendEvent } from './events/log.js';
 import { renderSession } from './session/render.js';
 import { injectInto, detectAvailableTargets } from './session/inject.js';
 import { findDecisions } from './commands/why.js';
 import { matchDecisions, hideDecision } from './session/state.js';
 import { readMemoryFiles, searchMemories, formatRecallResults, withFrontmatterLists } from './memory/search.js';
+import { buildResumeBrief, formatResumeBrief } from './session/brief.js';
+import { rememberMemory, memoryRoot, forgetStoredMemory, readStoredMemories } from './memory/store.js';
+import { memoryFilename, relativeFile, readSafeFile } from './security/files.js';
+import { visibleMemory, sessionView } from './memory/scope.js';
+import { parseFrontmatter } from './commands/validate.js';
 import { capture as track } from './telemetry.js';
 import { createRequire } from 'module';
 
@@ -81,9 +87,17 @@ const _registerTool = server.tool.bind(server);
 server.tool = (name, ...rest) => {
   const handler = rest[rest.length - 1];
   if (typeof handler === 'function') {
-    rest[rest.length - 1] = (...args) => {
-      try { track('mcp_tool_used', { tool: name }); } catch {}
-      return handler(...args);
+    rest[rest.length - 1] = async (...args) => {
+      const started = Date.now();
+      let success = false;
+      try {
+        const result = await handler(...args);
+        success = result?.isError !== true;
+        return result;
+      } finally {
+        try { track('mcp_tool_used', { tool: name, success }); } catch {}
+        appendEvent('mcp_tool_used', { tool: name, success, ms: Date.now() - started }).catch(() => {});
+      }
     };
   }
   return _registerTool(name, ...rest);
@@ -135,97 +149,39 @@ server.tool(
 
 server.tool(
   'memoir_recall',
-  'Search across all AI tool memories, project configs, and session context for relevant information. Returns the matched passages (not file headers) from the best files, ranked by how well each file covers all your terms — aliases, names, and descriptions weigh more than body prose. Use this before answering questions about a project, a past decision, or a tool. Use memoir_read to see a whole file.',
+  'Search memories and decisions for the current or selected project, including shared memories. Hidden, deleted, superseded, and unrelated project records are excluded. Returns the matched passages (not file headers) from the best files, ranked by how well each file covers all your terms — aliases, names, and descriptions weigh more than body prose. Use this before answering questions about a project, a past decision, or a tool. Use memoir_read to see a whole file.',
   {
     query: z.string().describe('Search query — keywords or topic to find in memories. Multi-word queries rank files that match every word highest.'),
     limit: z.number().int().min(1).max(30).optional().describe('Max results to return (default 10)'),
+    project: z.string().optional().describe('Project directory or identity. Defaults to the current working project; shared memories are also included.'),
+    budget: z.number().int().min(256).max(16000).optional().describe('Total character budget for returned evidence (default 6000).'),
   },
-  async ({ query, limit }) => {
-    const res = await searchMemories(query, { limit: limit || 10 });
+  async ({ query, limit, project, budget }) => {
+    const res = await searchMemories(query, { limit: limit || 10, project, budget });
     return { content: [{ type: 'text', text: formatRecallResults(query, res) }] };
   }
 );
 
 server.tool(
   'memoir_remember',
-  'Save a memory to a specific AI tool\'s memory files. Use this to persist important context, decisions, or facts for future sessions. Give the file frontmatter (type, name, description) and ALWAYS pass aliases — the other names, nicknames, or phrasings someone might search for this under (e.g. a "vertical swipe feed" surface should carry aliases like "tiktok", "reels", "/tape"). Recall weights aliases heaviest; a memory without them can only be found by the exact words it happens to use.',
+  'Save a durable, project-scoped memory in Memoir. Returns a stable ID and revision. Use this to persist important context, decisions, or facts for future sessions. Give the file frontmatter (type, name, description) and ALWAYS pass aliases — the other names, nicknames, or phrasings someone might search for this under (e.g. a "vertical swipe feed" surface should carry aliases like "tiktok", "reels", "/tape"). Recall weights aliases heaviest; a memory without them can only be found by the exact words it happens to use.',
   {
     content: z.string().describe('The memory content to save (markdown, ideally with --- frontmatter: type, name, description)'),
     filename: z.string().describe('Filename for the memory (e.g. "auth-setup.md", "project-goals.md")'),
     aliases: z.array(z.string()).optional().describe('Other names/phrasings this memory should be findable under. Written into frontmatter `aliases:`. Strongly recommended.'),
     tags: z.array(z.string()).optional().describe('Topic tags. Written into frontmatter `tags:`.'),
-    tool: z.string().optional().describe('Which AI tool to save to: "claude", "gemini", "cursor", etc. Defaults to claude.'),
-    project: z.string().optional().describe('Project directory path to save a project-level memory (e.g. CLAUDE.md). If provided, saves to that project directory instead of global tool config.'),
+    tool: z.string().optional().describe('Originating tool, recorded as provenance. Memory is stored in Memoir and is readable across clients.'),
+    scope: z.enum(['project', 'shared']).optional().describe('Default project scope; shared is for deliberately reusable preferences across projects.'),
+    project: z.string().optional().describe('Project directory or identity for this memory. Defaults to the working project; does not modify project files.'),
   },
-  async ({ content, filename, aliases, tags, tool, project }) => {
-    content = withFrontmatterLists(content, { aliases, tags });
-    // Project-level memory
-    if (project) {
-      const projectDir = project.startsWith('/') ? project : path.join(home, project);
-      if (!(await fs.pathExists(projectDir))) {
-        return { content: [{ type: 'text', text: `Project directory not found: ${projectDir}` }] };
-      }
-
-      // Default to CLAUDE.md for project-level memories.
-      // Guards mirror the global branch below and memoir_read above:
-      // model-supplied filename must be a bare markdown name — no
-      // separators, no traversal — and must resolve inside the project
-      // dir. Without this, filename:".zshrc" appends to a shell rc
-      // (code execution on next shell) and "package.json" corrupts
-      // real files.
-      let targetFile = filename || 'CLAUDE.md';
-      if (!targetFile.endsWith('.md')) targetFile += '.md';
-      if (targetFile.includes('/') || targetFile.includes('\\') || targetFile.includes('..')) {
-        return { content: [{ type: 'text', text: `Invalid filename: ${filename} (must be a bare .md name)` }] };
-      }
-      const projBase = path.resolve(projectDir);
-      const targetPath = path.resolve(projBase, targetFile);
-      if (!targetPath.startsWith(projBase + path.sep)) {
-        return { content: [{ type: 'text', text: `Invalid filename: ${filename}` }] };
-      }
-
-      // Append to existing file or create new
-      if (await fs.pathExists(targetPath)) {
-        const existing = await fs.readFile(targetPath, 'utf8');
-        await fs.writeFile(targetPath, existing + '\n\n' + content);
-      } else {
-        await fs.writeFile(targetPath, content);
-      }
-
-      return {
-        content: [{ type: 'text', text: `Saved to ${targetPath}` }]
-      };
-    }
-
-    // Global tool memory
-    const toolKey = (tool || 'claude').toLowerCase();
-
-    // Find the right directory for the tool
-    let targetDir;
-    if (toolKey === 'claude') {
-      // Save to Claude's memory system
-      const claudeMemDir = path.join(home, '.claude', 'projects', '-Users-' + path.basename(home), 'memory');
-      await fs.ensureDir(claudeMemDir);
-      targetDir = claudeMemDir;
-    } else if (toolKey === 'gemini') {
-      targetDir = path.join(home, '.gemini');
-    } else if (toolKey === 'cursor') {
-      const cursorDir = process.platform === 'win32'
-        ? path.join(process.env.APPDATA || '', 'Cursor', 'User', 'rules')
-        : path.join(home, 'Library', 'Application Support', 'Cursor', 'User', 'rules');
-      await fs.ensureDir(cursorDir);
-      targetDir = cursorDir;
-    } else {
-      return { content: [{ type: 'text', text: `Unsupported tool for writing: ${toolKey}. Supported: claude, gemini, cursor` }] };
+  async ({ content, filename, aliases, tags, tool, project, scope }) => {
+    try {
+      memoryFilename(filename);
+      const saved = await rememberMemory({ content, filename, aliases, tags, tool, project, scope });
+      return { content: [{ type: 'text', text: 'Memory saved: ' + saved.id + ' (revision ' + saved.revision + ', project ' + saved.project + '). Read with tool "memoir" and filepath "' + saved.path + '".' }] };
+    } catch (err) {
+      return { isError: true, content: [{ type: 'text', text: err.message }] };
     }
-
-    if (!filename.endsWith('.md')) filename += '.md';
-    const targetPath = path.join(targetDir, filename);
-    await fs.writeFile(targetPath, content);
-
-    return {
-      content: [{ type: 'text', text: `Memory saved to ${targetPath}` }]
-    };
   }
 );
 
@@ -237,6 +193,11 @@ server.tool(
   },
   async ({ tool }) => {
     const allFiles = [];
+    if (!tool || tool.toLowerCase() === 'memoir') {
+      for (const file of await readStoredMemories()) {
+        if (visibleMemory(parseFrontmatter(file.content).fields)) allFiles.push({ tool: 'Memoir', icon: '🧠', path: file.path, size: file.content.length });
+      }
+    }
 
     for (const adapter of adapters) {
       if (tool) {
@@ -246,6 +207,7 @@ server.tool(
 
       const files = await readMemoryFiles(adapter);
       for (const f of files) {
+        if (!visibleMemory(f)) continue;
         allFiles.push({ tool: adapter.name, icon: adapter.icon, path: f.path, size: f.content.length });
       }
     }
@@ -282,35 +244,35 @@ server.tool(
   {
     tool: z.string().describe('Tool name: "claude", "gemini", "cursor", etc.'),
     filepath: z.string().describe('Relative file path within the tool\'s memory directory'),
+    project: z.string().optional().describe('Project directory or identity; defaults to the working project.'),
   },
-  async ({ tool, filepath }) => {
-    const toolKey = tool.toLowerCase();
-    const adapter = adapters.find(a => a.name.toLowerCase().includes(toolKey));
-
-    if (!adapter) {
-      return { content: [{ type: 'text', text: `Unknown tool: ${tool}. Available: ${adapters.map(a => a.name).join(', ')}` }] };
-    }
-
-    // Containment: filepath comes from the model, and the model reads
-    // attacker-influenceable text all day. Without this, "../.ssh/id_rsa"
-    // resolves outside the adapter dir and the file is returned verbatim.
-    const base = path.resolve(adapter.source);
-    const fullPath = path.resolve(base, filepath);
-    if (fullPath !== base && !fullPath.startsWith(base + path.sep)) {
-      return { content: [{ type: 'text', text: `Invalid path: ${filepath} (must stay inside ${adapter.name}'s directory)` }] };
-    }
-
-    if (!(await fs.pathExists(fullPath))) {
-      return { content: [{ type: 'text', text: `File not found: ${filepath} in ${adapter.name}` }] };
-    }
-
+  async ({ tool, filepath, project }) => {
     try {
-      const content = await fs.readFile(fullPath, 'utf8');
-      return {
-        content: [{ type: 'text', text: `── ${adapter.name} / ${filepath} ──\n\n${content}` }]
-      };
+      const rel = relativeFile(filepath);
+      const toolKey = tool.toLowerCase();
+      let root, name;
+      if (toolKey === 'memoir') {
+        if (!/^[a-f0-9]{64}\.md$/.test(rel)) throw new Error('Use the memory ID returned by remember or recall.');
+        root = memoryRoot;
+        name = 'Memoir';
+      } else {
+        const adapter = adapters.find(a => a.name.toLowerCase().includes(toolKey));
+        if (!adapter) throw new Error('Unknown memory tool');
+        const permitted = adapter.customExtract ? adapter.files.includes(rel) : adapter.filter(path.join(adapter.source, rel));
+        if (!permitted) throw new Error('This file is excluded from the memory adapter');
+        root = adapter.source;
+        name = adapter.name;
+      }
+      let content = (await readSafeFile(root, rel)).toString('utf8');
+      const { fields } = parseFrontmatter(content);
+      if (toolKey.includes('claude')) fields.claudeProjectKey = rel.match(/^projects\/([^/]+)\//)?.[1];
+      if (!visibleMemory(fields, { project })) throw new Error('This memory is hidden, expired, superseded, or belongs to another project.');
+      // Generated session blocks are projections; authoritative decisions are
+      // retrieved from state so old projections cannot bypass a deletion.
+      content = content.replace(/<!--\s*memoir:session-block[^>]*-->[\s\S]*?<!--\s*\/memoir:session-block\s*-->/g, '');
+      return { content: [{ type: 'text', text: '── ' + name + ' / ' + rel + ' ──\n\n' + content }] };
     } catch (err) {
-      return { content: [{ type: 'text', text: `Error reading file: ${err.message}` }] };
+      return { isError: true, content: [{ type: 'text', text: err.message }] };
     }
   }
 );
@@ -342,47 +304,19 @@ server.tool(
   'memoir_consolidate',
   'Analyze all AI tool memories for duplicates, stale files, contradictions, and bloat. Returns a consolidation report with actionable suggestions. Use this to help users keep their AI memory clean.',
   {
-    smart: z.boolean().optional().describe('Use AI (Gemini Flash) for deeper analysis — finds semantic duplicates, contradictions, and merge candidates. Requires GEMINI_API_KEY.'),
+    smart: z.boolean().optional().describe('Compatibility option. This MCP tool performs local analysis only; use memoir consolidate --smart in the CLI for external model analysis.'),
   },
   async ({ smart }) => {
-    // Collect all memory files
     const allFiles = [];
+    for (const file of await readStoredMemories()) {
+      if (visibleMemory(parseFrontmatter(file.content).fields)) allFiles.push({
+        ...file, size: file.content.length, mtime: Date.parse(parseFrontmatter(file.content).fields.updated) || 0,
+      });
+    }
     for (const adapter of adapters) {
-      const files = [];
-      if (adapter.customExtract) {
-        for (const file of adapter.files) {
-          const filePath = path.join(adapter.source, file);
-          if (await fs.pathExists(filePath)) {
-            try {
-              const content = await fs.readFile(filePath, 'utf8');
-              const stat = await fs.stat(filePath);
-              files.push({ path: file, fullPath: filePath, content, tool: adapter.name, icon: adapter.icon, mtime: stat.mtimeMs, size: content.length });
-            } catch {}
-          }
-        }
-      } else if (await fs.pathExists(adapter.source)) {
-        const walk = async (dir, prefix = '') => {
-          let entries;
-          try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; }
-          for (const entry of entries) {
-            const fullPath = path.join(dir, entry.name);
-            const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
-            if (entry.isDirectory()) {
-              if (adapter.filter(fullPath)) await walk(fullPath, relPath);
-            } else if (/\.(md|json|yml|yaml)$/.test(entry.name)) {
-              if (adapter.filter(fullPath)) {
-                try {
-                  const content = await fs.readFile(fullPath, 'utf8');
-                  const stat = await fs.stat(fullPath);
-                  files.push({ path: relPath, fullPath, content, tool: adapter.name, icon: adapter.icon, mtime: stat.mtimeMs, size: content.length });
-                } catch {}
-              }
-            }
-          }
-        };
-        await walk(adapter.source);
+      for (const doc of await readMemoryFiles(adapter)) {
+        if (visibleMemory(doc)) allFiles.push({ ...doc, size: doc.content.length, mtime: doc.mtimeMs });
       }
-      allFiles.push(...files);
     }
 
     if (allFiles.length === 0) {
@@ -473,36 +407,39 @@ async function refreshPinnedBlock() {
 
 server.tool(
   'memoir_set_goal',
-  'Set the current goal for this session. Use when the user states what they want to work on, or when a clear focus emerges. Pinned into CLAUDE.md so future sessions see it.',
+  'Set the current goal for this session. Use when the user states what they want to work on, or when a clear focus emerges. Available through the scoped session and resume tools.',
   { text: z.string().describe('The goal, one short sentence') },
   async ({ text }) => {
-    await addGoal(text);
+    const state = await addGoal(text);
     await refreshPinnedBlock();
-    return { content: [{ type: 'text', text: `Goal set: ${text}` }] };
+    const replaced = (state.replacedGoals || []).map((g) => `"${g.text}"`);
+    return { content: [{ type: 'text', text: `Goal set: ${text}${replaced.length ? `\nGoals list is full (3) — replaced: ${replaced.join('; ')}. Re-set it with memoir_set_goal if that was wrong.` : ''}` }] };
   }
 );
 
 server.tool(
   'memoir_add_next',
-  'Add a next action to the current session. Use when the user decides on a concrete next step, or when you finish something and the logical next move is clear.',
+  'Add a next action to the current session. Use when the user decides on a concrete next step, or when you finish something and the logical next move is clear. The list holds 8; when it is full the oldest item is PARKED (still shown in the pinned block, still completable), never dropped — the response names anything parked.',
   { text: z.string().describe('The action, one short imperative sentence') },
   async ({ text }) => {
-    await addNext(text);
+    const state = await addNext(text);
     await refreshPinnedBlock();
-    return { content: [{ type: 'text', text: `Next: ${text}` }] };
+    const parked = (state.justParked || []).map((p) => `"${p.text}"`);
+    return { content: [{ type: 'text', text: `Next: ${text}${parked.length ? `\nList was full — parked (still open, still in the block): ${parked.join('; ')}` : ''}` }] };
   }
 );
 
 server.tool(
   'memoir_complete_next',
-  'Mark a next action as complete (removes it from the pinned list). Match by substring — pass the relevant keywords, not the whole text.',
+  'Mark a next action as complete (removes it from the pinned list, parked items included). Match by substring — pass the relevant keywords, not the whole text.',
   { match: z.string().describe('Substring to match against existing next actions') },
   async ({ match }) => {
+    const count = (st) => st.current.next_actions.length + (st.current.parked_actions || []).length;
     const before = await readSession();
-    const beforeCount = before.current.next_actions.length;
+    const beforeCount = count(before);
     await completeNext(match);
     const after = await readSession();
-    const removed = beforeCount - after.current.next_actions.length;
+    const removed = beforeCount - count(after);
     await refreshPinnedBlock();
     return {
       content: [{
@@ -549,12 +486,12 @@ server.tool(
   'Show the current session state — goals, next actions, open questions, recent decisions, recent sessions across machines. Use this to catch up at the start of a session, or when you need to orient yourself on what was decided.',
   {},
   async () => {
-    const state = await readSession();
+    const state = sessionView(await readSession());
     const machine = await getMachineId();
     const goals = state.current.goals.map(g => `- ${g.text}`).join('\n') || '(none)';
     const nexts = state.current.next_actions.map(n => `- [ ] ${n.text}`).join('\n') || '(none)';
     const questions = state.current.open_questions.map(q => `- ${q.text}`).join('\n') || '(none)';
-    const decisions = state.current.decisions.slice(0, 5).map(d => {
+    const decisions = state.current.decisions.filter(d => visibleMemory(d)).slice(0, 5).map(d => {
       let line = `- ${d.text}`;
       if (d.why) line += ` — *${d.why}*`;
       return line;
@@ -626,10 +563,16 @@ server.tool(
   'memoir_forget',
   'Forget a recorded decision — permanently hides it from the pinned block, memoir_why, and every synced machine (an absolute tombstone; there is no un-forget). Use when the user says a decision is wrong, obsolete, or was captured by mistake, or when a secret leaked into a decision. Refuses to act if the text matches more than one decision — call again with a more specific string. Pass purge=true to also redact the text in place (for secrets).',
   {
-    text: z.string().describe('The decision text, or a substring unique to it'),
+    text: z.string().describe('A canonical memory ID, or decision text/substr uniquely identifying a decision'),
     purge: z.boolean().optional().describe('Also redact the text/why/rejected in place, keeping only a hash. For leaked secrets. Default false.'),
   },
   async ({ text, purge }) => {
+    if (/^[a-f0-9]{64}$/.test(text)) {
+      try {
+        const result = await forgetStoredMemory(text, { purge: !!purge });
+        return { content: [{ type: 'text', text: 'Forgotten memory ' + result.id + '. The deletion will sync on push. ' + (purge ? 'Local record and revision history purged; older remote backups and Git history are not erased.' : '') }] };
+      } catch (err) { return { isError: true, content: [{ type: 'text', text: err.message }] }; }
+    }
     const state = await readSession();
     const matches = matchDecisions(state, text);
     if (matches.length === 0) {
@@ -650,7 +593,17 @@ server.tool(
         try { await injectInto(target, rendered); } catch {}
       }
     } catch {}
-    return { content: [{ type: 'text', text: `${res.purged ? 'Forgotten and purged' : 'Forgotten'}: "${matches[0].text}". The tombstone propagates on the next push.` }] };
+    return { content: [{ type: 'text', text: res.purged ? 'Forgotten and purged locally. The tombstone propagates on the next push; historical backups still require removal.' : 'Forgotten. The tombstone propagates on the next push.' }] };
+  }
+);
+
+server.tool(
+  'memoir_resume',
+  'Build an actionable handoff for the current project: goal, next actions, decisions with sources, open questions, and checkout drift. Saved observations never imply that current tests pass.',
+  { project: z.string().optional().describe('Project directory; defaults to the configured working project.') },
+  async ({ project }) => {
+    const brief = await buildResumeBrief(project);
+    return { content: [{ type: 'text', text: formatResumeBrief(brief) }] };
   }
 );
 

package/src/memory/lexical-index.js

@@ -0,0 +1,65 @@
+// Rebuildable, process-local postings. Canonical files remain authoritative;
+// nothing is persisted or trusted across a filesystem refresh or scope change.
+export class LexicalIndex {
+  constructor() { this.clear(); }
+
+  clear() {
+    this.documents = new Set();
+    this.postings = new Map();
+    this.tokensByDocument = new Map();
+    this.vocabulary = null;
+  }
+
+  sync(documents) {
+    const current = new Set(documents);
+    for (const doc of this.documents) {
+      if (current.has(doc)) continue;
+      for (const token of this.tokensByDocument.get(doc)) {
+        const posting = this.postings.get(token);
+        posting.delete(doc);
+        if (!posting.size) { this.postings.delete(token); this.vocabulary = null; }
+      }
+      this.tokensByDocument.delete(doc);
+    }
+    for (const doc of current) {
+      if (this.documents.has(doc)) continue;
+      const tokens = new Set(Object.values(doc.tf).flatMap(field => [...field.keys()]));
+      this.tokensByDocument.set(doc, tokens);
+      for (const token of tokens) {
+        if (!this.postings.has(token)) { this.postings.set(token, new Set()); this.vocabulary = null; }
+        this.postings.get(token).add(doc);
+      }
+    }
+    this.documents = current;
+  }
+
+  lookup(terms) {
+    if (!this.vocabulary) this.vocabulary = [...this.postings.keys()].sort();
+    const documents = new Set();
+    const matches = new Map();
+    for (const term of terms) {
+      const tokens = new Map();
+      if (this.postings.has(term)) tokens.set(term, 1);
+      if (term.length >= 4) {
+        // Binary seek to query-prefix matches; no full vocabulary scan.
+        let lo = 0, hi = this.vocabulary.length;
+        while (lo < hi) {
+          const mid = (lo + hi) >>> 1;
+          if (this.vocabulary[mid] < term) lo = mid + 1; else hi = mid;
+        }
+        for (let i = lo; i < this.vocabulary.length && this.vocabulary[i].startsWith(term); i++) {
+          const token = this.vocabulary[i];
+          if (token !== term) tokens.set(token, .6);
+        }
+        // The reference scorer also allows a document token to prefix the query.
+        for (let n = 4; n < term.length; n++) {
+          const token = term.slice(0, n);
+          if (this.postings.has(token)) tokens.set(token, .6);
+        }
+      }
+      matches.set(term, tokens);
+      for (const token of tokens.keys()) for (const doc of this.postings.get(token)) documents.add(doc);
+    }
+    return { documents, matches };
+  }
+}

package/src/memory/repository.js

@@ -0,0 +1,16 @@
+import { execFileSync } from 'node:child_process';
+
+export function repositoryState(project) {
+  const run = args => execFileSync('git', args, { cwd: project, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 3000 }).trim();
+  try {
+    return {
+      root: run(['rev-parse', '--show-toplevel']),
+      head: run(['rev-parse', 'HEAD']),
+      branch: run(['branch', '--show-current']) || '(detached)',
+      // git status can execute fsmonitor hooks and clean filters from project
+      // configuration. Reading a memory record must not run that code. File
+      // hashes provide scoped check freshness; report overall dirtiness unknown.
+      dirty: null,
+    };
+  } catch { return { root: project, head: null, branch: null, dirty: null }; }
+}

package/src/memory/scope.js

@@ -0,0 +1,65 @@
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import crypto from 'crypto';
+import { execFileSync } from 'child_process';
+
+const cache = new Map();
+export function projectIdentity(project = process.env.MEMOIR_PROJECT_ROOT || process.cwd()) {
+  if (project === 'shared') return 'shared';
+  if (/^(git|local):[a-f0-9]{32}$/.test(project)) return project;
+  let absolute = path.resolve(project.replace(/^~/, os.homedir()));
+  try { absolute = fs.realpathSync(absolute); } catch {}
+  const old = cache.get(absolute);
+  if (old && Date.now() - old.at < 60_000) return old.id;
+  let home = os.homedir();
+  try { home = fs.realpathSync(home); } catch {}
+  let key = path.relative(home, absolute).replace(/\\/g, '/');
+  let kind = 'local';
+  try {
+    const remote = execFileSync('git', ['config', '--get', 'remote.origin.url'], { cwd: absolute, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000 }).trim();
+    if (remote) {
+      // Normalize common SSH/HTTPS spellings; never persist embedded credentials.
+      key = remote.replace(/^git@([^:]+):/, '$1/').replace(/^https?:\/\/(?:[^/@]+@)?/, '').replace(/^ssh:\/\/git@/, '').replace(/\.git\/?$/, '').replace(/\/$/, '');
+      kind = 'git';
+    }
+  } catch {}
+  const id = kind + ':' + crypto.createHash('sha256').update(key).digest('hex').slice(0, 32);
+  cache.set(absolute, { id, at: Date.now() });
+  return id;
+}
+
+// Resolve project paths once per query, not once for every stored record.
+// A new predicate is created on each query so time-based validity is current.
+export function memoryVisibility({ project = process.env.MEMOIR_PROJECT_ROOT || process.cwd(), allProjects = false, now = Date.now() } = {}) {
+  let activeId, currentKey, sharedKey;
+  const identities = new Map();
+  return item => {
+    if (!item || item.hidden === true || item.hidden === 'true' || item.deleted === true || ['deleted', 'hidden', 'superseded'].includes(item.status) || item.superseded_by) return false;
+    if (item.valid_from && Date.parse(item.valid_from) > now) return false;
+    if (item.valid_until && Date.parse(item.valid_until) <= now) return false;
+    if (!allProjects && item.claudeProjectKey) {
+      currentKey ??= path.resolve(project.replace(/^~/, os.homedir())).replace(/[\\/:]/g, '-');
+      sharedKey ??= os.homedir().replace(/[\\/:]/g, '-');
+      if (item.claudeProjectKey !== currentKey && item.claudeProjectKey !== sharedKey) return false;
+    }
+    if (allProjects || !item.project || item.project === 'shared') return true;
+    activeId ??= projectIdentity(project);
+    const key = String(item.project);
+    if (!identities.has(key)) identities.set(key, projectIdentity(key));
+    return identities.get(key) === activeId;
+  };
+}
+
+export function visibleMemory(item, options = {}) {
+  return memoryVisibility(options)(item);
+}
+
+export function sessionView(state, options = {}) {
+  const current = { ...(state?.current || {}) };
+  for (const key of ['goals', 'next_actions', 'parked_actions', 'open_questions', 'decisions']) {
+    const archived = { goals: 'archived_goals', decisions: 'archived_decisions', open_questions: 'archived_questions' }[key];
+    current[key] = [...(current[key] || []), ...(archived ? current[archived] || [] : [])].filter(item => visibleMemory(item, options));
+  }
+  return { ...state, current, history: (state?.history || []).filter(item => visibleMemory(item, options)) };
+}