claude-memory-layer 1.0.0

package/src/core/canonical-key.ts

@@ -0,0 +1,186 @@
+/**
+ * AXIOMMIND canonical_key.py port
+ * Deterministic normalization ensuring identical titles always map to same keys
+ */
+
+import { createHash } from 'crypto';
+
+const MAX_KEY_LENGTH = 200;
+
+/**
+ * Convert text to a normalized canonical key
+ *
+ * Normalization steps:
+ * 1. NFKC unicode normalization
+ * 2. Lowercase conversion
+ * 3. Punctuation removal
+ * 4. Consecutive whitespace cleanup
+ * 5. Context addition (optional)
+ * 6. Long key truncation with MD5
+ */
+export function makeCanonicalKey(
+  title: string,
+  context?: { project?: string; sessionId?: string }
+): string {
+  // Step 1: NFKC normalization
+  let normalized = title.normalize('NFKC');
+
+  // Step 2: Lowercase conversion
+  normalized = normalized.toLowerCase();
+
+  // Step 3: Punctuation removal (unicode compatible)
+  normalized = normalized.replace(/[^\p{L}\p{N}\s]/gu, '');
+
+  // Step 4: Consecutive whitespace cleanup
+  normalized = normalized.replace(/\s+/g, ' ').trim();
+
+  // Step 5: Context addition
+  let key = normalized;
+  if (context?.project) {
+    key = `${context.project}::${key}`;
+  }
+
+  // Step 6: Long key handling
+  if (key.length > MAX_KEY_LENGTH) {
+    const hashSuffix = createHash('md5').update(key).digest('hex').slice(0, 8);
+    key = key.slice(0, MAX_KEY_LENGTH - 9) + '_' + hashSuffix;
+  }
+
+  return key;
+}
+
+/**
+ * Check if two texts have the same canonical key
+ */
+export function isSameCanonicalKey(a: string, b: string): boolean {
+  return makeCanonicalKey(a) === makeCanonicalKey(b);
+}
+
+/**
+ * Generate dedupe key (content + session for uniqueness)
+ * AXIOMMIND Principle 3: Idempotency guarantee
+ */
+export function makeDedupeKey(content: string, sessionId: string): string {
+  const contentHash = createHash('sha256').update(content).digest('hex');
+  return `${sessionId}:${contentHash}`;
+}
+
+/**
+ * Generate content hash for deduplication
+ */
+export function hashContent(content: string): string {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+// ============================================================
+// Entity Canonical Keys (Task Entity System)
+// ============================================================
+
+export type EntityKeyType = 'task' | 'condition' | 'artifact';
+
+/**
+ * Normalize text for entity key generation
+ */
+function normalizeForKey(text: string): string {
+  return text
+    .normalize('NFKC')
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}\s]/gu, '')
+    .replace(/\s+/g, '_')
+    .trim();
+}
+
+/**
+ * Generate canonical key for entities
+ * Format: {type}:{project}:{normalized_identifier}
+ */
+export function makeEntityCanonicalKey(
+  entityType: EntityKeyType,
+  identifier: string,
+  context?: { project?: string }
+): string {
+  const project = context?.project ?? 'default';
+
+  switch (entityType) {
+    case 'task':
+      return `task:${project}:${normalizeForKey(identifier)}`;
+    case 'condition':
+      return `cond:${project}:${normalizeForKey(identifier)}`;
+    case 'artifact':
+      return makeArtifactKey(identifier);
+  }
+}
+
+/**
+ * Generate canonical key for artifacts based on identifier pattern
+ * - URL: art:url:{sha1(url)}
+ * - JIRA key: art:jira:{key}
+ * - GitHub issue: art:gh_issue:{repo}:{num}
+ * - Generic: art:generic:{sha1(identifier)}
+ */
+export function makeArtifactKey(identifier: string): string {
+  // URL pattern
+  if (/^https?:\/\//.test(identifier)) {
+    const hash = createHash('sha1').update(identifier).digest('hex').slice(0, 12);
+    return `art:url:${hash}`;
+  }
+
+  // JIRA key pattern (e.g., PROJ-123)
+  const jiraMatch = identifier.match(/^([A-Z]+-\d+)$/);
+  if (jiraMatch) {
+    return `art:jira:${jiraMatch[1].toLowerCase()}`;
+  }
+
+  // GitHub issue pattern (e.g., owner/repo#123)
+  const ghMatch = identifier.match(/^([^\/]+\/[^#]+)#(\d+)$/);
+  if (ghMatch) {
+    return `art:gh_issue:${ghMatch[1]}:${ghMatch[2]}`;
+  }
+
+  // Generic identifier
+  const hash = createHash('sha1').update(identifier).digest('hex').slice(0, 12);
+  return `art:generic:${hash}`;
+}
+
+/**
+ * Generate dedupe key for task events
+ */
+export function makeTaskEventDedupeKey(
+  eventType: string,
+  taskId: string,
+  sessionId: string,
+  additionalContext?: string
+): string {
+  const parts = [eventType, taskId, sessionId];
+  if (additionalContext) {
+    parts.push(additionalContext);
+  }
+  const combined = parts.join(':');
+  return createHash('sha256').update(combined).digest('hex');
+}
+
+/**
+ * Parse entity canonical key to extract type and identifier
+ */
+export function parseEntityCanonicalKey(canonicalKey: string): {
+  entityType: EntityKeyType;
+  project?: string;
+  identifier: string;
+} | null {
+  const taskMatch = canonicalKey.match(/^task:([^:]+):(.+)$/);
+  if (taskMatch) {
+    return { entityType: 'task', project: taskMatch[1], identifier: taskMatch[2] };
+  }
+
+  const condMatch = canonicalKey.match(/^cond:([^:]+):(.+)$/);
+  if (condMatch) {
+    return { entityType: 'condition', project: condMatch[1], identifier: condMatch[2] };
+  }
+
+  const artMatch = canonicalKey.match(/^art:([^:]+):(.+)$/);
+  if (artMatch) {
+    return { entityType: 'artifact', identifier: artMatch[2] };
+  }
+
+  return null;
+}

package/src/core/citation-generator.ts

@@ -0,0 +1,63 @@
+/**
+ * Citation Generator
+ * Generates unique, short citation IDs for memory references
+ */
+
+import { createHash } from 'crypto';
+
+const ID_LENGTH = 6;
+const CHARSET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+
+/**
+ * Generate a citation ID from an event ID using SHA256
+ */
+export function generateCitationId(eventId: string): string {
+  const hash = createHash('sha256')
+    .update(eventId)
+    .digest();
+
+  let id = '';
+  for (let i = 0; i < ID_LENGTH; i++) {
+    id += CHARSET[hash[i] % CHARSET.length];
+  }
+
+  return id;
+}
+
+/**
+ * Generate a unique citation ID with collision handling
+ */
+export async function generateUniqueCitationId(
+  eventId: string,
+  existsCheck: (id: string) => Promise<boolean>
+): Promise<string> {
+  let id = generateCitationId(eventId);
+  let attempt = 0;
+
+  while (await existsCheck(id) && attempt < 10) {
+    // Add salt and regenerate
+    id = generateCitationId(`${eventId}:${attempt}`);
+    attempt++;
+  }
+
+  if (attempt >= 10) {
+    throw new Error('Failed to generate unique citation ID after 10 attempts');
+  }
+
+  return id;
+}
+
+/**
+ * Format a citation ID for display
+ */
+export function formatCitationId(citationId: string): string {
+  return `[mem:${citationId}]`;
+}
+
+/**
+ * Parse a citation ID from formatted string
+ */
+export function parseCitationId(formatted: string): string | null {
+  const match = formatted.match(/\[?mem:([A-Za-z0-9]{6})\]?/);
+  return match ? match[1] : null;
+}

package/src/core/consolidated-store.ts

@@ -0,0 +1,279 @@
+/**
+ * Consolidated Store
+ * Manages long-term integrated memories for Endless Mode
+ * Biomimetic: Simulates memory consolidation that occurs during sleep
+ */
+
+import { randomUUID } from 'crypto';
+import { Database } from 'duckdb';
+import type {
+  ConsolidatedMemory,
+  ConsolidatedMemoryInput
+} from './types.js';
+import { EventStore } from './event-store.js';
+
+export class ConsolidatedStore {
+  constructor(private eventStore: EventStore) {}
+
+  private get db(): Database {
+    return this.eventStore.getDatabase();
+  }
+
+  /**
+   * Create a new consolidated memory
+   */
+  async create(input: ConsolidatedMemoryInput): Promise<string> {
+    const memoryId = randomUUID();
+
+    await this.db.run(
+      `INSERT INTO consolidated_memories
+        (memory_id, summary, topics, source_events, confidence, created_at)
+       VALUES (?, ?, ?, ?, ?, CURRENT_TIMESTAMP)`,
+      [
+        memoryId,
+        input.summary,
+        JSON.stringify(input.topics),
+        JSON.stringify(input.sourceEvents),
+        input.confidence
+      ]
+    );
+
+    return memoryId;
+  }
+
+  /**
+   * Get a consolidated memory by ID
+   */
+  async get(memoryId: string): Promise<ConsolidatedMemory | null> {
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT * FROM consolidated_memories WHERE memory_id = ?`,
+      [memoryId]
+    );
+
+    if (rows.length === 0) return null;
+    return this.rowToMemory(rows[0]);
+  }
+
+  /**
+   * Search consolidated memories by query (simple text search)
+   */
+  async search(query: string, options?: { topK?: number }): Promise<ConsolidatedMemory[]> {
+    const topK = options?.topK || 5;
+
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT * FROM consolidated_memories
+       WHERE summary LIKE ?
+       ORDER BY confidence DESC
+       LIMIT ?`,
+      [`%${query}%`, topK]
+    );
+
+    return rows.map(this.rowToMemory);
+  }
+
+  /**
+   * Search by topics
+   */
+  async searchByTopics(topics: string[], options?: { topK?: number }): Promise<ConsolidatedMemory[]> {
+    const topK = options?.topK || 5;
+
+    // Build topic filter
+    const topicConditions = topics.map(() => `topics LIKE ?`).join(' OR ');
+    const topicParams = topics.map(t => `%"${t}"%`);
+
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT * FROM consolidated_memories
+       WHERE ${topicConditions}
+       ORDER BY confidence DESC
+       LIMIT ?`,
+      [...topicParams, topK]
+    );
+
+    return rows.map(this.rowToMemory);
+  }
+
+  /**
+   * Get all consolidated memories ordered by confidence
+   */
+  async getAll(options?: { limit?: number }): Promise<ConsolidatedMemory[]> {
+    const limit = options?.limit || 100;
+
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT * FROM consolidated_memories
+       ORDER BY confidence DESC, created_at DESC
+       LIMIT ?`,
+      [limit]
+    );
+
+    return rows.map(this.rowToMemory);
+  }
+
+  /**
+   * Get recently created memories
+   */
+  async getRecent(options?: { limit?: number; hours?: number }): Promise<ConsolidatedMemory[]> {
+    const limit = options?.limit || 10;
+    const hours = options?.hours || 24;
+
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT * FROM consolidated_memories
+       WHERE created_at > datetime('now', '-${hours} hours')
+       ORDER BY created_at DESC
+       LIMIT ?`,
+      [limit]
+    );
+
+    return rows.map(this.rowToMemory);
+  }
+
+  /**
+   * Mark a memory as accessed (tracks usage for importance scoring)
+   */
+  async markAccessed(memoryId: string): Promise<void> {
+    await this.db.run(
+      `UPDATE consolidated_memories
+       SET accessed_at = CURRENT_TIMESTAMP,
+           access_count = access_count + 1
+       WHERE memory_id = ?`,
+      [memoryId]
+    );
+  }
+
+  /**
+   * Update confidence score for a memory
+   */
+  async updateConfidence(memoryId: string, confidence: number): Promise<void> {
+    await this.db.run(
+      `UPDATE consolidated_memories
+       SET confidence = ?
+       WHERE memory_id = ?`,
+      [confidence, memoryId]
+    );
+  }
+
+  /**
+   * Delete a consolidated memory
+   */
+  async delete(memoryId: string): Promise<void> {
+    await this.db.run(
+      `DELETE FROM consolidated_memories WHERE memory_id = ?`,
+      [memoryId]
+    );
+  }
+
+  /**
+   * Get count of consolidated memories
+   */
+  async count(): Promise<number> {
+    const result = await this.db.all<Array<{ count: number }>>(
+      `SELECT COUNT(*) as count FROM consolidated_memories`
+    );
+    return result[0]?.count || 0;
+  }
+
+  /**
+   * Get most accessed memories (for importance scoring)
+   */
+  async getMostAccessed(limit: number = 10): Promise<ConsolidatedMemory[]> {
+    const rows = await this.db.all<Array<Record<string, unknown>>>(
+      `SELECT * FROM consolidated_memories
+       WHERE access_count > 0
+       ORDER BY access_count DESC
+       LIMIT ?`,
+      [limit]
+    );
+
+    return rows.map(this.rowToMemory);
+  }
+
+  /**
+   * Get statistics about consolidated memories
+   */
+  async getStats(): Promise<{
+    total: number;
+    averageConfidence: number;
+    topicCounts: Record<string, number>;
+    recentCount: number;
+  }> {
+    const total = await this.count();
+
+    const avgResult = await this.db.all<Array<{ avg: number | null }>>(
+      `SELECT AVG(confidence) as avg FROM consolidated_memories`
+    );
+    const averageConfidence = avgResult[0]?.avg || 0;
+
+    const recentResult = await this.db.all<Array<{ count: number }>>(
+      `SELECT COUNT(*) as count FROM consolidated_memories
+       WHERE created_at > datetime('now', '-24 hours')`
+    );
+    const recentCount = recentResult[0]?.count || 0;
+
+    // Get topic counts
+    const allMemories = await this.getAll({ limit: 1000 });
+    const topicCounts: Record<string, number> = {};
+    for (const memory of allMemories) {
+      for (const topic of memory.topics) {
+        topicCounts[topic] = (topicCounts[topic] || 0) + 1;
+      }
+    }
+
+    return {
+      total,
+      averageConfidence,
+      topicCounts,
+      recentCount
+    };
+  }
+
+  /**
+   * Check if source events are already consolidated
+   */
+  async isAlreadyConsolidated(eventIds: string[]): Promise<boolean> {
+    for (const eventId of eventIds) {
+      const result = await this.db.all<Array<{ count: number }>>(
+        `SELECT COUNT(*) as count FROM consolidated_memories
+         WHERE source_events LIKE ?`,
+        [`%"${eventId}"%`]
+      );
+      if ((result[0]?.count || 0) > 0) return true;
+    }
+    return false;
+  }
+
+  /**
+   * Get the last consolidation time
+   */
+  async getLastConsolidationTime(): Promise<Date | null> {
+    const result = await this.db.all<Array<{ created_at: string }>>(
+      `SELECT created_at FROM consolidated_memories
+       ORDER BY created_at DESC
+       LIMIT 1`
+    );
+
+    if (result.length === 0) return null;
+    return new Date(result[0].created_at);
+  }
+
+  /**
+   * Convert database row to ConsolidatedMemory
+   */
+  private rowToMemory(row: Record<string, unknown>): ConsolidatedMemory {
+    return {
+      memoryId: row.memory_id as string,
+      summary: row.summary as string,
+      topics: JSON.parse(row.topics as string || '[]'),
+      sourceEvents: JSON.parse(row.source_events as string || '[]'),
+      confidence: row.confidence as number,
+      createdAt: new Date(row.created_at as string),
+      accessedAt: row.accessed_at ? new Date(row.accessed_at as string) : undefined,
+      accessCount: row.access_count as number || 0
+    };
+  }
+}
+
+/**
+ * Create a Consolidated Store instance
+ */
+export function createConsolidatedStore(eventStore: EventStore): ConsolidatedStore {
+  return new ConsolidatedStore(eventStore);
+}