synabun 1.3.0

package/mcp-server/src/tools/memories.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+import { scrollMemories, getMemoryStats } from '../services/sqlite.js';
+import { validateCategory } from '../services/categories.js';
+import type { MemoryPayload } from '../types.js';
+import { text } from './response.js';
+
+export function buildMemoriesSchema() {
+  return {
+    action: z
+      .enum(['recent', 'stats', 'by-category', 'by-project'] as const)
+      .describe(
+        'recent=latest memories, stats=counts and health, by-category=filter by type, by-project=filter by project.'
+      ),
+    category: z
+      .string()
+      .optional()
+      .describe('Category to filter by (for by-category action).'),
+    project: z
+      .string()
+      .optional()
+      .describe('Filter by project (for by-project action).'),
+    limit: z
+      .coerce.number()
+      .min(1)
+      .max(50)
+      .optional()
+      .describe('Number of results (default 10).'),
+  };
+}
+
+export const memoriesSchema = buildMemoriesSchema();
+
+export const memoriesDescription =
+  'Browse recent memories or get statistics. Use this to see what you remember about a project, review recent learnings, or check memory health.';
+
+function formatAge(isoDate: string): string {
+  const diffMs = Date.now() - new Date(isoDate).getTime();
+  const days = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  if (days === 0) return 'today';
+  if (days === 1) return '1 day ago';
+  if (days < 30) return `${days} days ago`;
+  const months = Math.floor(days / 30);
+  if (months === 1) return '1 month ago';
+  return `${months} months ago`;
+}
+
+export async function handleMemories(args: {
+  action: string;
+  category?: string;
+  project?: string;
+  limit?: number;
+}) {
+  const action = args.action;
+  const category = args.category;
+  const project = args.project;
+  const limit = args.limit ?? 10;
+
+  if (category) {
+    const catCheck = validateCategory(category);
+    if (!catCheck.valid) {
+      return text(catCheck.error!);
+    }
+  }
+
+  if (action === 'stats') {
+    const stats = await getMemoryStats();
+
+    const categoryLines = Object.entries(stats.by_category)
+      .filter(([, count]) => count > 0)
+      .map(([cat, count]) => `  ${cat}: ${count}`)
+      .join('\n');
+
+    const projectLines = Object.entries(stats.by_project)
+      .map(([proj, count]) => `  ${proj}: ${count}`)
+      .join('\n');
+
+    return text(`Memory Statistics:\n\nTotal memories: ${stats.total}\n\nBy category:\n${categoryLines || '  (none)'}\n\nBy project:\n${projectLines || '  (none)'}\n\nOldest: ${stats.oldest ? formatAge(stats.oldest) : 'n/a'}\nNewest: ${stats.newest ? formatAge(stats.newest) : 'n/a'}`);
+  }
+
+  const must: Record<string, unknown>[] = [];
+  if ((action === 'by-category' || action === 'recent') && category) {
+    must.push({ key: 'category', match: { value: category } });
+  }
+  if ((action === 'by-project' || action === 'recent') && project) {
+    must.push({ key: 'project', match: { value: project } });
+  }
+
+  const filter = must.length > 0 ? { must } : undefined;
+  const result = await scrollMemories(filter, limit);
+
+  const sorted = result.points
+    .map((p) => ({
+      id: p.id as string,
+      payload: p.payload as unknown as MemoryPayload,
+    }))
+    .filter((m) => m.payload?.content && m.payload?.created_at)
+    .sort((a, b) => b.payload.created_at.localeCompare(a.payload.created_at));
+
+  if (sorted.length === 0) {
+    return text(`No memories found${category ? ` for category "${category}"` : ''}${project ? ` for project "${project}"` : ''}.`);
+  }
+
+  const lines = sorted.map((m, i) => {
+    const p = m.payload;
+    const tagStr = p.tags?.length ? ` [${p.tags.join(', ')}]` : '';
+    const sub = p.subcategory ? `/${p.subcategory}` : '';
+    return `${i + 1}. [${m.id}] ${p.category}${sub} | ${p.project} | imp:${p.importance} | ${formatAge(p.created_at)}${tagStr}\n   ${p.content.slice(0, 150)}${p.content.length > 150 ? '...' : ''}`;
+  });
+
+  const title =
+    action === 'recent'
+      ? 'Recent memories'
+      : action === 'by-category'
+        ? `Memories in "${category}"`
+        : `Memories for "${project}"`;
+
+  return text(`${title} (${sorted.length}):\n\n${lines.join('\n\n')}`);
+}

package/mcp-server/src/tools/recall.ts

@@ -0,0 +1,323 @@
+import { z } from 'zod';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { generateEmbedding } from '../services/local-embeddings.js';
+import { searchMemories, searchMemoriesFTS, updatePayload, searchSessionChunks } from '../services/sqlite.js';
+import { validateCategory } from '../services/categories.js';
+import { coerceStringArray } from './utils.js';
+import type { MemoryPayload, SessionChunkPayload } from '../types.js';
+import { config, detectProject } from '../config.js';
+import { text } from './response.js';
+
+export function buildRecallSchema() {
+  return {
+    query: z.string().describe('What to search for, in natural language.'),
+    category: z
+      .string()
+      .optional()
+      .describe('Optional: filter by category name.'),
+    project: z
+      .string()
+      .optional()
+      .describe(
+        'Optional: filter by project. If omitted, searches all projects but boosts current project.'
+      ),
+    tags: coerceStringArray()
+      .optional()
+      .describe('Optional: filter by tags (any match).'),
+    limit: z
+      .coerce.number()
+      .min(1)
+      .max(20)
+      .optional()
+      .describe('Number of results (default 5).'),
+    min_importance: z
+      .coerce.number()
+      .min(1)
+      .max(10)
+      .optional()
+      .describe('Minimum importance threshold.'),
+    min_score: z
+      .coerce.number()
+      .min(0)
+      .max(1)
+      .optional()
+      .describe('Minimum similarity score 0-1 (default 0.3).'),
+    include_sessions: z
+      .boolean()
+      .optional()
+      .describe('Override session chunk search. Auto-triggers on temporal queries or sparse results. Set true to force, false to disable.'),
+    recency_boost: z
+      .boolean()
+      .optional()
+      .describe('Prioritize recent memories. Shifts scoring to favor recency over semantic similarity (14-day half-life, 55% recency weight). Ideal for session-start boot queries.'),
+  };
+}
+
+export const recallSchema = buildRecallSchema();
+
+export const recallDescription =
+  'Search your persistent memory for relevant information. Use this at the start of any task to check what you already know, or when you need context about past decisions, known issues, or architectural patterns.';
+
+function applyTimeDecay(
+  rawScore: number,
+  createdAt: string,
+  importance: number,
+  accessCount: number,
+  recencyBoost = false
+): number {
+  const ageInDays =
+    (Date.now() - new Date(createdAt).getTime()) / (1000 * 60 * 60 * 24);
+  const accessBoost = Math.min(0.1, accessCount * 0.01);
+
+  if (recencyBoost) {
+    // Recency-first scoring: 14-day half-life, recency dominates
+    const recencyMultiplier = Math.pow(0.5, ageInDays / 14);
+    return rawScore * 0.35 + recencyMultiplier * 0.55 + accessBoost;
+  }
+
+  // Default scoring: semantic similarity dominates, 90-day half-life
+  if (importance >= 8) return rawScore;
+  const recencyMultiplier = Math.pow(0.5, ageInDays / 90);
+  return rawScore * 0.7 + recencyMultiplier * 0.2 + accessBoost;
+}
+
+function formatAge(isoDate: string): string {
+  const diffMs = Date.now() - new Date(isoDate).getTime();
+  const days = Math.floor(diffMs / (1000 * 60 * 60 * 24));
+  if (days === 0) return 'today';
+  if (days === 1) return '1 day ago';
+  if (days < 30) return `${days} days ago`;
+  const months = Math.floor(days / 30);
+  if (months === 1) return '1 month ago';
+  return `${months} months ago`;
+}
+
+interface RecallDefaults {
+  limit: number;
+  minImportance: number;
+  minScore: number;
+  maxChars: number;
+  includeSessions: 'auto' | 'always' | 'never';
+  recencyBoost: boolean;
+}
+
+const RECALL_DEFAULTS: RecallDefaults = {
+  limit: 5,
+  minImportance: 0,
+  minScore: 0.3,
+  maxChars: 0,
+  includeSessions: 'auto',
+  recencyBoost: false,
+};
+
+function getRecallDefaults(): RecallDefaults {
+  try {
+    const settingsPath = path.resolve(config.dataDir, 'display-settings.json');
+    const data = JSON.parse(readFileSync(settingsPath, 'utf-8'));
+    const d = data.recallDefaults;
+    if (!d) {
+      // Legacy: only recallMaxChars exists
+      return { ...RECALL_DEFAULTS, maxChars: data.recallMaxChars ?? 0 };
+    }
+    return {
+      limit: d.limit ?? RECALL_DEFAULTS.limit,
+      minImportance: d.minImportance ?? RECALL_DEFAULTS.minImportance,
+      minScore: d.minScore ?? RECALL_DEFAULTS.minScore,
+      maxChars: d.maxChars ?? RECALL_DEFAULTS.maxChars,
+      includeSessions: d.includeSessions ?? RECALL_DEFAULTS.includeSessions,
+      recencyBoost: d.recencyBoost ?? RECALL_DEFAULTS.recencyBoost,
+    };
+  } catch {
+    return { ...RECALL_DEFAULTS };
+  }
+}
+
+export async function handleRecall(args: {
+  query: string;
+  category?: string;
+  project?: string;
+  tags?: string[];
+  limit?: number;
+  min_importance?: number;
+  min_score?: number;
+  include_sessions?: boolean;
+  recency_boost?: boolean;
+}) {
+  const defaults = getRecallDefaults();
+  const query = args.query;
+  const category = args.category;
+  const project = args.project;
+  const tags = args.tags;
+  const limit = args.limit ?? defaults.limit;
+  const minImportance = args.min_importance ?? (defaults.minImportance > 0 ? defaults.minImportance : undefined);
+  const minScore = args.min_score ?? defaults.minScore;
+  const includeSessionsExplicit = args.include_sessions ??
+    (defaults.includeSessions === 'always' ? true : defaults.includeSessions === 'never' ? false : undefined);
+  const recencyBoost = args.recency_boost ?? defaults.recencyBoost;
+
+  if (category) {
+    const catCheck = validateCategory(category);
+    if (!catCheck.valid) {
+      return text(catCheck.error!);
+    }
+  }
+
+  const vector = await generateEmbedding(query);
+
+  const must: Record<string, unknown>[] = [];
+  if (category) must.push({ key: 'category', match: { value: category } });
+  if (project) must.push({ key: 'project', match: { value: project } });
+  if (tags && tags.length > 0) {
+    for (const tag of tags) {
+      must.push({ key: 'tags', match: { value: tag } });
+    }
+  }
+  if (minImportance) {
+    must.push({ key: 'importance', range: { gte: minImportance } });
+  }
+
+  const filter = must.length > 0 ? { must } : undefined;
+  // Use a lower raw threshold for the DB query — time decay, importance,
+  // and project boosts can lift borderline results well above minScore.
+  // The actual minScore filter is applied after adjustments below.
+  const rawThreshold = Math.min(minScore, minScore * 0.5);
+  const results = await searchMemories(vector, limit * 2, filter, rawThreshold);
+
+  const currentProject = detectProject();
+  const scored = results
+    .map((r) => {
+      const payload = r.payload as unknown as MemoryPayload;
+      let adjustedScore = applyTimeDecay(
+        r.score,
+        payload.created_at,
+        payload.importance,
+        payload.access_count,
+        recencyBoost
+      );
+      if (!project && payload.project === currentProject) {
+        adjustedScore *= 1.2;
+      }
+      return { id: r.id as string, score: adjustedScore, payload };
+    })
+    .filter((r) => r.score >= minScore)
+    .sort((a, b) => b.score - a.score)
+    .slice(0, limit);
+
+  // FTS5 keyword fallback — when vector results are weak, supplement with
+  // full-text search to catch exact identifiers, error codes, proper nouns
+  const FTS_TRIGGER_SCORE = 0.45;
+  const vectorWeak = scored.length === 0 ||
+    (scored.length < limit && scored[0]?.score < FTS_TRIGGER_SCORE);
+
+  if (vectorWeak) {
+    try {
+      const existingIds = new Set(scored.map(r => r.id));
+      const ftsResults = await searchMemoriesFTS(query, limit, filter, existingIds);
+      for (const fts of ftsResults) {
+        if (scored.length >= limit) break;
+        scored.push(fts);
+      }
+      // Re-sort after merge
+      scored.sort((a, b) => b.score - a.score);
+    } catch {
+      // FTS fallback failure is non-fatal
+    }
+  }
+
+  // Update access tracking (fire-and-forget)
+  const now = new Date().toISOString();
+  for (const result of scored) {
+    updatePayload(result.id, {
+      accessed_at: now,
+      access_count: result.payload.access_count + 1,
+    }).catch(() => {});
+  }
+
+  if (scored.length === 0) {
+    return text(`No memories found for "${query}"${category ? ` in category ${category}` : ''}${project ? ` for project ${project}` : ''}.`);
+  }
+
+  const maxChars = defaults.maxChars;
+
+  const lines = scored.map((r, i) => {
+    const p = r.payload;
+    const score = (r.score * 100).toFixed(0);
+    const tagStr = p.tags?.length ? ` [${p.tags.join(', ')}]` : '';
+    const sub = p.subcategory ? `/${p.subcategory}` : '';
+    const files = p.related_files?.length
+      ? `\n   Files: ${p.related_files.join(', ')}`
+      : '';
+    const displayContent = (maxChars > 0 && p.content.length > maxChars)
+      ? p.content.substring(0, maxChars) + '...'
+      : p.content;
+    return `${i + 1}. [${r.id}] (${score}% match, importance: ${p.importance}, ${formatAge(p.created_at)})\n   ${p.category}${sub} | ${p.project}${tagStr}\n   ${displayContent}${files}`;
+  });
+
+  // Session chunk search — auto-trigger when useful, or explicit override
+  const shouldIncludeSessions = (() => {
+    // Explicit override takes priority
+    if (includeSessionsExplicit !== undefined) return includeSessionsExplicit;
+    // Temporal/process keywords → likely asking about past sessions
+    const q = query.toLowerCase();
+    const sessionKeywords = [
+      'yesterday', 'last session', 'last time', 'remember when',
+      'how did we', 'what did we', 'earlier today', 'previous session',
+      'conversation about', 'we discussed', 'we worked on', 'we talked about',
+      'that session', 'that conversation', 'the other day', 'last week',
+      'before', 'recently', 'a while ago', 'few days ago',
+    ];
+    if (sessionKeywords.some(kw => q.includes(kw))) return true;
+    // Sparse/weak memory results → widen the net
+    if (scored.length < 3) return true;
+    if (scored.length > 0 && scored[0].score < 0.45) return true;
+    return false;
+  })();
+
+  let sessionLines: string[] = [];
+  if (shouldIncludeSessions) {
+    try {
+      const sessionFilter: Record<string, unknown> = {};
+      if (project) {
+        sessionFilter.must = [{ key: 'project', match: { value: project } }];
+      }
+      const sessionLimit = Math.max(3, Math.floor(limit / 2));
+      const sessionResults = await searchSessionChunks(vector, sessionLimit * 2, Object.keys(sessionFilter).length > 0 ? sessionFilter : undefined, rawThreshold);
+
+      // Deduplicate: skip chunks whose dedup_memory_id matches a returned memory
+      const memoryIds = new Set(scored.map((r) => r.id));
+      const filteredSessions = sessionResults.filter((r) => {
+        const payload = r.payload as unknown as SessionChunkPayload;
+        return !payload.dedup_memory_id || !memoryIds.has(payload.dedup_memory_id);
+      }).slice(0, sessionLimit);
+
+      sessionLines = filteredSessions.map((r, i) => {
+        const p = r.payload as unknown as SessionChunkPayload;
+        const score = (r.score * 100).toFixed(0);
+        const timeRange = p.start_timestamp && p.end_timestamp
+          ? `${new Date(p.start_timestamp).toISOString().slice(0, 16)} - ${new Date(p.end_timestamp).toISOString().slice(11, 16)}`
+          : 'unknown time';
+        const toolStr = p.tools_used?.length ? `Tools: ${p.tools_used.join(', ')}` : '';
+        const fileStr = p.files_modified?.length ? `Files: ${p.files_modified.join(', ')}` : '';
+        const linkedMems = p.related_memory_ids?.length ? `Linked memories: ${p.related_memory_ids.join(', ')}` : '';
+        const details = [toolStr, fileStr, linkedMems].filter(Boolean).join(' | ');
+        return `SESSION: [${r.id}] (${score}% match, ${timeRange}, branch: ${p.git_branch || 'unknown'})\n   Session: ${p.session_id} | Chunk ${p.chunk_index + 1} | ${p.project}\n   ${p.summary}\n   ${details}`;
+      });
+    } catch {
+      // Session search failure is non-fatal
+    }
+  }
+
+  const allLines = [...lines];
+  if (sessionLines.length > 0) {
+    allLines.push('', '--- Session Context ---');
+    allLines.push(...sessionLines);
+  }
+
+  const totalCount = scored.length + sessionLines.length;
+  const label = sessionLines.length > 0
+    ? `Found ${scored.length} memories and ${sessionLines.length} session chunks`
+    : `Found ${scored.length} memories`;
+
+  return text(`${label} for "${query}":\n\n${allLines.join('\n\n')}`);
+}

package/mcp-server/src/tools/reflect.ts

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+import { getMemory, updatePayload, updateVector } from '../services/sqlite.js';
+import { generateEmbedding } from '../services/local-embeddings.js';
+import { validateCategory } from '../services/categories.js';
+import { coerceStringArray } from './utils.js';
+import type { MemoryPayload } from '../types.js';
+import { invalidateCache } from '../services/neural-interface.js';
+import { computeChecksums } from '../services/file-checksums.js';
+import { text } from './response.js';
+
+export function buildReflectSchema() {
+  return {
+    memory_id: z.string().describe('The ID of the memory to update. MUST be the full UUID format (e.g., 8f7cab3b-644e-4cea-8662-de0ca695bdf2), not a shortened version. Use recall to get the full UUID.'),
+    content: z
+      .string()
+      .optional()
+      .describe(
+        'Updated content. If provided, the embedding vector is regenerated.'
+      ),
+    importance: z.coerce.number().min(1).max(10).optional().describe('Updated importance score.'),
+    tags: coerceStringArray()
+      .optional()
+      .describe('Replace all tags with these.'),
+    add_tags: coerceStringArray()
+      .optional()
+      .describe('Add tags without replacing existing ones.'),
+    subcategory: z.string().optional().describe('Updated subcategory.'),
+    category: z
+      .string()
+      .optional()
+      .describe('Change the category name.'),
+    related_files: coerceStringArray()
+      .optional()
+      .describe('Updated related file paths.'),
+    related_memory_ids: coerceStringArray()
+      .optional()
+      .describe('Link to related memories.'),
+    project: z.string().optional().describe('Change the project this memory belongs to (e.g. "criticalpixel", "synabun", "synabun-website").'),
+  };
+}
+
+export const reflectSchema = buildReflectSchema();
+
+export const reflectDescription =
+  'Update or annotate an existing memory. Use this when you discover additional context, when a decision changes, or when you want to adjust importance based on new information.';
+
+export async function handleReflect(args: {
+  memory_id: string;
+  content?: string;
+  importance?: number;
+  tags?: string[];
+  add_tags?: string[];
+  subcategory?: string;
+  category?: string;
+  related_files?: string[];
+  related_memory_ids?: string[];
+  project?: string;
+}) {
+  const memoryId = args.memory_id;
+
+  // Validate UUID format
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  if (!uuidRegex.test(memoryId)) {
+    return text(`Invalid memory_id format. Expected full UUID (e.g., 8f7cab3b-644e-4cea-8662-de0ca695bdf2), got: ${memoryId}\n\nUse the full UUID returned by 'remember', or call 'recall' to find the full UUID of an existing memory.`);
+  }
+
+  if (args.category) {
+    const catCheck = validateCategory(args.category);
+    if (!catCheck.valid) {
+      return text(catCheck.error!);
+    }
+  }
+
+  const existing = await getMemory(memoryId);
+  if (!existing) {
+    return text(`Memory "${memoryId}" not found.`);
+  }
+
+  const payload = existing.payload as unknown as MemoryPayload;
+  const now = new Date().toISOString();
+  const updates: Partial<MemoryPayload> = { updated_at: now };
+  const changes: string[] = [];
+
+  if (args.content) {
+    updates.content = args.content;
+    changes.push('content');
+  }
+  if (args.importance !== undefined) {
+    updates.importance = args.importance;
+    changes.push(`importance -> ${args.importance}`);
+  }
+  if (args.category) {
+    updates.category = args.category;
+    changes.push(`category -> ${args.category}`);
+  }
+  if (args.subcategory) {
+    updates.subcategory = args.subcategory;
+    changes.push(`subcategory -> ${args.subcategory}`);
+  }
+  if (args.tags) {
+    updates.tags = args.tags;
+    changes.push(`tags replaced`);
+  }
+  if (args.add_tags) {
+    const existingTags = payload.tags || [];
+    updates.tags = [...new Set([...existingTags, ...args.add_tags])];
+    changes.push(`tags added: ${args.add_tags.join(', ')}`);
+  }
+  if (args.related_files) {
+    updates.related_files = args.related_files;
+    changes.push('related_files updated');
+  }
+  if (args.related_memory_ids) {
+    updates.related_memory_ids = args.related_memory_ids;
+    changes.push('related_memory_ids updated');
+  }
+  if (args.project) {
+    updates.project = args.project;
+    changes.push(`project -> ${args.project}`);
+  }
+
+  if (changes.length === 0) {
+    return text('No changes specified.');
+  }
+
+  // Recompute file checksums whenever the memory is updated
+  const finalFiles = (updates.related_files ?? payload.related_files);
+  if (finalFiles?.length) {
+    const cs = computeChecksums(finalFiles);
+    updates.file_checksums = Object.keys(cs).length > 0 ? cs : undefined;
+  }
+
+  if (args.content) {
+    const mergedPayload: MemoryPayload = { ...payload, ...updates } as MemoryPayload;
+    const vector = await generateEmbedding(mergedPayload.content);
+    await updateVector(memoryId, vector, mergedPayload);
+  } else {
+    await updatePayload(memoryId, updates);
+  }
+
+  // Invalidate Neural Interface link cache (fire-and-forget)
+  invalidateCache('reflect');
+
+  return text(`Updated [${memoryId.slice(0, 8)}]: ${changes.join(', ')}`);
+}

package/mcp-server/src/tools/remember.ts

@@ -0,0 +1,115 @@
+import { z } from 'zod';
+import { v4 as uuidv4 } from 'uuid';
+import { generateEmbedding } from '../services/local-embeddings.js';
+import { upsertMemory } from '../services/sqlite.js';
+import { validateCategory } from '../services/categories.js';
+import { coerceStringArray } from './utils.js';
+import type { MemoryPayload, MemorySource } from '../types.js';
+import { detectProject } from '../config.js';
+import { computeChecksums } from '../services/file-checksums.js';
+import { invalidateCache } from '../services/neural-interface.js';
+import { text } from './response.js';
+
+export function buildRememberSchema() {
+  return {
+    content: z
+      .string()
+      .describe('The information to remember. Be specific and include context.'),
+    category: z
+      .string()
+      .describe('Category name. Call category tool with action "list" to see valid categories.'),
+  project: z
+    .string()
+    .optional()
+    .describe(
+      'Project this belongs to (e.g. "criticalpixel"). Defaults to auto-detected from working directory.'
+    ),
+  tags: coerceStringArray()
+    .optional()
+    .describe('Tags for categorization (e.g. ["redis", "cache", "pricing"])'),
+  importance: z
+    .coerce.number()
+    .min(1)
+    .max(10)
+    .optional()
+    .describe(
+      '1=trivial, 5=normal, 7=significant, 8+=critical. Default 5. Use 8+ for hard-won bug fixes and architecture decisions.'
+    ),
+  subcategory: z
+    .string()
+    .optional()
+    .describe(
+      'Optional refinement: architecture, bug-fix, api-quirk, performance, config, deployment, etc.'
+    ),
+  source: z
+    .enum(['user-told', 'self-discovered', 'auto-saved'] as const)
+    .optional()
+    .describe(
+      'How this was learned. user-told=user explicitly shared, self-discovered=found during work, auto-saved=session context.'
+    ),
+  related_files: coerceStringArray()
+    .optional()
+    .describe('File paths this memory relates to.'),
+  };
+}
+
+export const rememberSchema = buildRememberSchema();
+
+export const rememberDescription =
+  'Store a piece of information in persistent memory. Use this when you learn something important, make a decision, discover a pattern, fix a hard bug, or want to preserve context for future sessions.';
+
+export async function handleRemember(args: {
+  content: string;
+  category: string;
+  project?: string;
+  tags?: string[];
+  importance?: number;
+  subcategory?: string;
+  source?: string;
+  related_files?: string[];
+}) {
+  const catCheck = validateCategory(args.category);
+  if (!catCheck.valid) {
+    return text(catCheck.error!);
+  }
+
+  const content = args.content;
+  const category = args.category;
+  const project = args.project || detectProject();
+  const tags = args.tags || [];
+  const importance = args.importance ?? 5;
+  const subcategory = args.subcategory;
+  const source = (args.source as MemorySource) || 'self-discovered';
+  const related_files = args.related_files;
+
+  const id = uuidv4();
+  const now = new Date().toISOString();
+
+  const payload: MemoryPayload = {
+    content,
+    category,
+    subcategory,
+    project,
+    tags,
+    importance,
+    source,
+    created_at: now,
+    updated_at: now,
+    accessed_at: now,
+    access_count: 0,
+    related_files,
+    file_checksums: (() => {
+      if (!related_files?.length) return undefined;
+      const cs = computeChecksums(related_files);
+      return Object.keys(cs).length > 0 ? cs : undefined;
+    })(),
+  };
+
+  const vector = await generateEmbedding(content);
+  await upsertMemory(id, vector, payload);
+
+  // Invalidate Neural Interface link cache (fire-and-forget)
+  invalidateCache('remember');
+
+  return text(`Remembered [${id}] (${category}/${project}, importance: ${importance}): "${content.slice(0, 100)}${content.length > 100 ? '...' : ''}"`);
+}