pi-memory-stone 0.1.2 → 0.1.4

package/src/db/index.ts

@@ -4,7 +4,7 @@
  */
 
 import { DatabaseSync } from "node:sqlite";
-import { existsSync, mkdirSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { redactSecrets } from "../privacy/index.js";
@@ -41,17 +41,38 @@ export function getDb(): DatabaseSync {
   if (!_db) {
     const dbDir = getDbDir();
     if (!existsSync(dbDir)) {
-      mkdirSync(dbDir, { recursive: true });
+      mkdirSync(dbDir, { recursive: true, mode: 0o700 });
     }
+    hardenPathPermissions(dbDir, 0o700);
     _db = new DatabaseSync(getDbPath());
+    hardenDbFilePermissions();
     _db.exec("PRAGMA journal_mode = WAL");
     _db.exec("PRAGMA busy_timeout = 5000");
     _db.exec("PRAGMA foreign_keys = ON");
     runMigrations(_db);
+    hardenDbFilePermissions();
   }
   return _db;
 }
 
+function hardenPathPermissions(path: string, mode: number): void {
+  try {
+    chmodSync(path, mode);
+  } catch {
+    // Best-effort only: do not make memory unavailable on filesystems that
+    // do not support POSIX permissions.
+  }
+}
+
+export function hardenDbFilePermissions(): void {
+  const dbPath = getDbPath();
+  for (const path of [dbPath, `${dbPath}-wal`, `${dbPath}-shm`]) {
+    if (existsSync(path)) {
+      hardenPathPermissions(path, 0o600);
+    }
+  }
+}
+
 export function closeDb(): void {
   if (_db) {
     try {
@@ -242,13 +263,20 @@ export function upsertRecord(record: {
   status?: RecordStatus;
   confidence?: number;
   importance?: number;
+  created_at?: number;
+  updated_at?: number;
   superseded_by?: string | null;
   derived_from_memory_refs?: string | null;
 }): string {
   const db = getDb();
   const now = Date.now();
+  const createdAt = record.created_at ?? now;
+  const updatedAt = record.updated_at ?? now;
   const scope = record.scope ?? "project";
   const projectId = scope === "global" ? null : (record.project_id ?? null);
+  if (scope === "project" && !projectId) {
+    throw new Error("Project-scoped memory records require a project_id");
+  }
   const redactedText = redactSecrets(record.text);
   const redactedTags = record.tags ? redactSecrets(record.tags) : null;
   const id = recordIdentityHash(redactedText, record.kind, scope, projectId);
@@ -276,7 +304,7 @@ export function upsertRecord(record: {
       redactedTags,
       record.confidence ?? 1.0,
       record.importance ?? 0.5,
-      now,
+      updatedAt,
       record.status ?? existing.status,
       record.superseded_by ?? null,
       record.derived_from_memory_refs ?? null,
@@ -303,8 +331,8 @@ export function upsertRecord(record: {
       record.status ?? "active",
       record.confidence ?? 1.0,
       record.importance ?? 0.5,
-      now,
-      now,
+      createdAt,
+      updatedAt,
       record.superseded_by ?? null,
       record.derived_from_memory_refs ?? null,
     );
@@ -331,6 +359,14 @@ export function getRecord(id: string): RecordRow | undefined {
   );
 }
 
+export function listRecords(options: { includeInactive?: boolean } = {}): RecordRow[] {
+  const db = getDb();
+  const sql = options.includeInactive
+    ? "SELECT * FROM records ORDER BY created_at ASC, id ASC"
+    : "SELECT * FROM records WHERE status = 'active' ORDER BY created_at ASC, id ASC";
+  return db.prepare(sql).all() as unknown as RecordRow[];
+}
+
 export function searchRecordsFts(
   query: string,
   limit = 20,
@@ -351,6 +387,8 @@ export function searchRecordsFts(
 
   if (!terms) return [];
 
+  const safeLimit = Math.max(1, Math.min(200, Number.isFinite(limit) ? Math.floor(limit) : 20));
+
   const results = db
     .prepare(
       `SELECT r.*, fts.rank as rank
@@ -360,7 +398,7 @@ export function searchRecordsFts(
        ORDER BY rank
        LIMIT ?`
     )
-    .all(terms, limit) as unknown as (RecordRow & { rank: number })[];
+    .all(terms, safeLimit) as unknown as (RecordRow & { rank: number })[];
 
   // Apply post-filters
   return results.filter((r) => {

package/src/index.ts

@@ -8,7 +8,7 @@
  *  - SQLite schema + migrations
  *  - Deterministic turn_summary and file_activity capture on agent_end
  *  - FTS5 search
- *  - /memory-status, /memory-search, /memory-last commands
+ *  - /memory-status, /memory-search, /memory-open, /memory-inject, /memory-last commands
  *  - memory_search, memory_open, memory_remember, memory_forget tools
  *  - Conservative same-project before_agent_start injection
  */
@@ -19,7 +19,8 @@ import { registerTools } from "./tools/index.js";
 import { indexSessionOnAgentEnd } from "./indexing/index.js";
 import { retrieve, buildInjectionPacket, formatInjectionForLlm } from "./retrieval/index.js";
 import { getProjectId, getConfig, clearProjectCache } from "./config/index.js";
-import { closeDb } from "./db/index.js";
+import { closeDb, getRecord, insertInjection } from "./db/index.js";
+import { getMemorySessionState, manualRecordsToRankedResults } from "./session-state/index.js";
 import { createHash } from "node:crypto";
 
 // ─── Session-scoped state ───────────────────────────────────────────
@@ -72,62 +73,54 @@ export default function (pi: ExtensionAPI) {
       const config = getConfig(ctx.cwd);
       if (!config.enabled) return;
 
-      // Check for session toggle entries before honoring the cached toggle so
-      // /memory-on can re-enable injection after /memory-off in the same session.
-      for (const entry of ctx.sessionManager.getBranch()) {
-        if (
-          entry.type === "custom" &&
-          entry.customType === "memory-stone:session-toggle"
-        ) {
-          const data = entry.data as { enabled?: boolean } | undefined;
-          if (typeof data?.enabled === "boolean") {
-            sessionEnabled = data.enabled;
-          }
-        }
-      }
+      const sessionState = getMemorySessionState(ctx.sessionManager.getBranch());
+      sessionEnabled = sessionState.enabled;
 
       if (!sessionEnabled) return;
 
       const prompt = event.prompt || "";
-      if (!prompt.trim()) return;
-
-      // Hash prompt to detect repeated injections
       const promptHash = createHash("sha256").update(prompt).digest("hex").slice(0, 12);
-
       const projectId = getProjectId(ctx.cwd);
+      const injectionMode = sessionState.injectionMode ?? config.injectionMode;
+
+      const manualRecords = sessionState.manualRefs
+        .map((ref) => getRecord(ref))
+        .filter((record): record is NonNullable<typeof record> => Boolean(record));
+      const manualResults = manualRecordsToRankedResults(manualRecords, projectId);
+      const manualRefSet = new Set(manualResults.map((r) => r.record.id));
+
+      let autoResults: ReturnType<typeof retrieve> = [];
+      if (injectionMode === "auto" && prompt.trim()) {
+        const results = retrieve(prompt, projectId, [], {
+          limit: config.maxInjectedRecords,
+          crossProjectEnabled: config.crossProjectEnabled,
+        });
+
+        autoResults = results
+          .filter((r) => !manualRefSet.has(r.record.id))
+          .filter((r) => !injectedRefsThisSession.has(r.record.id))
+          .filter((r) => r.score >= config.scoreThreshold);
+      }
 
-      // Build search query
-      const results = retrieve(prompt, projectId, [], {
-        limit: config.maxInjectedRecords,
-        crossProjectEnabled: config.crossProjectEnabled,
-      });
-
-      // Filter: skip already-injected refs
-      const newResults = results.filter((r) => !injectedRefsThisSession.has(r.record.id));
-
-      // Score threshold
-      const thresholdResults = newResults.filter((r) => r.score >= config.scoreThreshold);
-
-      if (thresholdResults.length === 0) return;
+      const selectedResults = [...manualResults, ...autoResults];
+      if (selectedResults.length === 0) return;
 
-      // Build and format injection packet
-      const packet = buildInjectionPacket(thresholdResults);
+      const packet = buildInjectionPacket(selectedResults);
       const formatted = formatInjectionForLlm(packet, config.maxInjectedTokens);
 
-      // Track injected refs (prevent feedback loop)
-      for (const r of thresholdResults) {
+      // Track only search-selected refs. Manually chosen refs are intentionally
+      // injected on every turn until /memory-clear-injected is used.
+      for (const r of autoResults) {
         injectedRefsThisSession.add(r.record.id);
       }
 
-      // Log injection to DB
-      const { insertInjection } = await import("./db/index.js");
       insertInjection({
         session_id: ctx.sessionManager.getSessionId(),
         turn_entry_id: ctx.sessionManager.getLeafId() ?? undefined,
         prompt_hash: promptHash,
-        injected_refs: thresholdResults.map((r) => r.record.id).join(","),
+        injected_refs: selectedResults.map((r) => r.record.id).join(","),
         packet: formatted,
-        reasons: thresholdResults.map((r) => r.reasons.join(";")).join(" | "),
+        reasons: selectedResults.map((r) => r.reasons.join(";")).join(" | "),
       });
 
       // Inject as a non-context audit custom entry (separate from LLM context)
@@ -156,17 +149,7 @@ export default function (pi: ExtensionAPI) {
       sessionEnabled = true;
 
       // Restore session toggle from branch
-      for (const entry of ctx.sessionManager.getBranch()) {
-        if (
-          entry.type === "custom" &&
-          entry.customType === "memory-stone:session-toggle"
-        ) {
-          const data = entry.data as { enabled?: boolean } | undefined;
-          if (typeof data?.enabled === "boolean") {
-            sessionEnabled = data.enabled;
-          }
-        }
-      }
+      sessionEnabled = getMemorySessionState(ctx.sessionManager.getBranch()).enabled;
 
       // Clear project ID cache on session change
       clearProjectCache();

package/src/portable/index.ts

@@ -0,0 +1,217 @@
+/**
+ * Portable export/import/backup helpers for memory records.
+ */
+
+import { chmodSync, copyFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { getDb, getDbPath, hardenDbFilePermissions, listRecords, upsertRecord, type RecordRow } from "../db/index.js";
+import { SCHEMA_VERSION, RECORD_KINDS, RECORD_SCOPES, RECORD_STATUSES, type RecordKind, type RecordScope, type RecordStatus } from "../db/schema.js";
+import { isSensitiveForGlobalMemory } from "../privacy/index.js";
+
+export type ExportFormat = "json" | "md";
+
+export interface PortableMemoryRecord {
+  id: string;
+  kind: RecordKind;
+  scope: RecordScope;
+  project_id: string | null;
+  text: string;
+  tags: string | null;
+  status: RecordStatus;
+  confidence: number;
+  importance: number;
+  created_at: number;
+  updated_at: number;
+  superseded_by: string | null;
+  derived_from_memory_refs: string | null;
+}
+
+export interface PortableMemoryExport {
+  format: "pi-memory-stone-export";
+  version: 1;
+  exported_at: string;
+  schema_version: number;
+  records: PortableMemoryRecord[];
+}
+
+export interface ImportOptions {
+  /** Remap project-scoped records to this project id. Use undefined to preserve exported project ids. */
+  projectId?: string | null;
+  /** Force every imported record into a scope. */
+  scopeOverride?: RecordScope;
+}
+
+export interface ImportResult {
+  imported: number;
+  skipped: number;
+  ids: string[];
+}
+
+export function buildMemoryExport(includeInactive = false): PortableMemoryExport {
+  return {
+    format: "pi-memory-stone-export",
+    version: 1,
+    exported_at: new Date().toISOString(),
+    schema_version: SCHEMA_VERSION,
+    records: listRecords({ includeInactive }).map(toPortableRecord),
+  };
+}
+
+export function exportMemory(format: ExportFormat, includeInactive = false): string {
+  const payload = buildMemoryExport(includeInactive);
+  if (format === "json") {
+    return JSON.stringify(payload, null, 2) + "\n";
+  }
+
+  return exportMarkdown(payload);
+}
+
+export function writeMemoryExport(path: string, format: ExportFormat, includeInactive = false): number {
+  const payload = buildMemoryExport(includeInactive);
+  const content = format === "json" ? JSON.stringify(payload, null, 2) + "\n" : exportMarkdown(payload);
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  writeFileSync(path, content, { encoding: "utf8", mode: 0o600 });
+  return payload.records.length;
+}
+
+export function importMemoryJsonFile(path: string, options: ImportOptions = {}): ImportResult {
+  const raw = readFileSync(path, "utf8");
+  return importMemoryJson(raw, options);
+}
+
+export function importMemoryJson(raw: string, options: ImportOptions = {}): ImportResult {
+  const parsed = JSON.parse(raw) as Partial<PortableMemoryExport>;
+  if (parsed.format !== "pi-memory-stone-export" || parsed.version !== 1 || !Array.isArray(parsed.records)) {
+    throw new Error("Unsupported memory export file. Expected pi-memory-stone-export version 1 JSON.");
+  }
+
+  const result: ImportResult = { imported: 0, skipped: 0, ids: [] };
+  for (const candidate of parsed.records) {
+    const record = normalizePortableRecord(candidate);
+    if (!record) {
+      result.skipped += 1;
+      continue;
+    }
+
+    const scope = options.scopeOverride ?? record.scope;
+    const projectId = scope === "global" ? null : (options.projectId !== undefined ? options.projectId : record.project_id);
+    if (scope === "project" && !projectId) {
+      result.skipped += 1;
+      continue;
+    }
+    if (scope === "global" && isSensitiveForGlobalMemory(`${record.text}\n${record.tags ?? ""}`)) {
+      result.skipped += 1;
+      continue;
+    }
+    const id = upsertRecord({
+      kind: record.kind,
+      scope,
+      project_id: projectId,
+      text: record.text,
+      tags: record.tags,
+      status: record.status,
+      confidence: record.confidence,
+      importance: record.importance,
+      created_at: record.created_at,
+      updated_at: record.updated_at,
+      superseded_by: record.superseded_by,
+      derived_from_memory_refs: record.derived_from_memory_refs,
+    });
+
+    result.imported += 1;
+    result.ids.push(id);
+  }
+
+  return result;
+}
+
+export function backupMemoryDatabase(path: string): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  getDb().exec("PRAGMA wal_checkpoint(TRUNCATE)");
+  hardenDbFilePermissions();
+  copyFileSync(getDbPath(), path);
+  try {
+    chmodSync(path, 0o600);
+  } catch {}
+}
+
+export function defaultPortablePath(cwd: string, prefix: string, extension: string): string {
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+  return resolve(cwd, `${prefix}-${stamp}.${extension}`);
+}
+
+export function resolvePortablePath(cwd: string, path: string): string {
+  return isAbsolute(path) ? path : resolve(cwd, path);
+}
+
+function toPortableRecord(row: RecordRow): PortableMemoryRecord {
+  return {
+    id: row.id,
+    kind: row.kind,
+    scope: row.scope,
+    project_id: row.project_id,
+    text: row.text,
+    tags: row.tags,
+    status: row.status,
+    confidence: row.confidence,
+    importance: row.importance,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+    superseded_by: row.superseded_by,
+    derived_from_memory_refs: row.derived_from_memory_refs,
+  };
+}
+
+function exportMarkdown(payload: PortableMemoryExport): string {
+  const lines: string[] = [];
+  lines.push("# Memory Stone Export");
+  lines.push("");
+  lines.push(`Exported: ${payload.exported_at}`);
+  lines.push(`Records: ${payload.records.length}`);
+  lines.push("");
+
+  for (const record of payload.records) {
+    lines.push(`## [${record.kind}] ${record.id}`);
+    lines.push("");
+    lines.push(`- Scope: ${record.scope}`);
+    lines.push(`- Project: ${record.project_id ?? "global"}`);
+    lines.push(`- Status: ${record.status}`);
+    lines.push(`- Importance: ${record.importance}`);
+    lines.push(`- Created: ${new Date(record.created_at).toISOString()}`);
+    if (record.tags) lines.push(`- Tags: ${record.tags}`);
+    lines.push("");
+    lines.push(record.text);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}
+
+function normalizePortableRecord(candidate: unknown): PortableMemoryRecord | null {
+  if (!candidate || typeof candidate !== "object") return null;
+  const r = candidate as Record<string, unknown>;
+  if (typeof r.text !== "string" || r.text.trim() === "") return null;
+  if (!isStringMember(r.kind, RECORD_KINDS)) return null;
+  if (!isStringMember(r.scope, RECORD_SCOPES)) return null;
+  if (!isStringMember(r.status, RECORD_STATUSES)) return null;
+
+  return {
+    id: typeof r.id === "string" ? r.id : "",
+    kind: r.kind,
+    scope: r.scope,
+    project_id: typeof r.project_id === "string" ? r.project_id : null,
+    text: r.text,
+    tags: typeof r.tags === "string" ? r.tags : null,
+    status: r.status,
+    confidence: typeof r.confidence === "number" ? r.confidence : 1,
+    importance: typeof r.importance === "number" ? r.importance : 0.5,
+    created_at: typeof r.created_at === "number" ? r.created_at : Date.now(),
+    updated_at: typeof r.updated_at === "number" ? r.updated_at : Date.now(),
+    superseded_by: typeof r.superseded_by === "string" ? r.superseded_by : null,
+    derived_from_memory_refs: typeof r.derived_from_memory_refs === "string" ? r.derived_from_memory_refs : null,
+  };
+}
+
+function isStringMember<T extends readonly string[]>(value: unknown, allowed: T): value is T[number] {
+  return typeof value === "string" && (allowed as readonly string[]).includes(value);
+}

package/src/privacy/index.ts

@@ -27,7 +27,7 @@ const SECRET_PATTERNS: { name: string; regex: RegExp; replacement: SecretReplace
   },
   {
     name: "aws-secret",
-    regex: /(?<=SecretAccessKey[=:]\s*)[A-Za-z0-9/+]{40,}/g,
+    regex: /\b(?:aws[_-]?)?secret[_-]?access[_-]?key\b\s*[=:]\s*['"]?[A-Za-z0-9/+=]{40,}['"]?/gi,
     replacement: "[REDACTED:aws-secret]",
   },
   {
@@ -37,12 +37,12 @@ const SECRET_PATTERNS: { name: string; regex: RegExp; replacement: SecretReplace
   },
   {
     name: "generic-api-key",
-    regex: /(?:api[_-]?key|apikey|api[_-]?secret|secret[_-]?key)[=:]\s*['"]?[A-Za-z0-9_\-.]{16,}['"]?/gi,
+    regex: /\b(?:api[_-]?key|apikey|api[_-]?secret|secret[_-]?key|client[_-]?secret|private[_-]?key|access[_-]?key|auth[_-]?key)\b\s*[=:]\s*['"]?[A-Za-z0-9_\-./+=]{16,}['"]?/gi,
     replacement: "[REDACTED:api-key]",
   },
   {
     name: "secret-assignment",
-    regex: /\b(?:secret|secret[_-]?key)\b\s*[=:]\s*(?:['"][^'"]+['"]|[^\s'"`]+)/gi,
+    regex: /\b(?:secret|secret[_-]?key|client[_-]?secret|app[_-]?secret|webhook[_-]?secret|signing[_-]?secret)\b\s*[=:]\s*(?:['"][^'"]+['"]|[^\s'"`]+)/gi,
     replacement: "[REDACTED:secret]",
   },
   {
@@ -126,6 +126,22 @@ export function redactSecrets(text: string): string {
   return result;
 }
 
+export function isSensitiveForGlobalMemory(text: string): boolean {
+  if (redactSecrets(text) !== text) return true;
+
+  return [
+    // Local/absolute/relative filesystem paths and common repo paths.
+    /(?:^|\s)(?:~|\.|\.\.|[A-Za-z]:)?[/\\][^\s]+/,
+    /\b(?:src|lib|test|tests|packages|apps|docs|config)\/[\w./-]+\b/i,
+    /\b[\w.-]+\.(?:ts|tsx|js|jsx|mjs|cjs|json|yaml|yml|toml|env|db|sqlite|pem|key|crt)\b/i,
+    // Hostnames and network endpoints.
+    /\b(?:localhost|127\.0\.0\.1|0\.0\.0\.0|::1)\b/i,
+    /\b[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+(?::\d{2,5})?\b/i,
+    // Implementation/internal detail markers that should stay project-local.
+    /\b(?:internal|private|implementation detail|class|function|method|module|endpoint|schema|table|column)\b/i,
+  ].some((pattern) => pattern.test(text));
+}
+
 export function isSensitivePath(path: string, extraPatterns: RegExp[] = []): boolean {
   const allPatterns = [...DEFAULT_SENSITIVE_PATHS, ...extraPatterns];
 

package/src/retrieval/index.ts

@@ -23,6 +23,8 @@ const KIND_BOOST: Record<string, number> = {
 // ─── Recency decay ──────────────────────────────────────────────────
 
 const RECENCY_HALF_LIFE_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
+export const MAX_RETRIEVAL_LIMIT = 20;
+const MAX_CANDIDATE_LIMIT = MAX_RETRIEVAL_LIMIT * 10;
 
 function recencyDecay(createdAt: number): number {
   const age = Date.now() - createdAt;
@@ -72,7 +74,7 @@ export function rankAndFilter(
     // and require explicit cross-project retrieval.
     if (rec.scope === "global") {
       if (!crossProjectEnabled) continue;
-    } else if (rec.project_id && currentProjectId && rec.project_id !== currentProjectId) {
+    } else if (!rec.project_id || !currentProjectId || rec.project_id !== currentProjectId) {
       continue;
     }
 
@@ -121,6 +123,11 @@ export function rankAndFilter(
 
 // ─── Full retrieval pipeline ────────────────────────────────────────
 
+export function normalizeRetrievalLimit(value: unknown, fallback: number): number {
+  const numeric = typeof value === "number" && Number.isFinite(value) ? Math.floor(value) : fallback;
+  return Math.max(1, Math.min(MAX_RETRIEVAL_LIMIT, numeric));
+}
+
 export function retrieve(
   userPrompt: string,
   currentProjectId: string | null,
@@ -133,13 +140,14 @@ export function retrieve(
   },
 ): RankedResult[] {
   const config = getConfig();
-  const limit = opts?.limit ?? config.maxInjectedRecords;
+  const limit = normalizeRetrievalLimit(opts?.limit, config.maxInjectedRecords);
   const crossProject = opts?.crossProjectEnabled ?? config.crossProjectEnabled;
 
   const query = buildSearchQuery(userPrompt, recentFiles);
 
-  // Get more candidates than needed (ranking will filter)
-  const candidates = searchRecordsFts(query, limit * 10, opts?.kindFilter, opts?.scopeFilter);
+  // Get more candidates than needed (ranking will filter), but keep local work bounded.
+  const candidateLimit = Math.min(MAX_CANDIDATE_LIMIT, limit * 10);
+  const candidates = searchRecordsFts(query, candidateLimit, opts?.kindFilter, opts?.scopeFilter);
 
   const ranked = rankAndFilter(candidates, currentProjectId, crossProject);
 

package/src/session-state/index.ts

@@ -0,0 +1,89 @@
+import type { RecordRow } from "../db/index.js";
+import type { RankedResult } from "../retrieval/index.js";
+
+export type InjectionMode = "auto" | "manual";
+
+export const SESSION_TOGGLE_ENTRY = "memory-stone:session-toggle";
+export const INJECTION_MODE_ENTRY = "memory-stone:injection-mode";
+export const MANUAL_INJECTION_ENTRY = "memory-stone:manual-injection";
+
+export interface MemorySessionState {
+  enabled: boolean;
+  injectionMode?: InjectionMode;
+  manualRefs: string[];
+}
+
+export function isInjectionMode(value: unknown): value is InjectionMode {
+  return value === "auto" || value === "manual";
+}
+
+export function getMemorySessionState(branch: unknown[]): MemorySessionState {
+  let enabled = true;
+  let injectionMode: InjectionMode | undefined;
+  let manualRefs: string[] = [];
+
+  for (const entry of branch) {
+    if (!isCustomEntry(entry)) continue;
+
+    if (entry.customType === SESSION_TOGGLE_ENTRY) {
+      const data = entry.data as { enabled?: unknown } | undefined;
+      if (typeof data?.enabled === "boolean") {
+        enabled = data.enabled;
+      }
+      continue;
+    }
+
+    if (entry.customType === INJECTION_MODE_ENTRY) {
+      const data = entry.data as { mode?: unknown } | undefined;
+      if (isInjectionMode(data?.mode)) {
+        injectionMode = data.mode;
+      }
+      continue;
+    }
+
+    if (entry.customType === MANUAL_INJECTION_ENTRY) {
+      const data = entry.data as { action?: unknown; refs?: unknown } | undefined;
+      if (data?.action === "clear") {
+        manualRefs = [];
+      } else if (data?.action === "add" && Array.isArray(data.refs)) {
+        for (const ref of data.refs) {
+          if (typeof ref === "string" && ref.trim() && !manualRefs.includes(ref)) {
+            manualRefs.push(ref);
+          }
+        }
+      }
+    }
+  }
+
+  return { enabled, injectionMode, manualRefs };
+}
+
+export function parseRefArgs(args: string): string[] {
+  return (args ?? "")
+    .trim()
+    .split(/\s+/)
+    .map((part) => part.trim())
+    .filter((part) => part.length > 0 && !part.startsWith("--"));
+}
+
+export function isRecordVisibleInProject(record: RecordRow, currentProjectId: string | null): boolean {
+  if (record.scope === "global") return true;
+  return Boolean(currentProjectId && record.project_id && record.project_id === currentProjectId);
+}
+
+export function manualRecordsToRankedResults(
+  records: RecordRow[],
+  currentProjectId: string | null,
+): RankedResult[] {
+  return records
+    .filter((record) => record.status === "active" && isRecordVisibleInProject(record, currentProjectId))
+    .map((record) => ({
+      record,
+      score: Number.POSITIVE_INFINITY,
+      reasons: ["manual-ref"],
+    }));
+}
+
+function isCustomEntry(entry: unknown): entry is { type?: string; customType?: string; data?: unknown } {
+  return typeof entry === "object" && entry !== null && (entry as { type?: unknown }).type === "custom";
+}