claude-memory-layer 1.0.11 → 1.0.12

package/src/core/ingest-interceptor.ts

@@ -0,0 +1,80 @@
+import type { MemoryEventInput } from './types.js';
+
+export type IngestStage = 'before' | 'after' | 'error';
+
+export interface IngestContext {
+  stage: IngestStage;
+  operation: 'user_prompt' | 'agent_response' | 'session_summary' | 'tool_observation';
+  sessionId: string;
+  event: MemoryEventInput;
+  error?: Error;
+}
+
+export type IngestInterceptor = (context: IngestContext) => Promise<void> | void;
+
+export class IngestInterceptorRegistry {
+  private before: IngestInterceptor[] = [];
+  private after: IngestInterceptor[] = [];
+  private onError: IngestInterceptor[] = [];
+
+  registerBefore(interceptor: IngestInterceptor): () => void {
+    this.before.push(interceptor);
+    return () => {
+      this.before = this.before.filter((i) => i !== interceptor);
+    };
+  }
+
+  registerAfter(interceptor: IngestInterceptor): () => void {
+    this.after.push(interceptor);
+    return () => {
+      this.after = this.after.filter((i) => i !== interceptor);
+    };
+  }
+
+  registerOnError(interceptor: IngestInterceptor): () => void {
+    this.onError.push(interceptor);
+    return () => {
+      this.onError = this.onError.filter((i) => i !== interceptor);
+    };
+  }
+
+  async run(stage: IngestStage, context: Omit<IngestContext, 'stage'>): Promise<void> {
+    const interceptors = stage === 'before'
+      ? this.before
+      : stage === 'after'
+      ? this.after
+      : this.onError;
+
+    for (const interceptor of interceptors) {
+      await interceptor({ ...context, stage });
+    }
+  }
+}
+
+export function mergeHierarchicalMetadata(
+  base: Record<string, unknown> | undefined,
+  patch: Record<string, unknown> | undefined
+): Record<string, unknown> | undefined {
+  if (!base && !patch) return undefined;
+  if (!base) return patch;
+  if (!patch) return base;
+
+  const result: Record<string, unknown> = { ...base };
+
+  for (const [key, value] of Object.entries(patch)) {
+    const current = result[key];
+    if (
+      typeof current === 'object' && current !== null && !Array.isArray(current) &&
+      typeof value === 'object' && value !== null && !Array.isArray(value)
+    ) {
+      result[key] = mergeHierarchicalMetadata(
+        current as Record<string, unknown>,
+        value as Record<string, unknown>
+      );
+    } else {
+      result[key] = value;
+    }
+  }
+
+  return result;
+}

package/src/core/markdown-mirror.ts

@@ -0,0 +1,70 @@
+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/md-mirror.ts

@@ -0,0 +1,92 @@
+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/mongo-sync-config.ts

@@ -0,0 +1,165 @@
+/**
+ * Mongo Sync Config
+ * Persistent per-project config for enabling auto-sync from hooks (e.g., SessionEnd).
+ *
+ * Stored as JSON under the project's storagePath next to events.sqlite.
+ * Note: This may include credentials in plaintext (MongoDB URI). Treat accordingly.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+
+import type { MongoSyncDirection } from './mongo-sync-worker.js';
+
+export type MongoSyncConfig = {
+  version: 1;
+  enabled: boolean;
+  /** MongoDB connection URI (may include credentials). */
+  uri: string;
+  /** MongoDB database name. */
+  dbName: string;
+  /** Remote project key (shared across machines). */
+  projectKey: string;
+  /** push|pull|both */
+  direction: MongoSyncDirection;
+  /** Batch size for push/pull loops. */
+  batchSize: number;
+  /** If true, hooks will run a sync at SessionEnd. */
+  autoSyncOnSessionEnd: boolean;
+  createdAt: string;
+  updatedAt: string;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null;
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  const s = value.trim();
+  return s.length > 0 ? s : null;
+}
+
+function asPositiveInt(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    const n = Math.trunc(value);
+    return n > 0 ? n : null;
+  }
+  if (typeof value === 'string') {
+    const n = parseInt(value, 10);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  }
+  return null;
+}
+
+function normalizeDirection(value: unknown): MongoSyncDirection | null {
+  if (typeof value !== 'string') return null;
+  const v = value.toLowerCase();
+  if (v === 'push' || v === 'pull' || v === 'both') return v;
+  return null;
+}
+
+export function getMongoSyncConfigPath(storagePath: string): string {
+  return path.join(storagePath, 'mongo-sync.json');
+}
+
+export function readMongoSyncConfig(storagePath: string): MongoSyncConfig | null {
+  const configPath = getMongoSyncConfigPath(storagePath);
+  if (!fs.existsSync(configPath)) return null;
+
+  try {
+    const raw = JSON.parse(fs.readFileSync(configPath, 'utf8')) as unknown;
+    if (!isRecord(raw)) return null;
+
+    const version = raw.version;
+    if (version !== 1) return null;
+
+    const enabled = raw.enabled;
+    if (typeof enabled !== 'boolean') return null;
+
+    const uri = asNonEmptyString(raw.uri);
+    const dbName = asNonEmptyString(raw.dbName);
+    const projectKey = asNonEmptyString(raw.projectKey);
+    const direction = normalizeDirection(raw.direction);
+    const batchSize = asPositiveInt(raw.batchSize) ?? 500;
+    const autoSyncOnSessionEnd = typeof raw.autoSyncOnSessionEnd === 'boolean' ? raw.autoSyncOnSessionEnd : true;
+    const createdAt = asNonEmptyString(raw.createdAt) ?? new Date(0).toISOString();
+    const updatedAt = asNonEmptyString(raw.updatedAt) ?? new Date(0).toISOString();
+
+    if (!uri || !dbName || !projectKey || !direction) return null;
+
+    return {
+      version: 1,
+      enabled,
+      uri,
+      dbName,
+      projectKey,
+      direction,
+      batchSize,
+      autoSyncOnSessionEnd,
+      createdAt,
+      updatedAt
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function writeMongoSyncConfig(storagePath: string, config: Omit<MongoSyncConfig, 'version' | 'createdAt' | 'updatedAt'> & {
+  createdAt?: string;
+  updatedAt?: string;
+}): MongoSyncConfig {
+  if (!fs.existsSync(storagePath)) {
+    fs.mkdirSync(storagePath, { recursive: true });
+  }
+
+  const now = new Date().toISOString();
+  const existing = readMongoSyncConfig(storagePath);
+
+  const normalized: MongoSyncConfig = {
+    version: 1,
+    enabled: config.enabled,
+    uri: config.uri,
+    dbName: config.dbName,
+    projectKey: config.projectKey,
+    direction: config.direction,
+    batchSize: config.batchSize,
+    autoSyncOnSessionEnd: config.autoSyncOnSessionEnd,
+    createdAt: config.createdAt ?? existing?.createdAt ?? now,
+    updatedAt: config.updatedAt ?? now
+  };
+
+  const configPath = getMongoSyncConfigPath(storagePath);
+  const tmpPath = `${configPath}.tmp`;
+
+  // 0600: contains secrets (Mongo URI may embed credentials)
+  fs.writeFileSync(tmpPath, JSON.stringify(normalized, null, 2), { mode: 0o600 });
+  fs.renameSync(tmpPath, configPath);
+
+  return normalized;
+}
+
+export function removeMongoSyncConfig(storagePath: string): boolean {
+  const configPath = getMongoSyncConfigPath(storagePath);
+  if (!fs.existsSync(configPath)) return false;
+  fs.unlinkSync(configPath);
+  return true;
+}
+
+export function redactMongoUri(uri: string): string {
+  // mongodb://user:pass@host:port/  -> mongodb://user:***@host:port/
+  // mongodb+srv://user:pass@host/  -> mongodb+srv://user:***@host/
+  const schemeIdx = uri.indexOf('://');
+  if (schemeIdx === -1) return uri;
+  const atIdx = uri.indexOf('@', schemeIdx + 3);
+  if (atIdx === -1) return uri;
+
+  const creds = uri.slice(schemeIdx + 3, atIdx); // user:pass
+  const colonIdx = creds.indexOf(':');
+  if (colonIdx === -1) return uri;
+
+  const prefix = uri.slice(0, schemeIdx + 3 + colonIdx + 1);
+  const suffix = uri.slice(atIdx);
+  return `${prefix}***${suffix}`;
+}
+