@aitytech/agentkits-memory 1.0.0

package/src/hooks/service.ts

@@ -0,0 +1,582 @@
+/**
+ * Memory Hook Service
+ *
+ * Lightweight service for hooks to store/retrieve memory.
+ * Direct SQLite access without HTTP worker (simpler than claude-mem).
+ *
+ * @module @agentkits/memory/hooks/service
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import * as path from 'node:path';
+import { createRequire } from 'node:module';
+import initSqlJs, { Database as SqlJsDatabase } from 'sql.js';
+
+// ESM-compatible require for resolving sql.js WASM path
+const require = createRequire(import.meta.url);
+import {
+  Observation,
+  SessionRecord,
+  MemoryContext,
+  generateObservationId,
+  getObservationType,
+  generateObservationTitle,
+  truncate,
+} from './types.js';
+
+/**
+ * Memory Hook Service Configuration
+ */
+export interface MemoryHookServiceConfig {
+  /** Base directory for memory storage */
+  baseDir: string;
+
+  /** Database filename */
+  dbFilename: string;
+
+  /** Maximum observations to return in context */
+  maxContextObservations: number;
+
+  /** Maximum sessions to return in context */
+  maxContextSessions: number;
+
+  /** Maximum response size to store (bytes) */
+  maxResponseSize: number;
+}
+
+const DEFAULT_CONFIG: MemoryHookServiceConfig = {
+  baseDir: '.claude/memory',
+  dbFilename: 'hooks.db',
+  maxContextObservations: 20,
+  maxContextSessions: 5,
+  maxResponseSize: 5000,
+};
+
+/**
+ * Memory Hook Service
+ *
+ * Provides direct SQLite access for hooks without HTTP overhead.
+ * Stores observations and sessions for context injection.
+ */
+export class MemoryHookService {
+  private config: MemoryHookServiceConfig;
+  private db: SqlJsDatabase | null = null;
+  private SQL: any = null;
+  private initialized: boolean = false;
+  private dbPath: string;
+
+  constructor(cwd: string, config: Partial<MemoryHookServiceConfig> = {}) {
+    this.config = { ...DEFAULT_CONFIG, ...config };
+    this.dbPath = path.join(cwd, this.config.baseDir, this.config.dbFilename);
+  }
+
+  /**
+   * Initialize the service
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) return;
+
+    // Ensure directory exists
+    const dir = path.dirname(this.dbPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+
+    // Load sql.js - use local wasm file from node_modules
+    this.SQL = await initSqlJs({
+      locateFile: (file: string) => {
+        // Try to find the wasm file in node_modules
+        const localPath = path.join(
+          path.dirname(require.resolve('sql.js')),
+          file
+        );
+        return localPath;
+      },
+    });
+
+    // Load or create database
+    if (existsSync(this.dbPath)) {
+      const buffer = readFileSync(this.dbPath);
+      this.db = new this.SQL.Database(new Uint8Array(buffer));
+    } else {
+      this.db = new this.SQL.Database();
+    }
+
+    // Create schema
+    this.createSchema();
+
+    this.initialized = true;
+  }
+
+  /**
+   * Persist database to disk
+   */
+  async persist(): Promise<void> {
+    if (!this.db) return;
+
+    const data = this.db.export();
+    const buffer = Buffer.from(data);
+    writeFileSync(this.dbPath, buffer);
+  }
+
+  /**
+   * Shutdown the service
+   */
+  async shutdown(): Promise<void> {
+    if (!this.initialized || !this.db) return;
+
+    await this.persist();
+    this.db.close();
+    this.db = null;
+    this.initialized = false;
+  }
+
+  // ===== Session Management =====
+
+  /**
+   * Initialize or get session
+   */
+  async initSession(sessionId: string, project: string, prompt?: string): Promise<SessionRecord> {
+    await this.ensureInitialized();
+
+    // Check if session exists
+    const existing = this.getSession(sessionId);
+    if (existing) {
+      return existing;
+    }
+
+    // Create new session
+    const now = Date.now();
+    this.db!.run(`
+      INSERT INTO sessions (session_id, project, prompt, started_at, observation_count, status)
+      VALUES (?, ?, ?, ?, 0, 'active')
+    `, [sessionId, project, prompt || '', now]);
+
+    await this.persist();
+
+    return {
+      id: this.db!.exec('SELECT last_insert_rowid()')[0]?.values[0]?.[0] as number || 0,
+      sessionId,
+      project,
+      prompt: prompt || '',
+      startedAt: now,
+      observationCount: 0,
+      status: 'active',
+    };
+  }
+
+  /**
+   * Get session by ID
+   */
+  getSession(sessionId: string): SessionRecord | null {
+    if (!this.db) return null;
+
+    const stmt = this.db.prepare('SELECT * FROM sessions WHERE session_id = ?');
+    stmt.bind([sessionId]);
+
+    if (stmt.step()) {
+      const row = stmt.getAsObject();
+      stmt.free();
+      return this.rowToSession(row);
+    }
+
+    stmt.free();
+    return null;
+  }
+
+  /**
+   * Complete a session with summary
+   */
+  async completeSession(sessionId: string, summary?: string): Promise<void> {
+    await this.ensureInitialized();
+
+    const now = Date.now();
+    this.db!.run(`
+      UPDATE sessions
+      SET ended_at = ?, summary = ?, status = 'completed'
+      WHERE session_id = ?
+    `, [now, summary || '', sessionId]);
+
+    await this.persist();
+  }
+
+  /**
+   * Get recent sessions
+   */
+  async getRecentSessions(project: string, limit: number = 5): Promise<SessionRecord[]> {
+    await this.ensureInitialized();
+
+    const stmt = this.db!.prepare(`
+      SELECT * FROM sessions
+      WHERE project = ?
+      ORDER BY started_at DESC
+      LIMIT ?
+    `);
+    stmt.bind([project, limit]);
+
+    const sessions: SessionRecord[] = [];
+    while (stmt.step()) {
+      sessions.push(this.rowToSession(stmt.getAsObject()));
+    }
+    stmt.free();
+
+    return sessions;
+  }
+
+  // ===== Observation Management =====
+
+  /**
+   * Store an observation
+   */
+  async storeObservation(
+    sessionId: string,
+    project: string,
+    toolName: string,
+    toolInput: unknown,
+    toolResponse: unknown,
+    cwd: string
+  ): Promise<Observation> {
+    await this.ensureInitialized();
+
+    const id = generateObservationId();
+    const now = Date.now();
+    const type = getObservationType(toolName);
+    const title = generateObservationTitle(toolName, toolInput);
+
+    // Truncate large responses
+    const inputStr = JSON.stringify(toolInput || {});
+    const responseStr = truncate(
+      JSON.stringify(toolResponse || {}),
+      this.config.maxResponseSize
+    );
+
+    this.db!.run(`
+      INSERT INTO observations (id, session_id, project, tool_name, tool_input, tool_response, cwd, timestamp, type, title)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `, [id, sessionId, project, toolName, inputStr, responseStr, cwd, now, type, title]);
+
+    // Update session observation count
+    this.db!.run(`
+      UPDATE sessions
+      SET observation_count = observation_count + 1
+      WHERE session_id = ?
+    `, [sessionId]);
+
+    await this.persist();
+
+    return {
+      id,
+      sessionId,
+      project,
+      toolName,
+      toolInput: inputStr,
+      toolResponse: responseStr,
+      cwd,
+      timestamp: now,
+      type,
+      title,
+    };
+  }
+
+  /**
+   * Get observations for a session
+   */
+  async getSessionObservations(sessionId: string, limit: number = 50): Promise<Observation[]> {
+    await this.ensureInitialized();
+
+    const stmt = this.db!.prepare(`
+      SELECT * FROM observations
+      WHERE session_id = ?
+      ORDER BY timestamp DESC
+      LIMIT ?
+    `);
+    stmt.bind([sessionId, limit]);
+
+    const observations: Observation[] = [];
+    while (stmt.step()) {
+      observations.push(this.rowToObservation(stmt.getAsObject()));
+    }
+    stmt.free();
+
+    return observations;
+  }
+
+  /**
+   * Get recent observations for a project
+   */
+  async getRecentObservations(project: string, limit: number = 20): Promise<Observation[]> {
+    await this.ensureInitialized();
+
+    const stmt = this.db!.prepare(`
+      SELECT * FROM observations
+      WHERE project = ?
+      ORDER BY timestamp DESC
+      LIMIT ?
+    `);
+    stmt.bind([project, limit]);
+
+    const observations: Observation[] = [];
+    while (stmt.step()) {
+      observations.push(this.rowToObservation(stmt.getAsObject()));
+    }
+    stmt.free();
+
+    return observations;
+  }
+
+  // ===== Context Generation =====
+
+  /**
+   * Get memory context for session start
+   */
+  async getContext(project: string): Promise<MemoryContext> {
+    await this.ensureInitialized();
+
+    const recentObservations = await this.getRecentObservations(
+      project,
+      this.config.maxContextObservations
+    );
+
+    const previousSessions = await this.getRecentSessions(
+      project,
+      this.config.maxContextSessions
+    );
+
+    // Generate markdown
+    const markdown = this.formatContextMarkdown(recentObservations, previousSessions, project);
+
+    return {
+      recentObservations,
+      previousSessions,
+      markdown,
+    };
+  }
+
+  /**
+   * Format context as markdown
+   */
+  private formatContextMarkdown(
+    observations: Observation[],
+    sessions: SessionRecord[],
+    project: string
+  ): string {
+    const lines: string[] = [];
+
+    lines.push(`# Memory Context - ${project}`);
+    lines.push('');
+    lines.push('*AgentKits CPS™ - Auto-captured session memory*');
+    lines.push('');
+
+    // Recent observations
+    if (observations.length > 0) {
+      lines.push('## Recent Activity');
+      lines.push('');
+      lines.push('| Time | Action | Details |');
+      lines.push('|------|--------|---------|');
+
+      for (const obs of observations.slice(0, 10)) {
+        const time = this.formatRelativeTime(obs.timestamp);
+        const icon = this.getObservationIcon(obs.type);
+        lines.push(`| ${time} | ${icon} ${obs.toolName} | ${obs.title || ''} |`);
+      }
+      lines.push('');
+    }
+
+    // Previous sessions
+    if (sessions.length > 0) {
+      lines.push('## Previous Sessions');
+      lines.push('');
+
+      for (const session of sessions.slice(0, 3)) {
+        const time = this.formatRelativeTime(session.startedAt);
+        const status = session.status === 'completed' ? '✓' : '→';
+        lines.push(`### ${status} Session (${time})`);
+
+        if (session.prompt) {
+          lines.push(`**Task:** ${session.prompt.substring(0, 100)}${session.prompt.length > 100 ? '...' : ''}`);
+        }
+
+        if (session.summary) {
+          lines.push(`**Summary:** ${session.summary}`);
+        }
+
+        lines.push(`*Observations: ${session.observationCount}*`);
+        lines.push('');
+      }
+    }
+
+    // No context available
+    if (observations.length === 0 && sessions.length === 0) {
+      lines.push('*No previous session context available.*');
+      lines.push('');
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Generate session summary from observations
+   */
+  async generateSummary(sessionId: string): Promise<string> {
+    const observations = await this.getSessionObservations(sessionId);
+
+    if (observations.length === 0) {
+      return 'No activity recorded in this session.';
+    }
+
+    // Group by type
+    const byType: Record<string, number> = {};
+    const files: Set<string> = new Set();
+
+    for (const obs of observations) {
+      byType[obs.type] = (byType[obs.type] || 0) + 1;
+
+      // Extract file paths
+      try {
+        const input = JSON.parse(obs.toolInput);
+        if (input.file_path || input.path) {
+          files.add(input.file_path || input.path);
+        }
+      } catch {
+        // Ignore parse errors
+      }
+    }
+
+    // Build summary
+    const parts: string[] = [];
+
+    if (byType.write) {
+      parts.push(`${byType.write} file(s) modified`);
+    }
+    if (byType.read) {
+      parts.push(`${byType.read} file(s) read`);
+    }
+    if (byType.execute) {
+      parts.push(`${byType.execute} command(s) executed`);
+    }
+    if (byType.search) {
+      parts.push(`${byType.search} search(es)`);
+    }
+
+    let summary = parts.join(', ') || 'Various operations performed';
+
+    if (files.size > 0 && files.size <= 5) {
+      summary += `. Files: ${Array.from(files).join(', ')}`;
+    } else if (files.size > 5) {
+      summary += `. ${files.size} files touched.`;
+    }
+
+    return summary;
+  }
+
+  // ===== Private Methods =====
+
+  private async ensureInitialized(): Promise<void> {
+    if (!this.initialized) {
+      await this.initialize();
+    }
+  }
+
+  private createSchema(): void {
+    if (!this.db) return;
+
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS sessions (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        session_id TEXT UNIQUE NOT NULL,
+        project TEXT NOT NULL,
+        prompt TEXT,
+        started_at INTEGER NOT NULL,
+        ended_at INTEGER,
+        observation_count INTEGER DEFAULT 0,
+        summary TEXT,
+        status TEXT DEFAULT 'active'
+      )
+    `);
+
+    this.db.run(`
+      CREATE TABLE IF NOT EXISTS observations (
+        id TEXT PRIMARY KEY,
+        session_id TEXT NOT NULL,
+        project TEXT NOT NULL,
+        tool_name TEXT NOT NULL,
+        tool_input TEXT,
+        tool_response TEXT,
+        cwd TEXT,
+        timestamp INTEGER NOT NULL,
+        type TEXT,
+        title TEXT,
+        FOREIGN KEY (session_id) REFERENCES sessions(session_id)
+      )
+    `);
+
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_obs_session ON observations(session_id)');
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_obs_project ON observations(project)');
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_obs_timestamp ON observations(timestamp)');
+    this.db.run('CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project)');
+  }
+
+  private rowToSession(row: any): SessionRecord {
+    return {
+      id: row.id as number,
+      sessionId: row.session_id as string,
+      project: row.project as string,
+      prompt: row.prompt as string,
+      startedAt: row.started_at as number,
+      endedAt: row.ended_at as number | undefined,
+      observationCount: row.observation_count as number,
+      summary: row.summary as string | undefined,
+      status: row.status as 'active' | 'completed' | 'abandoned',
+    };
+  }
+
+  private rowToObservation(row: any): Observation {
+    return {
+      id: row.id as string,
+      sessionId: row.session_id as string,
+      project: row.project as string,
+      toolName: row.tool_name as string,
+      toolInput: row.tool_input as string,
+      toolResponse: row.tool_response as string,
+      cwd: row.cwd as string,
+      timestamp: row.timestamp as number,
+      type: row.type as any,
+      title: row.title as string | undefined,
+    };
+  }
+
+  private formatRelativeTime(timestamp: number): string {
+    const now = Date.now();
+    const diff = now - timestamp;
+
+    const minutes = Math.floor(diff / 60000);
+    const hours = Math.floor(diff / 3600000);
+    const days = Math.floor(diff / 86400000);
+
+    if (minutes < 1) return 'just now';
+    if (minutes < 60) return `${minutes}m ago`;
+    if (hours < 24) return `${hours}h ago`;
+    if (days < 7) return `${days}d ago`;
+
+    return new Date(timestamp).toLocaleDateString();
+  }
+
+  private getObservationIcon(type: string): string {
+    switch (type) {
+      case 'read': return '📖';
+      case 'write': return '✏️';
+      case 'execute': return '⚡';
+      case 'search': return '🔍';
+      default: return '•';
+    }
+  }
+}
+
+/**
+ * Create a hook service for the given project directory
+ */
+export function createHookService(cwd: string): MemoryHookService {
+  return new MemoryHookService(cwd);
+}
+
+export default MemoryHookService;

package/src/hooks/session-init.ts

@@ -0,0 +1,70 @@
+/**
+ * Session Init Hook Handler (UserPromptSubmit)
+ *
+ * Initializes a session record when the user submits their first prompt.
+ * Captures the initial prompt for context.
+ *
+ * @module @agentkits/memory/hooks/session-init
+ */
+
+import {
+  NormalizedHookInput,
+  HookResult,
+  EventHandler,
+} from './types.js';
+import { MemoryHookService } from './service.js';
+
+/**
+ * Session Init Hook - UserPromptSubmit Event
+ *
+ * Called when the user submits a prompt.
+ * Creates or updates the session record with the prompt.
+ */
+export class SessionInitHook implements EventHandler {
+  private service: MemoryHookService;
+
+  constructor(service: MemoryHookService) {
+    this.service = service;
+  }
+
+  /**
+   * Execute the session init hook
+   */
+  async execute(input: NormalizedHookInput): Promise<HookResult> {
+    try {
+      // Initialize service
+      await this.service.initialize();
+
+      // Initialize or get existing session
+      await this.service.initSession(
+        input.sessionId,
+        input.project,
+        input.prompt
+      );
+
+      return {
+        continue: true,
+        suppressOutput: true,
+      };
+    } catch (error) {
+      // Log error but don't block prompt
+      console.error('[AgentKits Memory] Session init hook error:', error);
+
+      return {
+        continue: true,
+        suppressOutput: true,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+}
+
+/**
+ * Create session init hook handler
+ */
+export function createSessionInitHook(cwd: string): SessionInitHook {
+  const service = new MemoryHookService(cwd);
+  return new SessionInitHook(service);
+}
+
+export default SessionInitHook;