squish-memory 1.1.5 → 1.2.0

package/core/places/walking.ts

@@ -0,0 +1,192 @@
+/**
+ * Walking Interface - Sequential memory retrieval through places
+ * 
+ * Implements place walking through memory places:
+ * - Walk single place to get memories in order
+ * - Walk all places for full tour
+ * - Token budget handling with TOON compression
+ */
+
+import { getDb } from '../../db/index.js';
+import { getSchema } from '../../db/schema.js';
+import { getProjectPlaces, type Place } from './places.js';
+import { getPlaceMemories } from './memory-places.js';
+import { getMemory } from '../memory/memories.js';
+import { compressForContext, isCompressed } from '../compression.js';
+import { logger } from '../logger.js';
+
+export interface WalkOptions {
+  tokenBudget?: number;  // Max tokens (default: 170)
+  maxMemoriesPerPlace?: number;
+  includePurpose?: boolean;
+  compressWithCompression?: boolean;
+}
+
+export interface WalkResult {
+  place: Place;
+  memories: MemorySummary[];
+  totalTokens: number;
+  truncated: boolean;
+}
+
+export interface MemorySummary {
+  id: string;
+  content: string;
+  type: string;
+  tags: string[];
+  createdAt: string;
+}
+
+/**
+ * Walk through a single place
+ */
+export async function walkPlace(
+  projectId: string,
+  placeType: string,
+  options: WalkOptions = {}
+): Promise<WalkResult | null> {
+  const { tokenBudget = 170, maxMemoriesPerPlace = 10, includePurpose = true, compressWithCompression = false } = options;
+
+  // Get the place
+  const places = await getProjectPlaces(projectId);
+  const place = places.find(p => p.placeType === placeType);
+  
+  if (!place) {
+    logger.warn(`[Walking] Place not found: ${placeType}`);
+    return null;
+  }
+
+  // Get memory IDs for this place
+  const memoryIds = await getPlaceMemories(place.id, maxMemoriesPerPlace);
+
+  // Get full memories
+  const memories: MemorySummary[] = [];
+  let totalTokens = 0;
+
+  for (const memoryId of memoryIds) {
+    const memory = await getMemory(memoryId);
+    if (!memory) continue;
+
+    let content = memory.content || '';
+    
+    // Compress with TOON if requested
+    if (compressWithCompression && content) {
+      content = compressForContext(content);
+    }
+
+    const tokenEstimate = Math.ceil(content.length / 4); // rough token estimate
+    
+    if (totalTokens + tokenEstimate > tokenBudget) {
+      // Would exceed budget - stop adding
+      break;
+    }
+
+    memories.push({
+      id: memory.id,
+      content,
+      type: memory.type,
+      tags: memory.tags || [],
+      createdAt: memory.createdAt || '',
+    });
+
+    totalTokens += tokenEstimate;
+  }
+
+  return {
+    place,
+    memories,
+    totalTokens,
+    truncated: memories.length < memoryIds.length,
+  };
+}
+
+/**
+  * Walk through all places in sort order
+ */
+export async function walkAllPlaces(
+  projectId: string,
+  options: WalkOptions = {}
+): Promise<WalkResult[]> {
+  const places = await getProjectPlaces(projectId);
+  const results: WalkResult[] = [];
+
+  for (const place of places) {
+    const walkResult = await walkPlace(projectId, place.placeType, options);
+    if (walkResult && walkResult.memories.length > 0) {
+      results.push(walkResult);
+    }
+  }
+
+  logger.info(`[Walking] Walked ${results.length} places for project ${projectId}`);
+  return results;
+}
+
+/**
+ * Quick tour - just place names and purposes (minimal tokens)
+ */
+export async function quickTour(projectId: string): Promise<{
+  places: { name: string; purpose: string; memoryCount: number }[];
+  totalMemories: number;
+}> {
+  const places = await getProjectPlaces(projectId);
+  
+  return {
+    places: places.map(p => ({
+      name: p.name,
+      purpose: p.purpose || '',
+      memoryCount: p.memoryCount,
+    })),
+    totalMemories: places.reduce((sum, p) => sum + p.memoryCount, 0),
+  };
+}
+
+/**
+ * Get context summary for a place (for injection)
+ */
+export async function getPlaceContext(
+  projectId: string,
+  placeType: string,
+  maxTokens: number = 50
+): Promise<string> {
+  const walkResult = await walkPlace(projectId, placeType, {
+    tokenBudget: maxTokens,
+    compressWithCompression: true,
+  });
+
+  if (!walkResult || walkResult.memories.length === 0) {
+    return '';
+  }
+
+  const lines = walkResult.memories.map((m, i) => 
+    `${i + 1}. [${m.type}] ${m.content.substring(0, 100)}`
+  );
+
+  return `## ${walkResult.place.name}\n${lines.join('\n')}`;
+}
+
+/**
+ * Full context for session start (all places)
+ */
+export async function getFullWalkingContext(
+  projectId: string,
+  maxTokens: number = 170
+): Promise<string> {
+  const results = await walkAllPlaces(projectId, {
+    tokenBudget: Math.floor(maxTokens / 7), // Distribute across 7 places
+    compressWithCompression: true,
+  });
+
+  if (results.length === 0) {
+    return 'No memories yet. Start building your spatial memory!';
+  }
+
+  const sections = results.map(r => {
+    const lines = r.memories.slice(0, 3).map((m, i) => 
+      `  ${i + 1}. ${m.content.substring(0, 60)}...`
+    ).join('\n');
+    
+    return `## ${r.place.name}\n${lines}`;
+  });
+
+  return sections.join('\n\n');
+}

package/core/projects

@@ -0,0 +1,89 @@
+// Deterministic Memory Requirements
+import { eq } from 'drizzle-orm';
+import { getSchema } from '../db/schema.js';
+import { buildMemoryFilters, buildMemoryFiltersPartial } from './utils/filter-builder.js';
+import { executeMemoryQuery, executeMemoryAssertion, MemoryRequirementError } from './utils/query-operations.js';
+
+export interface MemoryCriteria {
+  tag?: string;
+  type?: string;
+  types?: string[];
+  sector?: string;
+  minAge?: number;
+  maxAge?: number;
+  minConfidence?: number;
+  minRelevance?: number;
+  projectId?: string;
+  agentId?: string;
+  visibilityScope?: string;
+}
+
+export async function requireMemory(criteria: MemoryCriteria): Promise<any> {
+  const schema = await getSchema();
+  const filters = buildMemoryFilters(criteria, schema);
+
+  const memories = await executeMemoryAssertion(
+    criteria,
+    filters,
+    1,
+    'memory requirement',
+    'Required memory not found'
+  );
+
+  return memories[0];
+}
+
+export async function assertMemoryPresent(memoryId: string): Promise<void> {
+  const criteria = { memoryId };
+  const schema = await getSchema();
+  const filters = [eq(schema.memories.id, memoryId)];
+
+  await executeMemoryAssertion(
+    criteria,
+    filters,
+    1,
+    'asserting memory presence',
+    'Required memory is not present: ' + memoryId
+  );
+}
+
+export async function assertMemoryNotPresent(criteria: MemoryCriteria): Promise<void> {
+  const schema = await getSchema();
+  const filters = buildMemoryFiltersPartial(criteria, schema);
+
+  await executeMemoryAssertion(
+    criteria,
+    filters,
+    0,
+    'checking memory non-presence',
+    'Memory should not exist but was found'
+  );
+}
+
+export async function requireMemories(criteria: MemoryCriteria, minCount: number = 1): Promise<any[]> {
+  const schema = await getSchema();
+  const filters = buildMemoryFilters(criteria, schema);
+
+  return executeMemoryAssertion(
+    criteria,
+    filters,
+    minCount,
+    'checking memory requirements',
+    `Required ${minCount} memories but found fewer`
+  );
+}
+
+export async function requireHighConfidenceMemory(
+  criteria: MemoryCriteria,
+  minConfidence: number = 80
+): Promise<any> {
+  return requireMemory({ ...criteria, minConfidence });
+}
+
+export async function requireRecentMemory(
+  criteria: MemoryCriteria,
+  maxAgeDays: number = 7
+): Promise<any> {
+  const maxAge = maxAgeDays * 24 * 60 * 60 * 1000;
+  return requireMemory({ ...criteria, maxAge });
+}

package/core/projects.ts

@@ -0,0 +1,131 @@
+import { basename } from 'path';
+import { randomUUID } from 'crypto';
+import { eq } from 'drizzle-orm';
+import { getDb } from '../db/index.js';
+import { getSchema } from '../db/schema.js';
+import { serializeMetadata, deserializeMetadata } from './memory/serialization.js';
+import { config } from '../config.js';
+import { createDatabaseClient } from './storage/database.js';
+
+export interface ProjectRecord {
+  id: string;
+  name: string;
+  path: string;
+  description?: string | null;
+  metadata?: Record<string, unknown> | null;
+}
+
+export async function getProjectByPath(path: string): Promise<ProjectRecord | null> {
+  try {
+    const db = createDatabaseClient(await getDb());
+    const schema = await getSchema();
+    const rows = await db.select().from(schema.projects).where(eq(schema.projects.path, path)).limit(1);
+    const row = rows[0];
+    if (!row) return null;
+    return normalizeProject(row);
+  } catch (error: any) {
+    throw error;
+  }
+}
+
+export async function ensureProject(path?: string): Promise<ProjectRecord | null> {
+  if (!path) return null;
+  const existing = await getProjectByPath(path);
+  if (existing) return existing;
+
+  const db = createDatabaseClient(await getDb());
+  const schema = await getSchema();
+  const id = randomUUID();
+  const name = basename(path) || path;
+  const metadata = { source: 'mcp' };
+
+  await db.insert(schema.projects).values({
+    id,
+    name,
+    path,
+    metadata: serializeMetadata(metadata),
+  });
+
+  return { id, name, path, metadata };
+}
+
+export class ProjectNotFoundError extends Error {
+  constructor(path: string) {
+    super(`Project not found: ${path}`);
+    this.name = 'ProjectNotFoundError';
+  }
+}
+
+export async function requireProject(path: string): Promise<ProjectRecord> {
+  const project = await getProjectByPath(path);
+  if (!project) {
+    throw new ProjectNotFoundError(path);
+  }
+  return project;
+}
+
+export async function getOrCreateProject(path?: string): Promise<ProjectRecord | null> {
+  if (!path) return null;
+  const existing = await getProjectByPath(path);
+  if (existing) return existing;
+
+  const db = createDatabaseClient(await getDb());
+  const schema = await getSchema();
+  const id = randomUUID();
+  const name = basename(path) || path;
+  const metadata = { source: 'mcp' };
+
+  await db.insert(schema.projects).values({
+    id,
+    name,
+    path,
+    metadata: serializeMetadata(metadata),
+  });
+
+  return { id, name, path, metadata };
+}
+
+function normalizeProject(row: any): ProjectRecord {
+  const metadata = deserializeMetadata(row.metadata ?? null);
+  return {
+    id: row.id,
+    name: row.name,
+    path: row.path,
+    description: row.description ?? null,
+    metadata,
+  };
+}
+
+export async function getAllProjects(): Promise<ProjectRecord[]> {
+  try {
+    const db = createDatabaseClient(await getDb());
+    const schema = await getSchema();
+    const rows = await db.select().from(schema.projects);
+    
+    // Auto-create default project if none exist
+    if (rows.length === 0) {
+      const cwd = process.cwd();
+      const defaultProject = await getOrCreateProject(cwd);
+      if (defaultProject) {
+        return [defaultProject];
+      }
+    }
+    
+    return rows.map(normalizeProject);
+  } catch (error: any) {
+    throw error;
+  }
+}
+
+export async function getProjectById(id: string): Promise<ProjectRecord | null> {
+  try {
+    const db = createDatabaseClient(await getDb());
+    const schema = await getSchema();
+    const rows = await db.select().from(schema.projects).where(eq(schema.projects.id, id)).limit(1);
+    const row = rows[0];
+    if (!row) return null;
+    return normalizeProject(row);
+  } catch (error: any) {
+    throw error;
+  }
+}

package/core/redis.ts

@@ -0,0 +1,82 @@
+import { createClient, RedisClientType } from 'redis';
+import { performRedisPublish } from './utils/memory-operations.js';
+import { logger } from './logger.js';
+
+const REDIS_URL = process.env.REDIS_URL || 'redis://localhost:6379';
+
+let client: RedisClientType | null = null;
+
+export async function getRedisClient(): Promise<RedisClientType> {
+  if (client && client.isOpen) {
+    return client;
+  }
+
+  client = createClient({ url: REDIS_URL });
+
+  client.on('error', (err) => {
+    logger.error('Redis client error', err);
+  });
+
+  client.on('connect', () => {
+    logger.info('Redis connected');
+  });
+
+  await client.connect();
+  return client;
+}
+
+export async function closeRedisConnection(): Promise<void> {
+  if (client && client.isOpen) {
+    await client.quit();
+    client = null;
+  }
+}
+
+// Cache helpers with TTL
+export async function cacheGet<T>(key: string): Promise<T | null> {
+  const redis = await getRedisClient();
+  const value = await redis.get(key);
+  return value ? JSON.parse(value) : null;
+}
+
+export async function cacheSet<T>(key: string, value: T, ttlSeconds: number = 300): Promise<void> {
+  const redis = await getRedisClient();
+  await redis.setEx(key, ttlSeconds, JSON.stringify(value));
+}
+
+export async function cacheDelete(key: string): Promise<void> {
+  const redis = await getRedisClient();
+  await redis.del(key);
+}
+
+export async function cacheClear(pattern: string): Promise<void> {
+  const redis = await getRedisClient();
+  const keys = await redis.keys(pattern);
+  if (keys.length > 0) {
+    await redis.del(keys);
+  }
+}
+
+// Pub/Sub for real-time sync
+export async function publish(channel: string, message: unknown): Promise<void> {
+  await performRedisPublish(getRedisClient, channel, message);
+}
+
+export async function subscribe(channel: string, callback: (message: unknown) => void): Promise<void> {
+  const subscriber = (await getRedisClient()).duplicate();
+  await subscriber.connect();
+  await subscriber.subscribe(channel, (message) => {
+    callback(JSON.parse(message));
+  });
+}
+
+// Check Redis health
+export async function checkRedisHealth(): Promise<boolean> {
+  try {
+    const redis = await getRedisClient();
+    const pong = await redis.ping();
+    return pong === 'PONG';
+  } catch {
+    return false;
+  }
+}

package/core/responses.ts

@@ -0,0 +1,187 @@
+/**
+ * ResponseFormatter - Unified response formatting for all Squish output contexts
+ * @module core/responses
+ */
+
+export type ResponseStatus = 'ok' | 'error';
+
+export interface BaseResponse<T = unknown> {
+  status: ResponseStatus;
+  message?: string;
+  data?: T;
+  error?: string;
+  timestamp?: string;
+}
+
+export interface PaginatedResponse<T> extends BaseResponse<T[]> {
+  count: number;
+  total?: number;
+  page?: number;
+  limit?: number;
+}
+
+/**
+ * Format options for web responses
+ */
+export interface WebFormatOptions {
+  statusCode?: number;
+  pagination?: { total: number; page: number; limit: number };
+}
+
+/**
+ * Unified response formatter for all Squish output contexts
+ */
+export class ResponseFormatter {
+  /**
+   * Generate ISO timestamp
+   */
+  private static getTimestamp(): string {
+    return new Date().toISOString();
+  }
+
+  /**
+   * Build base response with timestamp
+   */
+  private static buildBase<T>(status: ResponseStatus, message?: string, data?: T, error?: string): BaseResponse<T> {
+    return {
+      status,
+      message,
+      data,
+      error,
+      timestamp: this.getTimestamp(),
+    };
+  }
+
+  // CLI Formatters
+
+  /**
+   * Format response for CLI output (pretty-printed JSON)
+   */
+  static cli<T>(data: T, message?: string): string {
+    const response = this.buildBase<T>(data instanceof Error ? 'error' : 'ok', message, data);
+    return JSON.stringify(response, null, 2);
+  }
+
+  /**
+   * Format error for CLI and exit process
+   */
+  static cliError(error: Error): never {
+    const response = this.buildBase<void>('error', error.message, undefined, error.message);
+    console.error(JSON.stringify(response, null, 2));
+    process.exit(1);
+  }
+
+  // Web API Formatters
+
+  /**
+   * Format successful response for Web API
+   */
+  static web<T>(
+    data: T,
+    message?: string,
+    options?: WebFormatOptions
+  ): { status: number; body: BaseResponse<T> } {
+    const body = this.buildBase<T>('ok', message, data);
+    
+    // Add pagination metadata if provided
+    if (options?.pagination) {
+      (body as any).count = options.pagination.total;
+      (body as any).total = options.pagination.total;
+      (body as any).page = options.pagination.page;
+      (body as any).limit = options.pagination.limit;
+    }
+    
+    return {
+      status: options?.statusCode ?? 200,
+      body,
+    };
+  }
+
+  /**
+   * Format error response for Web API
+   */
+  static webError(
+    error: Error,
+    options?: { statusCode?: number; log?: boolean }
+  ): { status: number; body: BaseResponse } {
+    const statusCode = options?.statusCode ?? 500;
+    const body = this.buildBase<void>('error', error.message, undefined, error.message);
+    
+    if (options?.log !== false) {
+      console.error(`[Web API Error ${statusCode}]:`, error.message);
+    }
+    
+    return { status: statusCode, body };
+  }
+
+  // MCP Formatters
+
+  /**
+   * Format response for MCP tools
+   */
+  static mcp<T>(
+    data: T,
+    message?: string
+  ): { content: Array<{ type: string; text: string }> } {
+    const response = this.buildBase<T>('ok', message, data);
+    return {
+      content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
+    };
+  }
+
+  /**
+   * Format error for MCP tools (throws McpError)
+   */
+  static mcpError(
+    error: Error,
+    context?: string
+  ): never {
+    const message = context ? `${context}: ${error.message}` : error.message;
+    const response = this.buildBase<void>('error', message, undefined, message);
+    
+    // Import McpError dynamically to avoid requiring @modelcontextprotocol/sdk in non-MCP contexts
+    try {
+      const { McpError, ErrorCode } = require('@modelcontextprotocol/sdk/types.js');
+      throw new McpError(ErrorCode.InternalError, JSON.stringify(response));
+    } catch (e) {
+      // If McpError is not available, throw a standard error with MCP-formatted message
+      const mcpError = new Error(JSON.stringify(response));
+      mcpError.name = 'McpError';
+      throw mcpError;
+    }
+  }
+
+  // Algorithm Handler Formatters
+
+  /**
+   * Format response for algorithm handlers
+   */
+  static algorithm<T>(
+    data: T,
+    message: string,
+    options?: { ok?: boolean; error?: string }
+  ): BaseResponse<T> {
+    const isOk = options?.ok !== false;
+    return this.buildBase<T>(
+      isOk ? 'ok' : 'error',
+      message,
+      isOk ? data : undefined,
+      options?.error
+    );
+  }
+
+  /**
+   * Convenience method for success responses
+   */
+  static success<T>(data: T, message?: string): BaseResponse<T> {
+    return this.buildBase<T>('ok', message, data);
+  }
+
+  /**
+   * Convenience method for failure responses
+   */
+  static failure(message: string, error?: Error | string): BaseResponse {
+    const errorMessage = error instanceof Error ? error.message : error;
+    return this.buildBase<void>('error', message, undefined, errorMessage);
+  }
+}