kotadb 2.0.1-next.20260203000100 → 2.0.1-next.20260203164934

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kotadb",
-  "version": "2.0.1-next.20260203000100",
+  "version": "2.0.1-next.20260203164934",
   "description": "Local-only code intelligence tool for CLI agents. SQLite-backed repository indexing and code search via MCP.",
   "type": "module",
   "module": "src/index.ts",

package/src/api/openapi/builder.ts

@@ -184,7 +184,7 @@ Repository indexing and advanced code intelligence operations are available via
 	const duration = Date.now() - startTime;
 	const pathCount = Object.keys(spec.paths || {}).length;
 
-	process.stdout.write(JSON.stringify({
+	process.stderr.write(JSON.stringify({
 		level: 'info',
 		module: 'openapi-builder',
 		message: 'OpenAPI spec generated',

package/src/db/migrations/004_memory_layer.sql

@@ -0,0 +1,183 @@
+-- SQLite Migration: Memory Layer Schema Extensions
+--
+-- Migration: 004_memory_layer
+-- Issue: Memory Layer for Agent Intelligence
+-- Author: Claude Code
+-- Date: 2026-02-03
+--
+-- This migration extends the memory layer tables with additional schema:
+-- - decisions: Add status column (active, superseded, deprecated)
+-- - failed_approaches: Alternative to failures with clearer naming
+-- - pattern_annotations: Enhanced patterns with evidence/confidence scoring
+-- - agent_sessions: Track agent work sessions
+-- - session_insights: Insights linked to sessions with file references
+--
+-- Note: The base sqlite-schema.sql already has decisions, failures, patterns,
+-- and insights tables. This migration adds enhanced versions and the missing
+-- agent_sessions table for complete session tracking.
+
+-- ============================================================================
+-- 1. Extend Decisions Table - Add status column
+-- ============================================================================
+-- Add status column to track decision lifecycle
+
+ALTER TABLE decisions ADD COLUMN status TEXT DEFAULT 'active';
+
+-- Add index for active decisions (most common query)
+CREATE INDEX IF NOT EXISTS idx_decisions_status ON decisions(status) WHERE status = 'active';
+
+-- ============================================================================
+-- 2. Failed Approaches Table (alternative to failures with clearer naming)
+-- ============================================================================
+-- Tracks what didn't work to prevent repeating mistakes
+
+CREATE TABLE IF NOT EXISTS failed_approaches (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    repository_id TEXT NOT NULL,                 -- Foreign key to repositories
+    title TEXT NOT NULL,                         -- Short description
+    problem TEXT NOT NULL,                       -- What problem was being solved
+    approach TEXT NOT NULL,                      -- What was tried
+    failure_reason TEXT NOT NULL,                -- Why it failed
+    related_files TEXT,                          -- JSON array of related file paths
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    
+    FOREIGN KEY (repository_id) REFERENCES repositories(id) ON DELETE CASCADE
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_failed_approaches_repository_id ON failed_approaches(repository_id);
+CREATE INDEX IF NOT EXISTS idx_failed_approaches_created_at ON failed_approaches(created_at DESC);
+
+-- ============================================================================
+-- 3. Failed Approaches FTS5 Virtual Table
+-- ============================================================================
+-- External content FTS5 for searching failed approaches
+
+CREATE VIRTUAL TABLE IF NOT EXISTS failed_approaches_fts USING fts5(
+    title,
+    problem,
+    approach,
+    failure_reason,
+    content='failed_approaches',
+    content_rowid='rowid'
+);
+
+-- ============================================================================
+-- 4. Failed Approaches FTS5 Sync Triggers
+-- ============================================================================
+
+-- After INSERT: Add new failed approach to FTS index
+CREATE TRIGGER IF NOT EXISTS failed_approaches_fts_ai 
+AFTER INSERT ON failed_approaches 
+BEGIN
+    INSERT INTO failed_approaches_fts(rowid, title, problem, approach, failure_reason) 
+    VALUES (new.rowid, new.title, new.problem, new.approach, new.failure_reason);
+END;
+
+-- After DELETE: Remove failed approach from FTS index
+CREATE TRIGGER IF NOT EXISTS failed_approaches_fts_ad 
+AFTER DELETE ON failed_approaches 
+BEGIN
+    INSERT INTO failed_approaches_fts(failed_approaches_fts, rowid, title, problem, approach, failure_reason) 
+    VALUES ('delete', old.rowid, old.title, old.problem, old.approach, old.failure_reason);
+END;
+
+-- After UPDATE: Update failed approach in FTS index (delete old, insert new)
+CREATE TRIGGER IF NOT EXISTS failed_approaches_fts_au 
+AFTER UPDATE ON failed_approaches 
+BEGIN
+    INSERT INTO failed_approaches_fts(failed_approaches_fts, rowid, title, problem, approach, failure_reason) 
+    VALUES ('delete', old.rowid, old.title, old.problem, old.approach, old.failure_reason);
+    INSERT INTO failed_approaches_fts(rowid, title, problem, approach, failure_reason) 
+    VALUES (new.rowid, new.title, new.problem, new.approach, new.failure_reason);
+END;
+
+-- ============================================================================
+-- 5. Pattern Annotations Table
+-- ============================================================================
+-- Enhanced pattern detection with evidence counting and confidence scoring
+
+CREATE TABLE IF NOT EXISTS pattern_annotations (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    repository_id TEXT NOT NULL,                 -- Foreign key to repositories
+    pattern_type TEXT NOT NULL,                  -- Pattern category (logging, error-handling, testing, etc.)
+    pattern_name TEXT NOT NULL,                  -- Pattern identifier
+    description TEXT NOT NULL,                   -- Human-readable description
+    example_code TEXT,                           -- Code example (optional)
+    evidence_count INTEGER NOT NULL DEFAULT 1,   -- Number of occurrences found
+    confidence REAL NOT NULL DEFAULT 1.0,        -- Confidence score (0.0-1.0)
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    
+    FOREIGN KEY (repository_id) REFERENCES repositories(id) ON DELETE CASCADE,
+    
+    CHECK (confidence >= 0.0 AND confidence <= 1.0),
+    CHECK (evidence_count >= 1)
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_pattern_annotations_repository_id ON pattern_annotations(repository_id);
+CREATE INDEX IF NOT EXISTS idx_pattern_annotations_pattern_type ON pattern_annotations(pattern_type);
+CREATE INDEX IF NOT EXISTS idx_pattern_annotations_confidence ON pattern_annotations(confidence DESC);
+-- Composite index for high-confidence patterns by type
+CREATE INDEX IF NOT EXISTS idx_pattern_annotations_type_confidence 
+ON pattern_annotations(repository_id, pattern_type, confidence DESC);
+
+-- ============================================================================
+-- 6. Agent Sessions Table
+-- ============================================================================
+-- Tracks agent work sessions for learning and analysis
+
+CREATE TABLE IF NOT EXISTS agent_sessions (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    repository_id TEXT NOT NULL,                 -- Foreign key to repositories
+    agent_type TEXT,                             -- Type of agent (plan, build, improve, etc.)
+    task_summary TEXT,                           -- What the agent was working on
+    outcome TEXT,                                -- Session outcome
+    files_modified TEXT,                         -- JSON array of modified file paths
+    started_at TEXT NOT NULL DEFAULT (datetime('now')),
+    ended_at TEXT,                               -- NULL if session is ongoing
+    
+    FOREIGN KEY (repository_id) REFERENCES repositories(id) ON DELETE CASCADE,
+    
+    CHECK (outcome IS NULL OR outcome IN ('success', 'failure', 'partial'))
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_agent_sessions_repository_id ON agent_sessions(repository_id);
+CREATE INDEX IF NOT EXISTS idx_agent_sessions_agent_type ON agent_sessions(agent_type) WHERE agent_type IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agent_sessions_outcome ON agent_sessions(outcome) WHERE outcome IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_agent_sessions_started_at ON agent_sessions(started_at DESC);
+-- Partial index for ongoing sessions
+CREATE INDEX IF NOT EXISTS idx_agent_sessions_ongoing ON agent_sessions(repository_id) WHERE ended_at IS NULL;
+
+-- ============================================================================
+-- 7. Session Insights Table
+-- ============================================================================
+-- Insights discovered during agent sessions with proper foreign keys
+
+CREATE TABLE IF NOT EXISTS session_insights (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    session_id TEXT NOT NULL,                    -- Foreign key to agent_sessions
+    insight_type TEXT NOT NULL,                  -- Type of insight
+    content TEXT NOT NULL,                       -- The insight content
+    related_file_id TEXT,                        -- Optional reference to indexed_files
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    
+    FOREIGN KEY (session_id) REFERENCES agent_sessions(id) ON DELETE CASCADE,
+    FOREIGN KEY (related_file_id) REFERENCES indexed_files(id) ON DELETE SET NULL,
+    
+    CHECK (insight_type IN ('discovery', 'failure', 'workaround'))
+);
+
+-- Indexes for common queries
+CREATE INDEX IF NOT EXISTS idx_session_insights_session_id ON session_insights(session_id);
+CREATE INDEX IF NOT EXISTS idx_session_insights_insight_type ON session_insights(insight_type);
+CREATE INDEX IF NOT EXISTS idx_session_insights_related_file ON session_insights(related_file_id) 
+WHERE related_file_id IS NOT NULL;
+CREATE INDEX IF NOT EXISTS idx_session_insights_created_at ON session_insights(created_at DESC);
+
+-- ============================================================================
+-- 8. Record Migration
+-- ============================================================================
+
+INSERT OR IGNORE INTO schema_migrations (name) VALUES ('004_memory_layer');

package/src/db/sqlite-schema.sql

@@ -258,6 +258,213 @@ CREATE TABLE IF NOT EXISTS schema_migrations (
 
 CREATE INDEX IF NOT EXISTS idx_schema_migrations_applied ON schema_migrations(applied_at DESC);
 
+
+-- ============================================================================
+-- 10. Memory Layer Tables (Agent Learning & Knowledge Persistence)
+-- ============================================================================
+-- These tables support the memory layer for cross-session knowledge persistence.
+-- They enable agents to record decisions, track failures, and share insights.
+--
+-- Issue: Memory Layer Implementation
+-- Author: Claude Code
+-- Date: 2026-02-03
+
+-- ============================================================================
+-- 10.1 Decisions Table - Architectural and design decisions
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    repository_id TEXT,                          -- Foreign key to repositories (nullable)
+    title TEXT NOT NULL,                         -- Decision title/summary
+    context TEXT NOT NULL,                       -- Context/background for the decision
+    decision TEXT NOT NULL,                      -- The actual decision made
+    scope TEXT NOT NULL,                         -- Decision scope
+    rationale TEXT,                              -- Why this decision was made
+    alternatives TEXT DEFAULT '[]',              -- JSON array of considered alternatives
+    related_files TEXT DEFAULT '[]',             -- JSON array of related file paths
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+    metadata TEXT DEFAULT '{}',                  -- Additional metadata as JSON
+    
+    FOREIGN KEY (repository_id) REFERENCES repositories(id) ON DELETE CASCADE,
+    CHECK (scope IN ('architecture', 'pattern', 'convention', 'workaround'))
+);
+
+-- Indexes for decisions
+CREATE INDEX IF NOT EXISTS idx_decisions_repository_id ON decisions(repository_id);
+CREATE INDEX IF NOT EXISTS idx_decisions_scope ON decisions(scope);
+CREATE INDEX IF NOT EXISTS idx_decisions_created_at ON decisions(created_at DESC);
+
+-- FTS5 virtual table for decision search
+CREATE VIRTUAL TABLE IF NOT EXISTS decisions_fts USING fts5(
+    title,
+    context,
+    decision,
+    rationale,
+    content='decisions',
+    content_rowid='rowid'
+);
+
+-- FTS5 sync triggers for decisions
+CREATE TRIGGER IF NOT EXISTS decisions_fts_ai 
+AFTER INSERT ON decisions 
+BEGIN
+    INSERT INTO decisions_fts(rowid, title, context, decision, rationale) 
+    VALUES (new.rowid, new.title, new.context, new.decision, new.rationale);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_fts_ad 
+AFTER DELETE ON decisions 
+BEGIN
+    INSERT INTO decisions_fts(decisions_fts, rowid, title, context, decision, rationale) 
+    VALUES ('delete', old.rowid, old.title, old.context, old.decision, old.rationale);
+END;
+
+CREATE TRIGGER IF NOT EXISTS decisions_fts_au 
+AFTER UPDATE ON decisions 
+BEGIN
+    INSERT INTO decisions_fts(decisions_fts, rowid, title, context, decision, rationale) 
+    VALUES ('delete', old.rowid, old.title, old.context, old.decision, old.rationale);
+    INSERT INTO decisions_fts(rowid, title, context, decision, rationale) 
+    VALUES (new.rowid, new.title, new.context, new.decision, new.rationale);
+END;
+
+-- ============================================================================
+-- 10.2 Failures Table - Failed approaches to avoid repeating mistakes
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS failures (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    repository_id TEXT,                          -- Foreign key to repositories (nullable)
+    title TEXT NOT NULL,                         -- Failure title/summary
+    problem TEXT NOT NULL,                       -- The problem being solved
+    approach TEXT NOT NULL,                      -- The approach that was tried
+    failure_reason TEXT NOT NULL,                -- Why it failed
+    related_files TEXT DEFAULT '[]',             -- JSON array of related file paths
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    metadata TEXT DEFAULT '{}',                  -- Additional metadata as JSON
+    
+    FOREIGN KEY (repository_id) REFERENCES repositories(id) ON DELETE CASCADE
+);
+
+-- Indexes for failures
+CREATE INDEX IF NOT EXISTS idx_failures_repository_id ON failures(repository_id);
+CREATE INDEX IF NOT EXISTS idx_failures_created_at ON failures(created_at DESC);
+
+-- FTS5 virtual table for failure search
+CREATE VIRTUAL TABLE IF NOT EXISTS failures_fts USING fts5(
+    title,
+    problem,
+    approach,
+    failure_reason,
+    content='failures',
+    content_rowid='rowid'
+);
+
+-- FTS5 sync triggers for failures
+CREATE TRIGGER IF NOT EXISTS failures_fts_ai 
+AFTER INSERT ON failures 
+BEGIN
+    INSERT INTO failures_fts(rowid, title, problem, approach, failure_reason) 
+    VALUES (new.rowid, new.title, new.problem, new.approach, new.failure_reason);
+END;
+
+CREATE TRIGGER IF NOT EXISTS failures_fts_ad 
+AFTER DELETE ON failures 
+BEGIN
+    INSERT INTO failures_fts(failures_fts, rowid, title, problem, approach, failure_reason) 
+    VALUES ('delete', old.rowid, old.title, old.problem, old.approach, old.failure_reason);
+END;
+
+CREATE TRIGGER IF NOT EXISTS failures_fts_au 
+AFTER UPDATE ON failures 
+BEGIN
+    INSERT INTO failures_fts(failures_fts, rowid, title, problem, approach, failure_reason) 
+    VALUES ('delete', old.rowid, old.title, old.problem, old.approach, old.failure_reason);
+    INSERT INTO failures_fts(rowid, title, problem, approach, failure_reason) 
+    VALUES (new.rowid, new.title, new.problem, new.approach, new.failure_reason);
+END;
+
+-- ============================================================================
+-- 10.3 Patterns Table - Discovered codebase patterns
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS patterns (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    repository_id TEXT,                          -- Foreign key to repositories (nullable)
+    pattern_type TEXT NOT NULL,                  -- Type of pattern (e.g., 'error-handling', 'api-call')
+    file_path TEXT,                              -- File where pattern was observed
+    description TEXT NOT NULL,                   -- Description of the pattern
+    example TEXT,                                -- Code example of the pattern
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    metadata TEXT DEFAULT '{}',                  -- Additional metadata as JSON
+    
+    FOREIGN KEY (repository_id) REFERENCES repositories(id) ON DELETE CASCADE
+);
+
+-- Indexes for patterns
+CREATE INDEX IF NOT EXISTS idx_patterns_repository_id ON patterns(repository_id);
+CREATE INDEX IF NOT EXISTS idx_patterns_pattern_type ON patterns(pattern_type);
+CREATE INDEX IF NOT EXISTS idx_patterns_file_path ON patterns(file_path);
+CREATE INDEX IF NOT EXISTS idx_patterns_created_at ON patterns(created_at DESC);
+
+-- ============================================================================
+-- 10.4 Insights Table - Session insights for future agents
+-- ============================================================================
+
+CREATE TABLE IF NOT EXISTS insights (
+    id TEXT PRIMARY KEY,                         -- uuid → TEXT
+    session_id TEXT,                             -- Session identifier (optional)
+    content TEXT NOT NULL,                       -- The insight content
+    insight_type TEXT NOT NULL,                  -- Type of insight
+    related_file TEXT,                           -- Related file path (optional)
+    created_at TEXT NOT NULL DEFAULT (datetime('now')),
+    metadata TEXT DEFAULT '{}',                  -- Additional metadata as JSON
+    
+    CHECK (insight_type IN ('discovery', 'failure', 'workaround'))
+);
+
+-- Indexes for insights
+CREATE INDEX IF NOT EXISTS idx_insights_session_id ON insights(session_id);
+CREATE INDEX IF NOT EXISTS idx_insights_insight_type ON insights(insight_type);
+CREATE INDEX IF NOT EXISTS idx_insights_related_file ON insights(related_file);
+CREATE INDEX IF NOT EXISTS idx_insights_created_at ON insights(created_at DESC);
+
+-- FTS5 virtual table for insight search
+CREATE VIRTUAL TABLE IF NOT EXISTS insights_fts USING fts5(
+    content,
+    content='insights',
+    content_rowid='rowid'
+);
+
+-- FTS5 sync triggers for insights
+CREATE TRIGGER IF NOT EXISTS insights_fts_ai 
+AFTER INSERT ON insights 
+BEGIN
+    INSERT INTO insights_fts(rowid, content) 
+    VALUES (new.rowid, new.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS insights_fts_ad 
+AFTER DELETE ON insights 
+BEGIN
+    INSERT INTO insights_fts(insights_fts, rowid, content) 
+    VALUES ('delete', old.rowid, old.content);
+END;
+
+CREATE TRIGGER IF NOT EXISTS insights_fts_au 
+AFTER UPDATE ON insights 
+BEGIN
+    INSERT INTO insights_fts(insights_fts, rowid, content) 
+    VALUES ('delete', old.rowid, old.content);
+    INSERT INTO insights_fts(rowid, content) 
+    VALUES (new.rowid, new.content);
+END;
+
+-- Record memory layer migration
+INSERT OR IGNORE INTO schema_migrations (name) VALUES ('002_memory_layer_tables');
+
 -- Record this migration
 INSERT OR IGNORE INTO schema_migrations (name) VALUES ('001_initial_sqlite_schema');
 

package/src/instrument.ts

@@ -26,9 +26,6 @@ if (process.env.NODE_ENV !== "test") {
 			// Privacy compliance: don't send IP addresses or user agents automatically
 			sendDefaultPii: false,
 
-			// Enable debug mode in development
-			debug: isDevelopment,
-
 			// Scrub sensitive headers before sending to Sentry
 			beforeSend(event, hint) {
 				// Remove sensitive headers
@@ -61,7 +58,7 @@ if (process.env.NODE_ENV !== "test") {
 		});
 
 		if (isDevelopment && process.env.SENTRY_DSN) {
-			process.stdout.write(
+			process.stderr.write(
 				JSON.stringify({
 					timestamp: new Date().toISOString(),
 					level: "info",

package/src/logging/logger.ts

@@ -100,19 +100,12 @@ function maskSensitiveData(context: LogContext): LogContext {
 }
 
 /**
- * Format and write log entry to stdout (info/debug/warn) or stderr (error)
+ * Format and write log entry to stderr (all logs go to stderr to keep stdout clean for JSON output)
  */
-function writeLog(entry: LogEntry, forceStderr = false): void {
+function writeLog(entry: LogEntry, _forceStderr = false): void {
 	const json = JSON.stringify(entry);
-	const output = `${json}\n`;
-
-	if (forceStderr || entry.level === "error") {
-		process.stderr.write(output);
-	} else {
-		process.stdout.write(output);
-	}
+	process.stderr.write(`${json}\n`);
 }
-
 /**
  * Create a logger instance with optional correlation context
  */

package/src/mcp/server.ts

@@ -23,6 +23,14 @@ import {
 	SYNC_EXPORT_TOOL,
 	SYNC_IMPORT_TOOL,
 	VALIDATE_IMPLEMENTATION_SPEC_TOOL,
+	// Memory Layer tools
+	SEARCH_DECISIONS_TOOL,
+	RECORD_DECISION_TOOL,
+	SEARCH_FAILURES_TOOL,
+	RECORD_FAILURE_TOOL,
+	SEARCH_PATTERNS_TOOL,
+	RECORD_INSIGHT_TOOL,
+	// Execute functions
 	executeAnalyzeChangeImpact,
 	executeGenerateTaskContext,
 	executeIndexRepository,
@@ -32,6 +40,13 @@ import {
 	executeSyncExport,
 	executeSyncImport,
 	executeValidateImplementationSpec,
+	// Memory Layer execute functions
+	executeSearchDecisions,
+	executeRecordDecision,
+	executeSearchFailures,
+	executeRecordFailure,
+	executeSearchPatterns,
+	executeRecordInsight,
 } from "./tools";
 
 const logger = createLogger({ module: "mcp-server" });
@@ -58,6 +73,12 @@ export interface McpServerContext {
  * - kota_sync_export: Export SQLite to JSONL
  * - kota_sync_import: Import JSONL to SQLite
  * - generate_task_context: Generate context for hook-based seeding
+ * - search_decisions: Search past architectural decisions
+ * - record_decision: Record a new architectural decision
+ * - search_failures: Search failed approaches
+ * - record_failure: Record a failed approach
+ * - search_patterns: Find codebase patterns
+ * - record_insight: Store a session insight
  */
 export function createMcpServer(context: McpServerContext): Server {
 	const server = new Server(
@@ -85,6 +106,13 @@ export function createMcpServer(context: McpServerContext): Server {
 				SYNC_EXPORT_TOOL,
 				SYNC_IMPORT_TOOL,
 				GENERATE_TASK_CONTEXT_TOOL,
+				// Memory Layer tools
+				SEARCH_DECISIONS_TOOL,
+				RECORD_DECISION_TOOL,
+				SEARCH_FAILURES_TOOL,
+				RECORD_FAILURE_TOOL,
+				SEARCH_PATTERNS_TOOL,
+				RECORD_INSIGHT_TOOL,
 			],
 		};
 	});
@@ -154,6 +182,49 @@ export function createMcpServer(context: McpServerContext): Server {
 						context.userId,
 					);
 					break;
+				// Memory Layer tools
+				case "search_decisions":
+					result = await executeSearchDecisions(
+						toolArgs,
+						"", // requestId not used
+						context.userId,
+					);
+					break;
+				case "record_decision":
+					result = await executeRecordDecision(
+						toolArgs,
+						"", // requestId not used
+						context.userId,
+					);
+					break;
+				case "search_failures":
+					result = await executeSearchFailures(
+						toolArgs,
+						"", // requestId not used
+						context.userId,
+					);
+					break;
+				case "record_failure":
+					result = await executeRecordFailure(
+						toolArgs,
+						"", // requestId not used
+						context.userId,
+					);
+					break;
+				case "search_patterns":
+					result = await executeSearchPatterns(
+						toolArgs,
+						"", // requestId not used
+						context.userId,
+					);
+					break;
+				case "record_insight":
+					result = await executeRecordInsight(
+						toolArgs,
+						"", // requestId not used
+						context.userId,
+					);
+					break;
 				default:
 					const error = new Error(`Unknown tool: ${name}`);
 					logger.error("Unknown MCP tool requested", error, {

package/src/mcp/tools.ts

@@ -372,6 +372,230 @@ export const GENERATE_TASK_CONTEXT_TOOL: ToolDefinition = {
 	},
 };
 
+// ============================================================================
+// Memory Layer Tool Definitions
+// ============================================================================
+
+/**
+ * Tool: search_decisions
+ */
+export const SEARCH_DECISIONS_TOOL: ToolDefinition = {
+	name: "search_decisions",
+	description:
+		"Search past architectural decisions using FTS5. Returns decisions with relevance scores.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			query: {
+				type: "string",
+				description: "Search query for decisions",
+			},
+			scope: {
+				type: "string",
+				enum: ["architecture", "pattern", "convention", "workaround"],
+				description: "Optional: Filter by decision scope",
+			},
+			repository: {
+				type: "string",
+				description: "Optional: Filter to a specific repository ID or full_name",
+			},
+			limit: {
+				type: "number",
+				description: "Optional: Max results (default: 20)",
+			},
+		},
+		required: ["query"],
+	},
+};
+
+/**
+ * Tool: record_decision
+ */
+export const RECORD_DECISION_TOOL: ToolDefinition = {
+	name: "record_decision",
+	description:
+		"Record a new architectural decision for future reference. Decisions are searchable via search_decisions.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			title: {
+				type: "string",
+				description: "Decision title/summary",
+			},
+			context: {
+				type: "string",
+				description: "Context and background for the decision",
+			},
+			decision: {
+				type: "string",
+				description: "The actual decision made",
+			},
+			scope: {
+				type: "string",
+				enum: ["architecture", "pattern", "convention", "workaround"],
+				description: "Decision scope/category (default: pattern)",
+			},
+			rationale: {
+				type: "string",
+				description: "Optional: Why this decision was made",
+			},
+			alternatives: {
+				type: "array",
+				items: { type: "string" },
+				description: "Optional: Alternatives that were considered",
+			},
+			related_files: {
+				type: "array",
+				items: { type: "string" },
+				description: "Optional: Related file paths",
+			},
+			repository: {
+				type: "string",
+				description: "Optional: Repository ID or full_name",
+			},
+		},
+		required: ["title", "context", "decision"],
+	},
+};
+
+/**
+ * Tool: search_failures
+ */
+export const SEARCH_FAILURES_TOOL: ToolDefinition = {
+	name: "search_failures",
+	description:
+		"Search failed approaches to avoid repeating mistakes. Returns failures with relevance scores.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			query: {
+				type: "string",
+				description: "Search query for failures",
+			},
+			repository: {
+				type: "string",
+				description: "Optional: Filter to a specific repository ID or full_name",
+			},
+			limit: {
+				type: "number",
+				description: "Optional: Max results (default: 20)",
+			},
+		},
+		required: ["query"],
+	},
+};
+
+/**
+ * Tool: record_failure
+ */
+export const RECORD_FAILURE_TOOL: ToolDefinition = {
+	name: "record_failure",
+	description:
+		"Record a failed approach for future reference. Helps agents avoid repeating mistakes.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			title: {
+				type: "string",
+				description: "Failure title/summary",
+			},
+			problem: {
+				type: "string",
+				description: "The problem being solved",
+			},
+			approach: {
+				type: "string",
+				description: "The approach that was tried",
+			},
+			failure_reason: {
+				type: "string",
+				description: "Why the approach failed",
+			},
+			related_files: {
+				type: "array",
+				items: { type: "string" },
+				description: "Optional: Related file paths",
+			},
+			repository: {
+				type: "string",
+				description: "Optional: Repository ID or full_name",
+			},
+		},
+		required: ["title", "problem", "approach", "failure_reason"],
+	},
+};
+
+/**
+ * Tool: search_patterns
+ */
+export const SEARCH_PATTERNS_TOOL: ToolDefinition = {
+	name: "search_patterns",
+	description:
+		"Find codebase patterns by type or file. Returns discovered patterns for consistency.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			query: {
+				type: "string",
+				description: "Optional: Search query for pattern name/description",
+			},
+			pattern_type: {
+				type: "string",
+				description: "Optional: Filter by pattern type (e.g., error-handling, api-call)",
+			},
+			file: {
+				type: "string",
+				description: "Optional: Filter by file path",
+			},
+			repository: {
+				type: "string",
+				description: "Optional: Filter to a specific repository ID or full_name",
+			},
+			limit: {
+				type: "number",
+				description: "Optional: Max results (default: 20)",
+			},
+		},
+	},
+};
+
+/**
+ * Tool: record_insight
+ */
+export const RECORD_INSIGHT_TOOL: ToolDefinition = {
+	name: "record_insight",
+	description:
+		"Store a session insight for future agents. Insights are discoveries, failures, or workarounds.",
+	inputSchema: {
+		type: "object",
+		properties: {
+			content: {
+				type: "string",
+				description: "The insight content",
+			},
+			insight_type: {
+				type: "string",
+				enum: ["discovery", "failure", "workaround"],
+				description: "Type of insight",
+			},
+			session_id: {
+				type: "string",
+				description: "Optional: Session identifier for grouping",
+			},
+			related_file: {
+				type: "string",
+				description: "Optional: Related file path",
+			},
+			repository: {
+				type: "string",
+				description: "Optional: Repository ID or full_name",
+			},
+		},
+		required: ["content", "insight_type"],
+	},
+};
+
+
 /**
  * Get all available tool definitions
  */
@@ -386,6 +610,13 @@ export function getToolDefinitions(): ToolDefinition[] {
 		SYNC_EXPORT_TOOL,
 		SYNC_IMPORT_TOOL,
 		GENERATE_TASK_CONTEXT_TOOL,
+		// Memory Layer tools
+		SEARCH_DECISIONS_TOOL,
+		RECORD_DECISION_TOOL,
+		SEARCH_FAILURES_TOOL,
+		RECORD_FAILURE_TOOL,
+		SEARCH_PATTERNS_TOOL,
+		RECORD_INSIGHT_TOOL,
 	];
 }
 
@@ -1131,6 +1362,520 @@ function generateTestFilePatterns(sourcePath: string): string[] {
 	return patterns;
 }
 
+
+
+// ============================================================================
+// Memory Layer Tool Executors
+// ============================================================================
+
+/**
+ * Escape a term for FTS5 MATCH clause
+ */
+function escapeFts5Term(term: string): string {
+	const escaped = term.replace(/"/g, '""');
+	return `"${escaped}"`;
+}
+
+/**
+ * Execute search_decisions tool
+ */
+export async function executeSearchDecisions(
+	params: unknown,
+	_requestId: string | number,
+	_userId: string,
+): Promise<unknown> {
+	if (typeof params !== "object" || params === null) {
+		throw new Error("Parameters must be an object");
+	}
+
+	const p = params as Record<string, unknown>;
+
+	if (p.query === undefined) {
+		throw new Error("Missing required parameter: query");
+	}
+	if (typeof p.query !== "string") {
+		throw new Error("Parameter 'query' must be a string");
+	}
+
+	if (p.scope !== undefined && typeof p.scope !== "string") {
+		throw new Error("Parameter 'scope' must be a string");
+	}
+	if (p.scope !== undefined && !["architecture", "pattern", "convention", "workaround"].includes(p.scope as string)) {
+		throw new Error("Parameter 'scope' must be one of: architecture, pattern, convention, workaround");
+	}
+	if (p.repository !== undefined && typeof p.repository !== "string") {
+		throw new Error("Parameter 'repository' must be a string");
+	}
+	if (p.limit !== undefined && typeof p.limit !== "number") {
+		throw new Error("Parameter 'limit' must be a number");
+	}
+
+	const db = getGlobalDatabase();
+	const escapedQuery = escapeFts5Term(p.query as string);
+	const limit = Math.min(Math.max((p.limit as number) || 20, 1), 100);
+
+	let sql = `
+		SELECT 
+			d.id,
+			d.title,
+			d.context,
+			d.decision,
+			d.scope,
+			d.rationale,
+			d.alternatives,
+			d.related_files,
+			d.repository_id,
+			d.created_at,
+			bm25(decisions_fts) as relevance
+		FROM decisions_fts
+		JOIN decisions d ON decisions_fts.rowid = d.rowid
+		WHERE decisions_fts MATCH ?
+	`;
+	const queryParams: (string | number)[] = [escapedQuery];
+
+	if (p.scope) {
+		sql += " AND d.scope = ?";
+		queryParams.push(p.scope as string);
+	}
+
+	if (p.repository) {
+		const repoResult = resolveRepositoryIdentifierWithError(p.repository as string);
+		if (!("error" in repoResult)) {
+			sql += " AND d.repository_id = ?";
+			queryParams.push(repoResult.id);
+		}
+	}
+
+	sql += " ORDER BY relevance LIMIT ?";
+	queryParams.push(limit);
+
+	const rows = db.query<{
+		id: string;
+		title: string;
+		context: string;
+		decision: string;
+		scope: string;
+		rationale: string | null;
+		alternatives: string;
+		related_files: string;
+		repository_id: string | null;
+		created_at: string;
+		relevance: number;
+	}>(sql, queryParams);
+
+	return {
+		results: rows.map((row) => ({
+			id: row.id,
+			title: row.title,
+			context: row.context,
+			decision: row.decision,
+			scope: row.scope,
+			rationale: row.rationale,
+			alternatives: JSON.parse(row.alternatives || "[]"),
+			related_files: JSON.parse(row.related_files || "[]"),
+			repository_id: row.repository_id,
+			created_at: row.created_at,
+			relevance: Math.abs(row.relevance),
+		})),
+		count: rows.length,
+	};
+}
+
+/**
+ * Execute record_decision tool
+ */
+export async function executeRecordDecision(
+	params: unknown,
+	_requestId: string | number,
+	_userId: string,
+): Promise<unknown> {
+	if (typeof params !== "object" || params === null) {
+		throw new Error("Parameters must be an object");
+	}
+
+	const p = params as Record<string, unknown>;
+
+	if (p.title === undefined || typeof p.title !== "string") {
+		throw new Error("Missing or invalid required parameter: title");
+	}
+	if (p.context === undefined || typeof p.context !== "string") {
+		throw new Error("Missing or invalid required parameter: context");
+	}
+	if (p.decision === undefined || typeof p.decision !== "string") {
+		throw new Error("Missing or invalid required parameter: decision");
+	}
+
+	const scope = (p.scope as string) || "pattern";
+	if (!["architecture", "pattern", "convention", "workaround"].includes(scope)) {
+		throw new Error("Parameter 'scope' must be one of: architecture, pattern, convention, workaround");
+	}
+
+	if (p.rationale !== undefined && typeof p.rationale !== "string") {
+		throw new Error("Parameter 'rationale' must be a string");
+	}
+	if (p.alternatives !== undefined && !Array.isArray(p.alternatives)) {
+		throw new Error("Parameter 'alternatives' must be an array");
+	}
+	if (p.related_files !== undefined && !Array.isArray(p.related_files)) {
+		throw new Error("Parameter 'related_files' must be an array");
+	}
+	if (p.repository !== undefined && typeof p.repository !== "string") {
+		throw new Error("Parameter 'repository' must be a string");
+	}
+
+	const db = getGlobalDatabase();
+	const { randomUUID } = await import("node:crypto");
+	const id = randomUUID();
+
+	let repositoryId: string | null = null;
+	if (p.repository) {
+		const repoResult = resolveRepositoryIdentifierWithError(p.repository as string);
+		if (!("error" in repoResult)) {
+			repositoryId = repoResult.id;
+		}
+	}
+
+	const sql = `
+		INSERT INTO decisions (
+			id, repository_id, title, context, decision, scope,
+			rationale, alternatives, related_files, created_at, updated_at
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, datetime('now'), datetime('now'))
+	`;
+
+	db.run(sql, [
+		id,
+		repositoryId,
+		p.title as string,
+		p.context as string,
+		p.decision as string,
+		scope,
+		(p.rationale as string) || null,
+		JSON.stringify((p.alternatives as string[]) || []),
+		JSON.stringify((p.related_files as string[]) || []),
+	]);
+
+	logger.info("Decision recorded", { id, title: p.title, scope });
+
+	return {
+		success: true,
+		id,
+		message: "Decision recorded successfully",
+	};
+}
+
+/**
+ * Execute search_failures tool
+ */
+export async function executeSearchFailures(
+	params: unknown,
+	_requestId: string | number,
+	_userId: string,
+): Promise<unknown> {
+	if (typeof params !== "object" || params === null) {
+		throw new Error("Parameters must be an object");
+	}
+
+	const p = params as Record<string, unknown>;
+
+	if (p.query === undefined) {
+		throw new Error("Missing required parameter: query");
+	}
+	if (typeof p.query !== "string") {
+		throw new Error("Parameter 'query' must be a string");
+	}
+
+	if (p.repository !== undefined && typeof p.repository !== "string") {
+		throw new Error("Parameter 'repository' must be a string");
+	}
+	if (p.limit !== undefined && typeof p.limit !== "number") {
+		throw new Error("Parameter 'limit' must be a number");
+	}
+
+	const db = getGlobalDatabase();
+	const escapedQuery = escapeFts5Term(p.query as string);
+	const limit = Math.min(Math.max((p.limit as number) || 20, 1), 100);
+
+	let sql = `
+		SELECT 
+			f.id,
+			f.title,
+			f.problem,
+			f.approach,
+			f.failure_reason,
+			f.related_files,
+			f.repository_id,
+			f.created_at,
+			bm25(failures_fts) as relevance
+		FROM failures_fts
+		JOIN failures f ON failures_fts.rowid = f.rowid
+		WHERE failures_fts MATCH ?
+	`;
+	const queryParams: (string | number)[] = [escapedQuery];
+
+	if (p.repository) {
+		const repoResult = resolveRepositoryIdentifierWithError(p.repository as string);
+		if (!("error" in repoResult)) {
+			sql += " AND f.repository_id = ?";
+			queryParams.push(repoResult.id);
+		}
+	}
+
+	sql += " ORDER BY relevance LIMIT ?";
+	queryParams.push(limit);
+
+	const rows = db.query<{
+		id: string;
+		title: string;
+		problem: string;
+		approach: string;
+		failure_reason: string;
+		related_files: string;
+		repository_id: string | null;
+		created_at: string;
+		relevance: number;
+	}>(sql, queryParams);
+
+	return {
+		results: rows.map((row) => ({
+			id: row.id,
+			title: row.title,
+			problem: row.problem,
+			approach: row.approach,
+			failure_reason: row.failure_reason,
+			related_files: JSON.parse(row.related_files || "[]"),
+			repository_id: row.repository_id,
+			created_at: row.created_at,
+			relevance: Math.abs(row.relevance),
+		})),
+		count: rows.length,
+	};
+}
+
+/**
+ * Execute record_failure tool
+ */
+export async function executeRecordFailure(
+	params: unknown,
+	_requestId: string | number,
+	_userId: string,
+): Promise<unknown> {
+	if (typeof params !== "object" || params === null) {
+		throw new Error("Parameters must be an object");
+	}
+
+	const p = params as Record<string, unknown>;
+
+	if (p.title === undefined || typeof p.title !== "string") {
+		throw new Error("Missing or invalid required parameter: title");
+	}
+	if (p.problem === undefined || typeof p.problem !== "string") {
+		throw new Error("Missing or invalid required parameter: problem");
+	}
+	if (p.approach === undefined || typeof p.approach !== "string") {
+		throw new Error("Missing or invalid required parameter: approach");
+	}
+	if (p.failure_reason === undefined || typeof p.failure_reason !== "string") {
+		throw new Error("Missing or invalid required parameter: failure_reason");
+	}
+
+	if (p.related_files !== undefined && !Array.isArray(p.related_files)) {
+		throw new Error("Parameter 'related_files' must be an array");
+	}
+	if (p.repository !== undefined && typeof p.repository !== "string") {
+		throw new Error("Parameter 'repository' must be a string");
+	}
+
+	const db = getGlobalDatabase();
+	const { randomUUID } = await import("node:crypto");
+	const id = randomUUID();
+
+	let repositoryId: string | null = null;
+	if (p.repository) {
+		const repoResult = resolveRepositoryIdentifierWithError(p.repository as string);
+		if (!("error" in repoResult)) {
+			repositoryId = repoResult.id;
+		}
+	}
+
+	const sql = `
+		INSERT INTO failures (
+			id, repository_id, title, problem, approach, failure_reason,
+			related_files, created_at
+		) VALUES (?, ?, ?, ?, ?, ?, ?, datetime('now'))
+	`;
+
+	db.run(sql, [
+		id,
+		repositoryId,
+		p.title as string,
+		p.problem as string,
+		p.approach as string,
+		p.failure_reason as string,
+		JSON.stringify((p.related_files as string[]) || []),
+	]);
+
+	logger.info("Failure recorded", { id, title: p.title });
+
+	return {
+		success: true,
+		id,
+		message: "Failure recorded successfully",
+	};
+}
+
+/**
+ * Execute search_patterns tool
+ */
+export async function executeSearchPatterns(
+	params: unknown,
+	_requestId: string | number,
+	_userId: string,
+): Promise<unknown> {
+	if (params !== undefined && (typeof params !== "object" || params === null)) {
+		throw new Error("Parameters must be an object");
+	}
+
+	const p = (params as Record<string, unknown>) || {};
+
+	if (p.query !== undefined && typeof p.query !== "string") {
+		throw new Error("Parameter 'query' must be a string");
+	}
+	if (p.pattern_type !== undefined && typeof p.pattern_type !== "string") {
+		throw new Error("Parameter 'pattern_type' must be a string");
+	}
+	if (p.file !== undefined && typeof p.file !== "string") {
+		throw new Error("Parameter 'file' must be a string");
+	}
+	if (p.repository !== undefined && typeof p.repository !== "string") {
+		throw new Error("Parameter 'repository' must be a string");
+	}
+	if (p.limit !== undefined && typeof p.limit !== "number") {
+		throw new Error("Parameter 'limit' must be a number");
+	}
+
+	const db = getGlobalDatabase();
+	const limit = Math.min(Math.max((p.limit as number) || 20, 1), 100);
+
+	let sql = `
+		SELECT 
+			id,
+			repository_id,
+			pattern_type,
+			file_path,
+			description,
+			example,
+			created_at
+		FROM patterns
+		WHERE 1=1
+	`;
+	const queryParams: (string | number)[] = [];
+
+	if (p.pattern_type) {
+		sql += " AND pattern_type = ?";
+		queryParams.push(p.pattern_type as string);
+	}
+
+	if (p.file) {
+		sql += " AND file_path = ?";
+		queryParams.push(p.file as string);
+	}
+
+	if (p.repository) {
+		const repoResult = resolveRepositoryIdentifierWithError(p.repository as string);
+		if (!("error" in repoResult)) {
+			sql += " AND repository_id = ?";
+			queryParams.push(repoResult.id);
+		}
+	}
+
+	sql += " ORDER BY created_at DESC LIMIT ?";
+	queryParams.push(limit);
+
+	const rows = db.query<{
+		id: string;
+		repository_id: string | null;
+		pattern_type: string;
+		file_path: string | null;
+		description: string;
+		example: string | null;
+		created_at: string;
+	}>(sql, queryParams);
+
+	return {
+		results: rows.map((row) => ({
+			id: row.id,
+			repository_id: row.repository_id,
+			pattern_type: row.pattern_type,
+			file_path: row.file_path,
+			description: row.description,
+			example: row.example,
+			created_at: row.created_at,
+		})),
+		count: rows.length,
+	};
+}
+
+/**
+ * Execute record_insight tool
+ */
+export async function executeRecordInsight(
+	params: unknown,
+	_requestId: string | number,
+	_userId: string,
+): Promise<unknown> {
+	if (typeof params !== "object" || params === null) {
+		throw new Error("Parameters must be an object");
+	}
+
+	const p = params as Record<string, unknown>;
+
+	if (p.content === undefined || typeof p.content !== "string") {
+		throw new Error("Missing or invalid required parameter: content");
+	}
+	if (p.insight_type === undefined || typeof p.insight_type !== "string") {
+		throw new Error("Missing or invalid required parameter: insight_type");
+	}
+	if (!["discovery", "failure", "workaround"].includes(p.insight_type as string)) {
+		throw new Error("Parameter 'insight_type' must be one of: discovery, failure, workaround");
+	}
+
+	if (p.session_id !== undefined && typeof p.session_id !== "string") {
+		throw new Error("Parameter 'session_id' must be a string");
+	}
+	if (p.related_file !== undefined && typeof p.related_file !== "string") {
+		throw new Error("Parameter 'related_file' must be a string");
+	}
+	if (p.repository !== undefined && typeof p.repository !== "string") {
+		throw new Error("Parameter 'repository' must be a string");
+	}
+
+	const db = getGlobalDatabase();
+	const { randomUUID } = await import("node:crypto");
+	const id = randomUUID();
+
+	const sql = `
+		INSERT INTO insights (
+			id, session_id, content, insight_type, related_file, created_at
+		) VALUES (?, ?, ?, ?, ?, datetime('now'))
+	`;
+
+	db.run(sql, [
+		id,
+		(p.session_id as string) || null,
+		p.content as string,
+		p.insight_type as string,
+		(p.related_file as string) || null,
+	]);
+
+	logger.info("Insight recorded", { id, insight_type: p.insight_type });
+
+	return {
+		success: true,
+		id,
+		message: "Insight recorded successfully",
+	};
+}
+
 /**
  * Main tool call dispatcher
  */
@@ -1159,6 +1904,19 @@ export async function handleToolCall(
 			return await executeSyncImport(params, requestId);
 		case "generate_task_context":
 			return await executeGenerateTaskContext(params, requestId, userId);
+		// Memory Layer tools
+		case "search_decisions":
+			return await executeSearchDecisions(params, requestId, userId);
+		case "record_decision":
+			return await executeRecordDecision(params, requestId, userId);
+		case "search_failures":
+			return await executeSearchFailures(params, requestId, userId);
+		case "record_failure":
+			return await executeRecordFailure(params, requestId, userId);
+		case "search_patterns":
+			return await executeSearchPatterns(params, requestId, userId);
+		case "record_insight":
+			return await executeRecordInsight(params, requestId, userId);
 		default:
 			throw invalidParams(requestId, "Unknown tool: " + toolName);
 	}