pi-hermes-memory 0.3.3 → 0.4.0

package/src/store/session-parser.ts

@@ -0,0 +1,214 @@
+import fs from 'node:fs';
+
+/**
+ * Parsed session data from a JSONL file.
+ */
+export interface ParsedSession {
+  id: string;
+  project: string;
+  cwd: string;
+  startedAt: string;
+  endedAt: string | null;
+  messages: ParsedMessage[];
+}
+
+/**
+ * A single parsed message from a session.
+ */
+export interface ParsedMessage {
+  id: string;
+  role: 'user' | 'assistant' | 'system';
+  content: string;
+  timestamp: string;
+  toolCalls?: string[];
+}
+
+/**
+ * Raw JSONL entry types.
+ */
+interface JsonlEntry {
+  type: string;
+  id?: string;
+  parentId?: string | null;
+  timestamp?: string;
+  cwd?: string;
+  message?: {
+    role?: string;
+    content?: unknown;
+    timestamp?: number;
+  };
+  customType?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Extract text content from a message's content array.
+ */
+function extractTextContent(content: unknown): string {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+
+  const parts: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    const b = block as Record<string, unknown>;
+
+    switch (b.type) {
+      case 'text':
+        if (typeof b.text === 'string') parts.push(b.text);
+        break;
+      case 'thinking':
+        // Skip thinking blocks — they're internal reasoning
+        break;
+      case 'tool_use':
+        // Skip tool_use blocks — we track tool calls separately
+        break;
+      case 'tool_result':
+        // Include tool result text if present
+        if (typeof b.content === 'string') {
+          parts.push(b.content);
+        } else if (Array.isArray(b.content)) {
+          for (const item of b.content) {
+            if (item && typeof item === 'object' && (item as Record<string, unknown>).type === 'text') {
+              parts.push((item as Record<string, unknown>).text as string);
+            }
+          }
+        }
+        break;
+    }
+  }
+  return parts.join('\n').trim();
+}
+
+/**
+ * Extract tool call names from a message's content array.
+ */
+function extractToolCalls(content: unknown): string[] | undefined {
+  if (!Array.isArray(content)) return undefined;
+
+  const toolNames: string[] = [];
+  for (const block of content) {
+    if (!block || typeof block !== 'object') continue;
+    const b = block as Record<string, unknown>;
+    if (b.type === 'tool_use' && typeof b.name === 'string') {
+      toolNames.push(b.name);
+    }
+  }
+  return toolNames.length > 0 ? toolNames : undefined;
+}
+
+/**
+ * Parse a Pi session JSONL file.
+ *
+ * @param filePath — Path to the .jsonl file
+ * @returns Parsed session data, or null if the file is invalid
+ */
+export function parseSessionFile(filePath: string): ParsedSession | null {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const lines = content.split('\n').filter(line => line.trim());
+
+  if (lines.length === 0) return null;
+
+  let sessionId: string | null = null;
+  let sessionCwd: string | null = null;
+  let sessionTimestamp: string | null = null;
+  const messages: ParsedMessage[] = [];
+
+  for (const line of lines) {
+    let entry: JsonlEntry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue; // Skip malformed lines
+    }
+
+    switch (entry.type) {
+      case 'session':
+        sessionId = entry.id ?? null;
+        sessionCwd = entry.cwd ?? null;
+        sessionTimestamp = entry.timestamp ?? null;
+        break;
+
+      case 'message': {
+        if (!entry.message || !entry.id || !entry.timestamp) break;
+
+        const role = entry.message.role;
+        if (role !== 'user' && role !== 'assistant' && role !== 'system') break;
+
+        const textContent = extractTextContent(entry.message.content);
+        if (!textContent) break; // Skip empty messages
+
+        const toolCalls = role === 'assistant' ? extractToolCalls(entry.message.content) : undefined;
+
+        messages.push({
+          id: entry.id,
+          role,
+          content: textContent,
+          timestamp: entry.timestamp,
+          toolCalls,
+        });
+        break;
+      }
+      // Skip other entry types (model_change, thinking_level_change, custom, etc.)
+    }
+  }
+
+  if (!sessionId || !sessionCwd || !sessionTimestamp) return null;
+
+  // Decode project name from cwd-encoded directory name
+  // The directory is named like "--Users-chandrateja-Documents-pi-hermes-memory--"
+  // We extract the last segment as the project name
+  const project = sessionCwd.split('/').pop() ?? sessionCwd;
+
+  return {
+    id: sessionId,
+    project,
+    cwd: sessionCwd,
+    startedAt: sessionTimestamp,
+    endedAt: null, // We don't know when it ended from the JSONL
+    messages,
+  };
+}
+
+/**
+ * Get all session JSONL files for a project (or all projects).
+ *
+ * @param sessionsDir — Path to ~/.pi/agent/sessions/
+ * @param projectDir — Optional: specific project directory name (e.g., "--Users-...--")
+ * @returns Array of file paths
+ */
+export function getSessionFiles(sessionsDir: string, projectDir?: string): string[] {
+  if (projectDir) {
+    const dir = `${sessionsDir}/${projectDir}`;
+    if (!fs.existsSync(dir)) return [];
+    return fs.readdirSync(dir)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => `${dir}/${f}`);
+  }
+
+  // All projects
+  if (!fs.existsSync(sessionsDir)) return [];
+  const files: string[] = [];
+  for (const dir of fs.readdirSync(sessionsDir)) {
+    const dirPath = `${sessionsDir}/${dir}`;
+    if (!fs.statSync(dirPath).isDirectory()) continue;
+    for (const f of fs.readdirSync(dirPath)) {
+      if (f.endsWith('.jsonl')) {
+        files.push(`${dirPath}/${f}`);
+      }
+    }
+  }
+  return files;
+}
+
+/**
+ * Decode a project directory name to a human-readable project name.
+ * "--Users-chandrateja-Documents-pi-hermes-memory--" → "pi-hermes-memory"
+ */
+export function decodeProjectDir(dirName: string): string {
+  // Remove leading/trailing dashes
+  const cleaned = dirName.replace(/^-+|-+$/g, '');
+  // Split by dash and take the last segment (project name)
+  const segments = cleaned.split('-');
+  return segments[segments.length - 1] ?? cleaned;
+}

package/src/store/session-search.ts

@@ -0,0 +1,134 @@
+import { DatabaseManager } from './db.js';
+
+/**
+ * Escape a string for FTS5 query syntax.
+ * Wraps the query in double quotes to treat it as a literal phrase.
+ */
+function escapeFts5Query(query: string): string {
+  // If the query already contains FTS5 operators (OR, AND, NOT, NEAR), leave it as-is
+  if (/\b(OR|AND|NOT|NEAR)\b/.test(query)) {
+    return query;
+  }
+  // Otherwise, wrap in double quotes to treat as literal phrase
+  return `"${query.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Search result from session history.
+ */
+export interface SessionSearchResult {
+  sessionId: string;
+  project: string;
+  role: string;
+  content: string;
+  timestamp: string;
+  snippet: string;
+}
+
+/**
+ * Search options for session search.
+ */
+export interface SessionSearchOptions {
+  /** Maximum number of results (default: 10) */
+  limit?: number;
+  /** Filter by project name */
+  project?: string;
+  /** Filter by role: 'user', 'assistant', 'system' */
+  role?: string;
+  /** Only return messages after this date (ISO string) */
+  since?: string;
+}
+
+/**
+ * Search across indexed session messages using FTS5.
+ *
+ * @param dbManager — Database manager instance
+ * @param query — FTS5 search query
+ * @param options — Search options
+ * @returns Array of search results with snippets
+ */
+export function searchSessions(
+  dbManager: DatabaseManager,
+  query: string,
+  options: SessionSearchOptions = {}
+): SessionSearchResult[] {
+  const db = dbManager.getDb();
+  const { limit = 10, project, role, since } = options;
+
+  // Build the query dynamically based on filters
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  // FTS5 match condition — use subquery for reliable rowid matching
+  conditions.push('m.rowid IN (SELECT rowid FROM message_fts WHERE message_fts MATCH ?)');
+  params.push(escapeFts5Query(query));
+
+  // Project filter
+  if (project) {
+    conditions.push('s.project = ?');
+    params.push(project);
+  }
+
+  // Role filter
+  if (role) {
+    conditions.push('m.role = ?');
+    params.push(role);
+  }
+
+  // Date filter
+  if (since) {
+    conditions.push('m.timestamp >= ?');
+    params.push(since);
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+  const sql = `
+    SELECT
+      m.session_id,
+      s.project,
+      m.role,
+      m.content,
+      m.timestamp,
+      m.content as snippet
+    FROM messages m
+    JOIN sessions s ON s.id = m.session_id
+    ${whereClause}
+    ORDER BY m.timestamp DESC
+    LIMIT ?
+  `;
+  params.push(limit);
+
+  try {
+    const rows = db.prepare(sql).all(...params) as Array<{
+      session_id: string;
+      project: string;
+      role: string;
+      content: string;
+      timestamp: string;
+      snippet: string;
+    }>;
+
+    // Map snake_case column names to camelCase
+    return rows.map(row => ({
+      sessionId: row.session_id,
+      project: row.project,
+      role: row.role,
+      content: row.content,
+      timestamp: row.timestamp,
+      snippet: row.snippet,
+    }));
+  } catch (err) {
+    // FTS5 can throw on malformed queries — return empty results
+    return [];
+  }
+}
+
+/**
+ * Get the total number of indexed messages.
+ */
+export function getIndexedMessageCount(dbManager: DatabaseManager): number {
+  const db = dbManager.getDb();
+  const result = db.prepare('SELECT COUNT(*) as count FROM messages').get() as { count: number };
+  return result.count;
+}

package/src/store/sqlite-memory-store.ts

@@ -0,0 +1,215 @@
+import { DatabaseManager } from './db.js';
+
+/**
+ * A memory entry stored in SQLite.
+ */
+export interface SqliteMemoryEntry {
+  id: number;
+  project: string | null;
+  target: 'memory' | 'user';
+  content: string;
+  created: string;
+  lastReferenced: string;
+}
+
+/**
+ * Add a memory entry to the SQLite store.
+ */
+export function addMemory(
+  dbManager: DatabaseManager,
+  content: string,
+  target: 'memory' | 'user' = 'memory',
+  project: string | null = null
+): SqliteMemoryEntry {
+  const db = dbManager.getDb();
+  const today = new Date().toISOString().split('T')[0];
+
+  const result = db.prepare(`
+    INSERT INTO memories (project, target, content, created, last_referenced)
+    VALUES (?, ?, ?, ?, ?)
+  `).run(project, target, content, today, today);
+
+  return {
+    id: Number(result.lastInsertRowid),
+    project,
+    target,
+    content,
+    created: today,
+    lastReferenced: today,
+  };
+}
+
+/**
+ * Escape a string for FTS5 query syntax.
+ * Wraps the query in double quotes to treat it as a literal phrase.
+ */
+function escapeFts5Query(query: string): string {
+  // If the query already contains FTS5 operators (OR, AND, NOT, NEAR), leave it as-is
+  if (/\b(OR|AND|NOT|NEAR)\b/.test(query)) {
+    return query;
+  }
+  // Otherwise, wrap in double quotes to treat as literal phrase
+  return `"${query.replace(/"/g, '""')}"`;
+}
+
+/**
+ * Search memories using FTS5.
+ */
+export function searchMemories(
+  dbManager: DatabaseManager,
+  query: string,
+  options: { project?: string; target?: string; limit?: number } = {}
+): SqliteMemoryEntry[] {
+  const db = dbManager.getDb();
+  const { project, target, limit = 10 } = options;
+
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  // FTS5 match via subquery with escaped query
+  conditions.push('m.id IN (SELECT rowid FROM memory_fts WHERE memory_fts MATCH ?)');
+  params.push(escapeFts5Query(query));
+
+  if (project !== undefined) {
+    if (project === null) {
+      conditions.push('m.project IS NULL');
+    } else {
+      conditions.push('m.project = ?');
+      params.push(project);
+    }
+  }
+
+  if (target) {
+    conditions.push('m.target = ?');
+    params.push(target);
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+  const sql = `
+    SELECT id, project, target, content, created, last_referenced
+    FROM memories m
+    ${whereClause}
+    ORDER BY m.last_referenced DESC
+    LIMIT ?
+  `;
+  params.push(limit);
+
+  const rows = db.prepare(sql).all(...params) as Array<{
+    id: number;
+    project: string | null;
+    target: string;
+    content: string;
+    created: string;
+    last_referenced: string;
+  }>;
+
+  return rows.map(row => ({
+    id: row.id,
+    project: row.project,
+    target: row.target as 'memory' | 'user',
+    content: row.content,
+    created: row.created,
+    lastReferenced: row.last_referenced,
+  }));
+}
+
+/**
+ * Get all memories, optionally filtered.
+ */
+export function getMemories(
+  dbManager: DatabaseManager,
+  options: { project?: string | null; target?: string } = {}
+): SqliteMemoryEntry[] {
+  const db = dbManager.getDb();
+  const { project, target } = options;
+
+  const conditions: string[] = [];
+  const params: unknown[] = [];
+
+  if (project !== undefined) {
+    if (project === null) {
+      conditions.push('project IS NULL');
+    } else {
+      conditions.push('project = ?');
+      params.push(project);
+    }
+  }
+
+  if (target) {
+    conditions.push('target = ?');
+    params.push(target);
+  }
+
+  const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : '';
+
+  const rows = db.prepare(`
+    SELECT id, project, target, content, created, last_referenced
+    FROM memories
+    ${whereClause}
+    ORDER BY last_referenced DESC
+  `).all(...params) as Array<{
+    id: number;
+    project: string | null;
+    target: string;
+    content: string;
+    created: string;
+    last_referenced: string;
+  }>;
+
+  return rows.map(row => ({
+    id: row.id,
+    project: row.project,
+    target: row.target as 'memory' | 'user',
+    content: row.content,
+    created: row.created,
+    lastReferenced: row.last_referenced,
+  }));
+}
+
+/**
+ * Remove a memory by ID.
+ */
+export function removeMemory(dbManager: DatabaseManager, id: number): boolean {
+  const db = dbManager.getDb();
+  const result = db.prepare('DELETE FROM memories WHERE id = ?').run(id);
+  return result.changes > 0;
+}
+
+/**
+ * Update a memory's last_referenced date.
+ */
+export function touchMemory(dbManager: DatabaseManager, id: number): void {
+  const db = dbManager.getDb();
+  const today = new Date().toISOString().split('T')[0];
+  db.prepare('UPDATE memories SET last_referenced = ? WHERE id = ?').run(today, id);
+}
+
+/**
+ * Get memory statistics.
+ */
+export function getMemoryStats(dbManager: DatabaseManager): {
+  total: number;
+  byProject: { project: string | null; count: number }[];
+  byTarget: { target: string; count: number }[];
+} {
+  const db = dbManager.getDb();
+
+  const total = (db.prepare('SELECT COUNT(*) as count FROM memories').get() as { count: number }).count;
+
+  const byProject = db.prepare(`
+    SELECT project, COUNT(*) as count
+    FROM memories
+    GROUP BY project
+    ORDER BY count DESC
+  `).all() as { project: string | null; count: number }[];
+
+  const byTarget = db.prepare(`
+    SELECT target, COUNT(*) as count
+    FROM memories
+    GROUP BY target
+    ORDER BY count DESC
+  `).all() as { target: string; count: number }[];
+
+  return { total, byProject, byTarget };
+}

package/src/tools/memory-search-tool.ts

@@ -0,0 +1,78 @@
+import { DatabaseManager } from '../store/db.js';
+import { searchMemories, getMemoryStats } from '../store/sqlite-memory-store.js';
+
+export function registerMemorySearchTool(ctx: {
+  registerTool: (tool: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<string>;
+  }) => void;
+}, dbManager: DatabaseManager) {
+  ctx.registerTool({
+    name: 'memory_search',
+    description: `Search extended memory store for relevant entries. Use this when you need context beyond what's in the system prompt — the extended store has unlimited capacity and is searchable.
+
+Use cases:
+- Find memories about a specific topic: "What do I know about auth setup?"
+- Search project-specific memories: "What conventions does project X follow?"
+- Find user preferences: "What are the user's testing preferences?"
+
+Returns matching memory entries with project context and dates.`,
+    parameters: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Search query. Use natural language or specific terms.',
+        },
+        project: {
+          type: 'string',
+          description: 'Filter by project name. Pass null for global memories only.',
+        },
+        target: {
+          type: 'string',
+          enum: ['memory', 'user'],
+          description: 'Filter by target type (memory or user).',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum results to return (default: 10, max: 20).',
+        },
+      },
+      required: ['query'],
+    },
+    handler: async (args: Record<string, unknown>) => {
+      const query = args.query as string;
+      const project = args.project as string | undefined;
+      const target = args.target as string | undefined;
+      const limit = Math.min((args.limit as number) || 10, 20);
+
+      if (!query || query.trim().length === 0) {
+        return 'Error: query is required';
+      }
+
+      const stats = getMemoryStats(dbManager);
+      if (stats.total === 0) {
+        return 'No memories in extended store yet. Use the memory tool with add action to store memories.';
+      }
+
+      const results = searchMemories(dbManager, query, { project, target, limit });
+
+      if (results.length === 0) {
+        return `No memories found matching "${query}". Try a different search term or broader query.`;
+      }
+
+      let output = `Found ${results.length} memories matching "${query}":\n\n`;
+
+      for (const entry of results) {
+        const projectLabel = entry.project ? `[${entry.project}]` : '[global]';
+        const targetLabel = entry.target === 'user' ? '👤' : '🧠';
+        output += `${targetLabel} ${projectLabel} ${entry.content}\n`;
+        output += `   Created: ${entry.created} | Last used: ${entry.lastReferenced}\n\n`;
+      }
+
+      return output.trim();
+    },
+  });
+}