claude-memory-layer 1.0.31 → 1.0.33

package/src/core/markdown-mirror.ts

@@ -1,70 +0,0 @@
-import * as fs from 'fs/promises';
-import * as path from 'path';
-import type { MemoryEvent } from './types.js';
-
-const DEFAULT_NAMESPACE = 'default';
-const DEFAULT_CATEGORY = 'uncategorized';
-
-export function sanitizeSegment(input: unknown, fallback: string): string {
-  const raw = String(input ?? '').trim().toLowerCase();
-  const safe = raw
-    .normalize('NFKD')
-    .replace(/[^a-z0-9_-]+/g, '-')
-    .replace(/^-+|-+$/g, '');
-
-  if (!safe || safe === '.' || safe === '..') return fallback;
-  return safe;
-}
-
-function getCategorySegments(metadata: Record<string, unknown> | undefined, eventType: string): string[] {
-  const raw = metadata?.categoryPath;
-  if (Array.isArray(raw) && raw.length > 0) {
-    return raw.map((s) => sanitizeSegment(s, DEFAULT_CATEGORY));
-  }
-  const single = metadata?.category;
-  if (typeof single === 'string' && single.trim()) {
-    return [sanitizeSegment(single, DEFAULT_CATEGORY)];
-  }
-  return [sanitizeSegment(eventType, DEFAULT_CATEGORY)];
-}
-
-export function buildMirrorPath(rootDir: string, event: MemoryEvent): string {
-  const metadata = event.metadata as Record<string, unknown> | undefined;
-  const namespace = sanitizeSegment(metadata?.namespace, DEFAULT_NAMESPACE);
-  const categories = getCategorySegments(metadata, event.eventType);
-
-  const d = event.timestamp;
-  const yyyy = d.getFullYear();
-  const mm = String(d.getMonth() + 1).padStart(2, '0');
-  const dd = String(d.getDate()).padStart(2, '0');
-
-  return path.join(rootDir, 'memory', namespace, ...categories, `${yyyy}-${mm}-${dd}.md`);
-}
-
-export function formatMirrorEntry(event: MemoryEvent): string {
-  const category = Array.isArray((event.metadata as any)?.categoryPath)
-    ? ((event.metadata as any).categoryPath as unknown[]).join('/')
-    : String((event.metadata as any)?.category ?? event.eventType);
-
-  return [
-    '',
-    `- ts: ${event.timestamp.toISOString()}`,
-    `  id: ${event.id}`,
-    `  type: ${event.eventType}`,
-    `  session: ${event.sessionId}`,
-    `  category: ${category}`,
-    '  content: |',
-    ...event.content.split('\n').map((line) => `    ${line}`)
-  ].join('\n') + '\n';
-}
-
-export class MarkdownMirror {
-  constructor(private readonly rootDir: string) {}
-
-  async append(event: MemoryEvent): Promise<string> {
-    const outPath = buildMirrorPath(this.rootDir, event);
-    await fs.mkdir(path.dirname(outPath), { recursive: true });
-    await fs.appendFile(outPath, formatMirrorEntry(event), 'utf8');
-    return outPath;
-  }
-}

package/src/core/matcher.ts

@@ -1,208 +0,0 @@
-/**
- * AXIOMMIND Matcher - Weighted scoring with confidence classification
- * Implements matching thresholds: high (≥0.92), suggested (≥0.75), none (<0.75)
- */
-
-import type {
-  MemoryMatch,
-  MatchResult,
-  MatchConfidence
-} from './types.js';
-import { SearchResult } from './vector-store.js';
-
-export interface MatchWeights {
-  semanticSimilarity: number;
-  ftsScore: number;
-  recencyBonus: number;
-  statusWeight: number;
-}
-
-export interface MatcherConfig {
-  weights: MatchWeights;
-  minCombinedScore: number;
-  minGap: number;
-  suggestionThreshold: number;
-}
-
-const DEFAULT_CONFIG: MatcherConfig = {
-  weights: {
-    semanticSimilarity: 0.4,
-    ftsScore: 0.25,
-    recencyBonus: 0.2,
-    statusWeight: 0.15
-  },
-  minCombinedScore: 0.92,
-  minGap: 0.03,
-  suggestionThreshold: 0.75
-};
-
-export class Matcher {
-  private readonly config: MatcherConfig;
-
-  constructor(config: Partial<MatcherConfig> = {}) {
-    this.config = {
-      ...DEFAULT_CONFIG,
-      ...config,
-      weights: { ...DEFAULT_CONFIG.weights, ...config.weights }
-    };
-  }
-
-  /**
-   * Calculate combined score using AXIOMMIND weighted formula
-   */
-  calculateCombinedScore(
-    semanticScore: number,
-    ftsScore: number = 0,
-    recencyDays: number = 0,
-    isActive: boolean = true
-  ): number {
-    const { weights } = this.config;
-
-    // Recency bonus: decays over 30 days
-    const recencyBonus = Math.max(0, 1 - recencyDays / 30);
-
-    // Status weight: active events get full weight
-    const statusMultiplier = isActive ? 1.0 : 0.7;
-
-    const combinedScore =
-      weights.semanticSimilarity * semanticScore +
-      weights.ftsScore * ftsScore +
-      weights.recencyBonus * recencyBonus +
-      weights.statusWeight * statusMultiplier;
-
-    return Math.min(1.0, combinedScore);
-  }
-
-  /**
-   * Classify match confidence based on AXIOMMIND thresholds
-   */
-  classifyConfidence(
-    topScore: number,
-    secondScore: number | null
-  ): MatchConfidence {
-    const { minCombinedScore, minGap, suggestionThreshold } = this.config;
-
-    // Calculate gap (infinity if no second match)
-    const gap = secondScore !== null ? topScore - secondScore : Infinity;
-
-    // High confidence: score ≥ 0.92 AND gap ≥ 0.03
-    if (topScore >= minCombinedScore && gap >= minGap) {
-      return 'high';
-    }
-
-    // Suggested: score ≥ 0.75
-    if (topScore >= suggestionThreshold) {
-      return 'suggested';
-    }
-
-    // No match
-    return 'none';
-  }
-
-  /**
-   * Match search results to find best memory
-   */
-  matchSearchResults(
-    results: SearchResult[],
-    getEventAge: (eventId: string) => number
-  ): MatchResult {
-    if (results.length === 0) {
-      return {
-        match: null,
-        confidence: 'none'
-      };
-    }
-
-    // Calculate combined scores
-    const scoredResults = results.map(result => {
-      const ageDays = getEventAge(result.eventId);
-      const combinedScore = this.calculateCombinedScore(
-        result.score,
-        result.score, // Reuse the retrieval score as lexical/proxy score when no separate FTS score is provided.
-        ageDays,
-        true // Assume active
-      );
-
-      return {
-        result,
-        combinedScore
-      };
-    });
-
-    // Sort by combined score
-    scoredResults.sort((a, b) => b.combinedScore - a.combinedScore);
-
-    const topResult = scoredResults[0];
-    const secondScore = scoredResults.length > 1 ? scoredResults[1].combinedScore : null;
-
-    // Classify confidence
-    const confidence = this.classifyConfidence(topResult.combinedScore, secondScore);
-
-    // Build match result
-    const match: MemoryMatch = {
-      event: {
-        id: topResult.result.eventId,
-        eventType: topResult.result.eventType as 'user_prompt' | 'agent_response' | 'session_summary',
-        sessionId: topResult.result.sessionId,
-        timestamp: new Date(topResult.result.timestamp),
-        content: topResult.result.content,
-        canonicalKey: '', // Would need to be fetched
-        dedupeKey: ''     // Would need to be fetched
-      },
-      score: topResult.combinedScore
-    };
-
-    const gap = secondScore !== null ? topResult.combinedScore - secondScore : undefined;
-
-    // Build alternatives for suggested matches
-    const alternatives = confidence === 'suggested'
-      ? scoredResults.slice(1, 4).map(sr => ({
-          event: {
-            id: sr.result.eventId,
-            eventType: sr.result.eventType as 'user_prompt' | 'agent_response' | 'session_summary',
-            sessionId: sr.result.sessionId,
-            timestamp: new Date(sr.result.timestamp),
-            content: sr.result.content,
-            canonicalKey: '',
-            dedupeKey: ''
-          },
-          score: sr.combinedScore
-        }))
-      : undefined;
-
-    return {
-      match: confidence !== 'none' ? match : null,
-      confidence,
-      gap,
-      alternatives
-    };
-  }
-
-  /**
-   * Calculate days between two dates
-   */
-  static calculateAgeDays(timestamp: Date): number {
-    const now = new Date();
-    const diffMs = now.getTime() - timestamp.getTime();
-    return diffMs / (1000 * 60 * 60 * 24);
-  }
-
-  /**
-   * Get current configuration
-   */
-  getConfig(): Readonly<MatcherConfig> {
-    return { ...this.config };
-  }
-}
-
-/**
- * Default matcher instance
- */
-let defaultMatcher: Matcher | null = null;
-
-export function getDefaultMatcher(): Matcher {
-  if (!defaultMatcher) {
-    defaultMatcher = new Matcher();
-  }
-  return defaultMatcher;
-}

package/src/core/md-mirror.ts

@@ -1,92 +0,0 @@
-import * as fs from 'node:fs';
-import * as path from 'node:path';
-import type { MemoryEventInput } from './types.js';
-
-function sanitizeSegment(input: string | undefined, fallback: string): string {
-  const v = (input || '').trim().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
-  return v || fallback;
-}
-
-function getAtPath(obj: Record<string, unknown> | undefined, dotted: string): unknown {
-  if (!obj) return undefined;
-  return dotted.split('.').reduce<unknown>((acc, key) => {
-    if (!acc || typeof acc !== 'object') return undefined;
-    return (acc as Record<string, unknown>)[key];
-  }, obj);
-}
-
-export function buildMirrorPath(rootDir: string, event: MemoryEventInput): string {
-  const meta = event.metadata as Record<string, unknown> | undefined;
-
-  const namespaceRaw = getAtPath(meta, 'namespace') ?? getAtPath(meta, 'scope.namespace') ?? event.eventType;
-  const namespace = sanitizeSegment(typeof namespaceRaw === 'string' ? namespaceRaw : undefined, 'general');
-
-  const categoryRaw = getAtPath(meta, 'categoryPath') ?? getAtPath(meta, 'scope.categoryPath');
-  const categoryPath = Array.isArray(categoryRaw) && categoryRaw.length > 0
-    ? categoryRaw.map((x) => sanitizeSegment(typeof x === 'string' ? x : undefined, 'uncategorized'))
-    : ['uncategorized'];
-
-  const d = event.timestamp;
-  const yyyy = d.getFullYear();
-  const mm = String(d.getMonth() + 1).padStart(2, '0');
-  const dd = String(d.getDate()).padStart(2, '0');
-
-  return path.join(rootDir, 'memory', namespace, ...categoryPath, `${yyyy}-${mm}-${dd}.md`);
-}
-
-export class MarkdownMirror {
-  constructor(private readonly rootDir: string) {}
-
-  async append(event: MemoryEventInput, eventId?: string): Promise<void> {
-    const out = buildMirrorPath(this.rootDir, event);
-    fs.mkdirSync(path.dirname(out), { recursive: true });
-
-    const lines = [
-      '',
-      `## ${event.timestamp.toISOString()} | ${eventId ?? 'pending-id'}`,
-      `- type: ${event.eventType}`,
-      `- session: ${event.sessionId}`,
-      event.content,
-    ];
-
-    await fs.promises.appendFile(out, lines.join('\n'), 'utf8');
-    await this.refreshIndex();
-  }
-
-  private async refreshIndex(): Promise<void> {
-    const memoryRoot = path.join(this.rootDir, 'memory');
-    await fs.promises.mkdir(memoryRoot, { recursive: true });
-
-    const files: string[] = [];
-    await this.walk(memoryRoot, files);
-
-    const mdFiles = files
-      .filter((f) => f.endsWith('.md'))
-      .map((f) => path.relative(this.rootDir, f))
-      .filter((rel) => rel !== path.join('memory', '_index.md'))
-      .sort();
-
-    const index = [
-      '# Memory Index',
-      '',
-      'Generated automatically by MarkdownMirror.',
-      '',
-      ...mdFiles.map((rel) => `- ${rel}`),
-      '',
-    ].join('\n');
-
-    await fs.promises.writeFile(path.join(memoryRoot, '_index.md'), index, 'utf8');
-  }
-
-  private async walk(dir: string, out: string[]): Promise<void> {
-    const entries = await fs.promises.readdir(dir, { withFileTypes: true });
-    for (const e of entries) {
-      const full = path.join(dir, e.name);
-      if (e.isDirectory()) {
-        await this.walk(full, out);
-      } else {
-        out.push(full);
-      }
-    }
-  }
-}

package/src/core/metadata-extractor.ts

@@ -1,203 +0,0 @@
-/**
- * Metadata Extractor
- * Extracts tool-specific metadata from tool inputs and outputs
- */
-
-import type { ToolMetadata } from './types.js';
-
-/**
- * Get file type from path
- */
-function getFileType(filePath: string): string | undefined {
-  const ext = filePath.split('.').pop()?.toLowerCase();
-  if (!ext) return undefined;
-
-  const typeMap: Record<string, string> = {
-    ts: 'typescript',
-    tsx: 'typescript',
-    js: 'javascript',
-    jsx: 'javascript',
-    py: 'python',
-    rb: 'ruby',
-    go: 'go',
-    rs: 'rust',
-    java: 'java',
-    kt: 'kotlin',
-    swift: 'swift',
-    c: 'c',
-    cpp: 'cpp',
-    h: 'header',
-    hpp: 'header',
-    cs: 'csharp',
-    php: 'php',
-    html: 'html',
-    css: 'css',
-    scss: 'scss',
-    json: 'json',
-    yaml: 'yaml',
-    yml: 'yaml',
-    xml: 'xml',
-    md: 'markdown',
-    sql: 'sql',
-    sh: 'shell',
-    bash: 'shell',
-    zsh: 'shell'
-  };
-
-  return typeMap[ext];
-}
-
-/**
- * Count lines in content
- */
-function countLines(content: string): number {
-  return content.split('\n').length;
-}
-
-/**
- * Extract bash command (without arguments that might contain secrets)
- */
-function extractCommand(fullCommand: string): string {
-  // Get first word (command name)
-  const parts = fullCommand.trim().split(/\s+/);
-  const command = parts[0];
-
-  // For common commands, include safe arguments
-  const safeCommands = ['git', 'npm', 'yarn', 'pnpm', 'node', 'python', 'go', 'cargo', 'make'];
-  if (safeCommands.includes(command) && parts.length > 1) {
-    // Include subcommand for these
-    return `${command} ${parts[1]}`;
-  }
-
-  return command;
-}
-
-/**
- * Extract metadata from tool usage
- */
-export function extractMetadata(
-  toolName: string,
-  input: Record<string, unknown>,
-  output: string,
-  success: boolean
-): ToolMetadata {
-  switch (toolName) {
-    case 'Read': {
-      const filePath = input.file_path as string | undefined;
-      return {
-        filePath,
-        fileType: filePath ? getFileType(filePath) : undefined,
-        lineCount: success ? countLines(output) : undefined
-      };
-    }
-
-    case 'Write': {
-      const filePath = input.file_path as string | undefined;
-      const content = input.content as string | undefined;
-      return {
-        filePath,
-        fileType: filePath ? getFileType(filePath) : undefined,
-        lineCount: content ? countLines(content) : undefined
-      };
-    }
-
-    case 'Edit': {
-      const filePath = input.file_path as string | undefined;
-      return {
-        filePath,
-        fileType: filePath ? getFileType(filePath) : undefined
-      };
-    }
-
-    case 'Bash': {
-      const fullCommand = input.command as string | undefined;
-      return {
-        command: fullCommand ? extractCommand(fullCommand) : undefined
-      };
-    }
-
-    case 'Grep': {
-      const pattern = input.pattern as string | undefined;
-      // Count matches from output
-      const matchCount = success
-        ? (output.match(/\n/g) || []).length + (output.trim() ? 1 : 0)
-        : undefined;
-      return {
-        pattern,
-        matchCount
-      };
-    }
-
-    case 'Glob': {
-      const pattern = input.pattern as string | undefined;
-      const matchCount = success
-        ? (output.match(/\n/g) || []).length + (output.trim() ? 1 : 0)
-        : undefined;
-      return {
-        pattern,
-        matchCount
-      };
-    }
-
-    case 'WebFetch': {
-      const url = input.url as string | undefined;
-      // Try to extract status code from output
-      const statusMatch = output.match(/status:\s*(\d{3})/i);
-      return {
-        url,
-        statusCode: statusMatch ? parseInt(statusMatch[1], 10) : undefined
-      };
-    }
-
-    case 'WebSearch': {
-      return {};
-    }
-
-    case 'NotebookEdit': {
-      const notebookPath = input.notebook_path as string | undefined;
-      return {
-        filePath: notebookPath,
-        fileType: 'jupyter'
-      };
-    }
-
-    default:
-      return {};
-  }
-}
-
-/**
- * Create embedding content for tool observation
- */
-export function createToolObservationEmbedding(
-  toolName: string,
-  metadata: ToolMetadata,
-  success: boolean
-): string {
-  const parts: string[] = [];
-
-  parts.push(`Tool: ${toolName}`);
-
-  if (metadata.filePath) {
-    parts.push(`File: ${metadata.filePath}`);
-  }
-  if (metadata.command) {
-    parts.push(`Command: ${metadata.command}`);
-  }
-  if (metadata.pattern) {
-    parts.push(`Pattern: ${metadata.pattern}`);
-  }
-  if (metadata.url) {
-    // Only include domain for privacy
-    try {
-      const url = new URL(metadata.url);
-      parts.push(`URL: ${url.hostname}`);
-    } catch {
-      // Invalid URL, skip
-    }
-  }
-
-  parts.push(`Result: ${success ? 'Success' : 'Failed'}`);
-
-  return parts.join('\n');
-}

package/src/core/model/memory-fact.ts

@@ -1,30 +0,0 @@
-import { z } from 'zod';
-
-export const MemoryFactTypeSchema = z.enum([
-  'decision',
-  'constraint',
-  'task_state',
-  'tool_observation',
-  'preference',
-  'code_context',
-  'summary_fact'
-]);
-export type MemoryFactType = z.infer<typeof MemoryFactTypeSchema>;
-
-export const MemoryFactSchema = z.object({
-  factId: z.string(),
-  projectHash: z.string(),
-  factType: MemoryFactTypeSchema,
-  text: z.string(),
-  derivedFromEventIds: z.array(z.string()).default([]),
-  sourceKind: z.enum(['prompt', 'assistant', 'tool', 'import']),
-  confidence: z.number().min(0).max(1),
-  importance: z.number().min(0).max(1).default(0.5),
-  tags: z.array(z.string()).default([]),
-  entityRefs: z.array(z.string()).optional(),
-  fileRefs: z.array(z.string()).optional(),
-  symbolRefs: z.array(z.string()).optional(),
-  createdAt: z.string(),
-  updatedAt: z.string()
-});
-export type MemoryFact = z.infer<typeof MemoryFactSchema>;

package/src/core/model/memory-rule.ts

@@ -1,14 +0,0 @@
-import { z } from 'zod';
-
-export const MemoryRuleSchema = z.object({
-  ruleId: z.string(),
-  projectHash: z.string().optional(),
-  scope: z.enum(['project', 'shared']),
-  ruleType: z.enum(['preference', 'workflow', 'convention', 'constraint']),
-  text: z.string(),
-  confidence: z.number().min(0).max(1),
-  evidenceIds: z.array(z.string()).default([]),
-  createdAt: z.string(),
-  updatedAt: z.string()
-});
-export type MemoryRule = z.infer<typeof MemoryRuleSchema>;

package/src/core/model/memory-summary.ts

@@ -1,21 +0,0 @@
-import { z } from 'zod';
-
-export const MemorySummaryTypeSchema = z.enum([
-  'turn',
-  'session',
-  'project',
-  'continuity',
-  'timeline_digest'
-]);
-export type MemorySummaryType = z.infer<typeof MemorySummaryTypeSchema>;
-
-export const MemorySummarySchema = z.object({
-  summaryId: z.string(),
-  summaryType: MemorySummaryTypeSchema,
-  refId: z.string(),
-  text: z.string(),
-  sourceEventIds: z.array(z.string()).default([]),
-  sourceFactIds: z.array(z.string()).default([]),
-  createdAt: z.string()
-});
-export type MemorySummary = z.infer<typeof MemorySummarySchema>;

package/src/core/model/raw-event.ts

@@ -1,28 +0,0 @@
-import { z } from 'zod';
-
-export const RawEventTypeSchema = z.enum([
-  'user_prompt',
-  'assistant_response',
-  'tool_output',
-  'session_marker',
-  'imported_turn'
-]);
-export type RawEventType = z.infer<typeof RawEventTypeSchema>;
-
-export const PrivacyLevelSchema = z.enum(['public', 'internal', 'private', 'masked']);
-export type PrivacyLevel = z.infer<typeof PrivacyLevelSchema>;
-
-export const RawEventSchema = z.object({
-  eventId: z.string(),
-  projectHash: z.string(),
-  sessionId: z.string(),
-  turnId: z.string().optional(),
-  eventType: RawEventTypeSchema,
-  content: z.string(),
-  toolName: z.string().optional(),
-  sourceRef: z.string().optional(),
-  metadata: z.record(z.unknown()).default({}),
-  privacyLevel: PrivacyLevelSchema.default('internal'),
-  createdAt: z.string()
-});
-export type RawEvent = z.infer<typeof RawEventSchema>;

package/src/core/model/retrieval-result.ts

@@ -1,35 +0,0 @@
-import { z } from 'zod';
-
-export const RetrievalReasonSchema = z.enum([
-  'semantic_match',
-  'keyword_match',
-  'recent_relevance',
-  'continuity_link',
-  'entity_overlap',
-  'tool_followup',
-  'summary_fallback'
-]);
-export type RetrievalReason = z.infer<typeof RetrievalReasonSchema>;
-
-export const RetrievalResultTypeSchema = z.enum([
-  'fact',
-  'summary',
-  'tool_evidence',
-  'rule',
-  'source'
-]);
-export type RetrievalResultType = z.infer<typeof RetrievalResultTypeSchema>;
-
-export const RetrievalResultEnvelopeSchema = z.object({
-  id: z.string(),
-  resultType: RetrievalResultTypeSchema,
-  title: z.string().optional(),
-  snippet: z.string(),
-  score: z.number().min(0).max(1),
-  reasons: z.array(RetrievalReasonSchema).default([]),
-  sourceRef: z.string().optional(),
-  sessionId: z.string().optional(),
-  turnId: z.string().optional(),
-  metadata: z.record(z.unknown()).optional()
-});
-export type RetrievalResultEnvelope = z.infer<typeof RetrievalResultEnvelopeSchema>;