claude-memory-layer 1.0.0

package/src/hooks/post-tool-use.ts

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+/**
+ * PostToolUse Hook
+ * Called after each tool execution - stores tool observations
+ */
+
+import { getDefaultMemoryService } from '../services/memory-service.js';
+import { applyPrivacyFilter, maskSensitiveInput, truncateOutput } from '../core/privacy/index.js';
+import { extractMetadata, createToolObservationEmbedding } from '../core/metadata-extractor.js';
+import type { PostToolUseInput, ToolObservationPayload, Config } from '../core/types.js';
+
+// Default config (will be overridden by actual config when available)
+const DEFAULT_CONFIG: Config['toolObservation'] = {
+  enabled: true,
+  excludedTools: ['TodoWrite', 'TodoRead'],
+  maxOutputLength: 10000,
+  maxOutputLines: 100,
+  storeOnlyOnSuccess: false
+};
+
+const DEFAULT_PRIVACY_CONFIG: Config['privacy'] = {
+  excludePatterns: ['password', 'secret', 'api_key', 'token', 'bearer'],
+  anonymize: false,
+  privateTags: {
+    enabled: true,
+    marker: '[PRIVATE]',
+    preserveLineCount: false,
+    supportedFormats: ['xml']
+  }
+};
+
+/**
+ * Calculate duration from ISO timestamps
+ */
+function calculateDuration(startedAt: string, endedAt: string): number {
+  const start = new Date(startedAt).getTime();
+  const end = new Date(endedAt).getTime();
+  return end - start;
+}
+
+async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: PostToolUseInput = JSON.parse(inputData);
+
+  const config = DEFAULT_CONFIG;
+  const privacyConfig = DEFAULT_PRIVACY_CONFIG;
+
+  // 1. Check if tool observation is enabled
+  if (!config.enabled) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  // 2. Check if tool is excluded
+  if (config.excludedTools?.includes(input.tool_name)) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  // 3. Check success filter
+  const success = !input.tool_error;
+  if (!success && config.storeOnlyOnSuccess) {
+    console.log(JSON.stringify({}));
+    return;
+  }
+
+  try {
+    const memoryService = getDefaultMemoryService();
+
+    // 4. Mask sensitive data in input
+    const maskedInput = maskSensitiveInput(input.tool_input);
+
+    // 5. Apply privacy filter to output
+    const filterResult = applyPrivacyFilter(input.tool_output, privacyConfig);
+    const maskedOutput = filterResult.content;
+
+    // 6. Truncate output
+    const truncatedOutput = truncateOutput(maskedOutput, {
+      maxLength: config.maxOutputLength,
+      maxLines: config.maxOutputLines
+    });
+
+    // 7. Extract metadata
+    const metadata = extractMetadata(
+      input.tool_name,
+      maskedInput,
+      input.tool_output,
+      success
+    );
+
+    // 8. Create payload
+    const payload: ToolObservationPayload = {
+      toolName: input.tool_name,
+      toolInput: maskedInput,
+      toolOutput: truncatedOutput,
+      durationMs: calculateDuration(input.started_at, input.ended_at),
+      success,
+      errorMessage: input.tool_error,
+      metadata
+    };
+
+    // 9. Store observation
+    await memoryService.storeToolObservation(input.session_id, payload);
+
+    // Output empty (hook doesn't return context)
+    console.log(JSON.stringify({}));
+  } catch (error) {
+    console.error('PostToolUse hook error:', error);
+    console.log(JSON.stringify({}));
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}
+
+main().catch(console.error);

package/src/hooks/session-end.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Session End Hook
+ * Called when session ends - generates and stores session summary
+ */
+
+import { getDefaultMemoryService } from '../services/memory-service.js';
+import type { SessionEndInput } from '../core/types.js';
+
+async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: SessionEndInput = JSON.parse(inputData);
+
+  const memoryService = getDefaultMemoryService();
+
+  try {
+    // Get session history
+    const sessionEvents = await memoryService.getSessionHistory(input.session_id);
+
+    if (sessionEvents.length > 0) {
+      // Generate a simple session summary
+      const summary = generateSummary(sessionEvents);
+
+      // Store session summary
+      await memoryService.storeSessionSummary(input.session_id, summary);
+
+      // End session with summary
+      await memoryService.endSession(input.session_id, summary);
+
+      // Process any pending embeddings
+      await memoryService.processPendingEmbeddings();
+    }
+
+    console.log(JSON.stringify({}));
+  } catch (error) {
+    console.error('Memory hook error:', error);
+    console.log(JSON.stringify({}));
+  }
+}
+
+/**
+ * Generate a simple session summary from events
+ */
+function generateSummary(events: Array<{ eventType: string; content: string }>): string {
+  const userPrompts = events.filter(e => e.eventType === 'user_prompt');
+  const responses = events.filter(e => e.eventType === 'agent_response');
+
+  const parts: string[] = [];
+
+  parts.push(`Session with ${userPrompts.length} user prompts and ${responses.length} responses.`);
+
+  // Add first few user prompts as topics
+  if (userPrompts.length > 0) {
+    parts.push('Topics discussed:');
+    for (const prompt of userPrompts.slice(0, 3)) {
+      const topic = prompt.content.slice(0, 100).replace(/\n/g, ' ');
+      parts.push(`- ${topic}${prompt.content.length > 100 ? '...' : ''}`);
+    }
+  }
+
+  return parts.join('\n');
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}
+
+main().catch(console.error);

package/src/hooks/session-start.ts

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * Session Start Hook
+ * Called when a new Claude Code session starts
+ */
+
+import { getDefaultMemoryService } from '../services/memory-service.js';
+import type { SessionStartInput, SessionStartOutput } from '../core/types.js';
+
+async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: SessionStartInput = JSON.parse(inputData);
+
+  const memoryService = getDefaultMemoryService();
+
+  try {
+    // Start session in memory service
+    await memoryService.startSession(input.session_id, input.cwd);
+
+    // Get recent context for this project
+    const recentEvents = await memoryService.getRecentEvents(10);
+    const projectEvents = recentEvents.filter(e =>
+      e.metadata?.projectPath === input.cwd
+    );
+
+    let context = '';
+    if (projectEvents.length > 0) {
+      context = `## Previous Session Context\n\nYou have worked on this project before. Here are some relevant memories:\n\n`;
+      for (const event of projectEvents.slice(0, 3)) {
+        const date = event.timestamp.toISOString().split('T')[0];
+        context += `- **${date}**: ${event.content.slice(0, 150)}...\n`;
+      }
+    }
+
+    const output: SessionStartOutput = { context };
+    console.log(JSON.stringify(output));
+  } catch (error) {
+    console.error('Memory hook error:', error);
+    console.log(JSON.stringify({ context: '' }));
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}
+
+main().catch(console.error);

package/src/hooks/stop.ts

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+/**
+ * Stop Hook
+ * Called when agent stops - stores the conversation messages
+ */
+
+import { getDefaultMemoryService } from '../services/memory-service.js';
+import { applyPrivacyFilter } from '../core/privacy/index.js';
+import type { StopInput, Config } from '../core/types.js';
+
+// Default privacy config
+const DEFAULT_PRIVACY_CONFIG: Config['privacy'] = {
+  excludePatterns: ['password', 'secret', 'api_key', 'token', 'bearer'],
+  anonymize: false,
+  privateTags: {
+    enabled: true,
+    marker: '[PRIVATE]',
+    preserveLineCount: false,
+    supportedFormats: ['xml']
+  }
+};
+
+async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: StopInput = JSON.parse(inputData);
+
+  const memoryService = getDefaultMemoryService();
+
+  try {
+    // Store agent responses from the conversation
+    for (const message of input.messages) {
+      if (message.role === 'assistant' && message.content) {
+        // Apply privacy filter
+        const filterResult = applyPrivacyFilter(message.content, DEFAULT_PRIVACY_CONFIG);
+        let content = filterResult.content;
+
+        // Truncate very long responses
+        if (content.length > 5000) {
+          content = content.slice(0, 5000) + '...[truncated]';
+        }
+
+        await memoryService.storeAgentResponse(
+          input.session_id,
+          content,
+          {
+            stopReason: input.stop_reason,
+            privacy: filterResult.metadata
+          }
+        );
+      }
+    }
+
+    // Process embeddings immediately
+    await memoryService.processPendingEmbeddings();
+
+    // Output empty (stop hook doesn't return context)
+    console.log(JSON.stringify({}));
+  } catch (error) {
+    console.error('Memory hook error:', error);
+    console.log(JSON.stringify({}));
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}
+
+main().catch(console.error);

package/src/hooks/user-prompt-submit.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+/**
+ * User Prompt Submit Hook
+ * Called when user submits a prompt - retrieves relevant memories
+ */
+
+import { getDefaultMemoryService } from '../services/memory-service.js';
+import type { UserPromptSubmitInput, UserPromptSubmitOutput } from '../core/types.js';
+
+async function main(): Promise<void> {
+  // Read input from stdin
+  const inputData = await readStdin();
+  const input: UserPromptSubmitInput = JSON.parse(inputData);
+
+  const memoryService = getDefaultMemoryService();
+
+  try {
+    // Retrieve relevant memories for the prompt
+    const retrievalResult = await memoryService.retrieveMemories(input.prompt, {
+      topK: 5,
+      minScore: 0.7
+    });
+
+    // Store the user prompt for future retrieval
+    await memoryService.storeUserPrompt(
+      input.session_id,
+      input.prompt
+    );
+
+    // Format context for Claude
+    const context = memoryService.formatAsContext(retrievalResult);
+
+    const output: UserPromptSubmitOutput = { context };
+    console.log(JSON.stringify(output));
+  } catch (error) {
+    console.error('Memory hook error:', error);
+    console.log(JSON.stringify({ context: '' }));
+  }
+}
+
+function readStdin(): Promise<string> {
+  return new Promise((resolve) => {
+    let data = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      data += chunk;
+    });
+    process.stdin.on('end', () => {
+      resolve(data);
+    });
+  });
+}
+
+main().catch(console.error);

package/src/mcp/handlers.ts

@@ -0,0 +1,212 @@
+/**
+ * MCP Tool Handlers
+ * Implementation of tool calls
+ */
+
+import { getDefaultMemoryService } from '../services/memory-service.js';
+import { generateCitationId } from '../core/citation-generator.js';
+
+interface ToolResult {
+  content: Array<{ type: string; text: string }>;
+  isError?: boolean;
+}
+
+export async function handleToolCall(
+  name: string,
+  args: Record<string, unknown>
+): Promise<ToolResult> {
+  try {
+    const memoryService = getDefaultMemoryService();
+    await memoryService.initialize();
+
+    switch (name) {
+      case 'mem-search':
+        return await handleMemSearch(args);
+
+      case 'mem-timeline':
+        return await handleMemTimeline(args);
+
+      case 'mem-details':
+        return await handleMemDetails(args);
+
+      case 'mem-stats':
+        return await handleMemStats();
+
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true
+        };
+    }
+  } catch (error) {
+    return {
+      content: [{ type: 'text', text: `Error: ${(error as Error).message}` }],
+      isError: true
+    };
+  }
+}
+
+async function handleMemSearch(args: Record<string, unknown>): Promise<ToolResult> {
+  const query = args.query as string;
+  const topK = Math.min((args.topK as number) || 5, 20);
+
+  const memoryService = getDefaultMemoryService();
+  const result = await memoryService.retrieveMemories(query, {
+    topK,
+    sessionId: args.sessionId as string
+  });
+
+  const lines: string[] = [
+    '## Memory Search Results',
+    '',
+    `Found ${result.memories.length} relevant memories:`,
+    ''
+  ];
+
+  for (let i = 0; i < result.memories.length; i++) {
+    const m = result.memories[i];
+    const citationId = generateCitationId(m.event.id);
+    const date = m.event.timestamp.toISOString().split('T')[0];
+    const preview = m.event.content.slice(0, 100) + (m.event.content.length > 100 ? '...' : '');
+
+    lines.push(`### ${i + 1}. [mem:${citationId}] (score: ${m.score.toFixed(2)})`);
+    lines.push(`**Type**: ${m.event.eventType} | **Date**: ${date}`);
+    lines.push(`> ${preview}`);
+    lines.push('');
+  }
+
+  lines.push('---');
+  lines.push('*Use `mem-details` with IDs for full content.*');
+
+  return {
+    content: [{ type: 'text', text: lines.join('\n') }]
+  };
+}
+
+async function handleMemTimeline(args: Record<string, unknown>): Promise<ToolResult> {
+  const ids = args.ids as string[];
+  const windowSize = (args.windowSize as number) || 3;
+
+  const memoryService = getDefaultMemoryService();
+  const recentEvents = await memoryService.getRecentEvents(10000);
+
+  const lines: string[] = [
+    '## Timeline Context',
+    ''
+  ];
+
+  for (const targetId of ids) {
+    // Find the target event
+    const targetEvent = recentEvents.find(e =>
+      e.id === targetId || generateCitationId(e.id) === targetId
+    );
+
+    if (!targetEvent) {
+      lines.push(`Event ${targetId} not found.`);
+      continue;
+    }
+
+    // Get session events
+    const sessionEvents = recentEvents
+      .filter(e => e.sessionId === targetEvent.sessionId)
+      .sort((a, b) => a.timestamp.getTime() - b.timestamp.getTime());
+
+    const eventIndex = sessionEvents.findIndex(e => e.id === targetEvent.id);
+    const start = Math.max(0, eventIndex - windowSize);
+    const end = Math.min(sessionEvents.length, eventIndex + windowSize + 1);
+
+    lines.push(`### Session: ${targetEvent.sessionId.slice(0, 8)}`);
+    lines.push('');
+
+    for (let i = start; i < end; i++) {
+      const e = sessionEvents[i];
+      const isTarget = e.id === targetEvent.id;
+      const marker = isTarget ? '**→**' : '   ';
+      const time = e.timestamp.toLocaleTimeString();
+      const preview = e.content.slice(0, 60) + (e.content.length > 60 ? '...' : '');
+      const citationId = generateCitationId(e.id);
+
+      lines.push(`${marker} ${time} [${citationId}] ${e.eventType}: ${preview}`);
+    }
+
+    lines.push('');
+  }
+
+  return {
+    content: [{ type: 'text', text: lines.join('\n') }]
+  };
+}
+
+async function handleMemDetails(args: Record<string, unknown>): Promise<ToolResult> {
+  const ids = args.ids as string[];
+
+  const memoryService = getDefaultMemoryService();
+  const recentEvents = await memoryService.getRecentEvents(10000);
+
+  const lines: string[] = [];
+
+  for (const targetId of ids) {
+    const event = recentEvents.find(e =>
+      e.id === targetId || generateCitationId(e.id) === targetId
+    );
+
+    if (!event) {
+      lines.push(`## Event ${targetId} not found.`);
+      lines.push('');
+      continue;
+    }
+
+    const citationId = generateCitationId(event.id);
+    const date = event.timestamp.toISOString();
+
+    lines.push(`## Memory: [mem:${citationId}]`);
+    lines.push('');
+    lines.push(`**Session**: ${event.sessionId}`);
+    lines.push(`**Type**: ${event.eventType}`);
+    lines.push(`**Date**: ${date}`);
+    lines.push('');
+    lines.push('**Content**:');
+    lines.push('```');
+    lines.push(event.content);
+    lines.push('```');
+    lines.push('');
+    lines.push('---');
+    lines.push('');
+  }
+
+  return {
+    content: [{ type: 'text', text: lines.join('\n') }]
+  };
+}
+
+async function handleMemStats(): Promise<ToolResult> {
+  const memoryService = getDefaultMemoryService();
+  const stats = await memoryService.getStats();
+  const recentEvents = await memoryService.getRecentEvents(10000);
+
+  const uniqueSessions = new Set(recentEvents.map(e => e.sessionId));
+
+  const lines: string[] = [
+    '## Memory Statistics',
+    '',
+    `- **Total Events**: ${stats.totalEvents}`,
+    `- **Total Vectors**: ${stats.vectorCount}`,
+    `- **Sessions**: ${uniqueSessions.size}`,
+    '',
+    '### Events by Type',
+    ''
+  ];
+
+  const eventsByType = recentEvents.reduce((acc, e) => {
+    acc[e.eventType] = (acc[e.eventType] || 0) + 1;
+    return acc;
+  }, {} as Record<string, number>);
+
+  for (const [type, count] of Object.entries(eventsByType)) {
+    lines.push(`- ${type}: ${count}`);
+  }
+
+  return {
+    content: [{ type: 'text', text: lines.join('\n') }]
+  };
+}

package/src/mcp/index.ts

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for Claude Desktop
+ * Provides memory search tools via Model Context Protocol
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  ListToolsRequestSchema,
+  CallToolRequestSchema
+} from '@modelcontextprotocol/sdk/types.js';
+
+import { tools } from './tools.js';
+import { handleToolCall } from './handlers.js';
+
+const server = new Server(
+  {
+    name: 'code-memory-mcp',
+    version: '1.0.0'
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+
+// Tool listing handler
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+// Tool call handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+  return handleToolCall(name, args || {});
+});
+
+// Start server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('code-memory MCP server started');
+}
+
+main().catch(console.error);