@membank/core 0.9.4 → 0.11.0

package/dist/index.d.mts

@@ -1,30 +1,10 @@
-import BetterSqlite3 from "better-sqlite3";
 import { z } from "zod";
+import BetterSqlite3 from "better-sqlite3";
+import { EventEmitter } from "node:events";
 
 //#region src/config/loader.d.ts
 declare function isSynthesisEnabled(): boolean;
 //#endregion
-//#region src/db/errors.d.ts
-declare class MembankError extends Error {
-  constructor(message: string, options?: ErrorOptions);
-}
-declare class DatabaseError extends MembankError {
-  constructor(message: string, options?: ErrorOptions);
-}
-//#endregion
-//#region src/db/manager.d.ts
-type VecLoader = (db: BetterSqlite3.Database) => void;
-declare class DatabaseManager {
-  #private;
-  private constructor();
-  static open(dbPath?: string): DatabaseManager;
-  static openInMemory(): DatabaseManager;
-  /** For testing: inject a custom vec loader (e.g. a throwing stub). */
-  static _openInMemoryWithLoader(loader: VecLoader): DatabaseManager;
-  get db(): BetterSqlite3.Database;
-  close(): void;
-}
-//#endregion
 //#region src/schemas.d.ts
 declare const MEMORY_TYPE_VALUES: readonly ["correction", "preference", "decision", "learning", "fact"];
 declare const MemoryTypeSchema: z.ZodEnum<{
@@ -270,16 +250,133 @@ declare const ProjectRowSchema: z.ZodObject<{
 }, z.core.$strip>;
 type ProjectRow = z.infer<typeof ProjectRowSchema>;
 //#endregion
-//#region src/db/row-types.d.ts
+//#region src/persistence/infrastructure/row-types.d.ts
 declare function rowToMemory(row: MemoryRow, projects: Project[], reviewEvents?: ReviewEvent[]): Memory;
 declare function rowToProject(row: ProjectRow): Project;
 //#endregion
-//#region src/embedding/service.d.ts
+//#region src/db/errors.d.ts
+declare class MembankError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class DatabaseError extends MembankError {
+  constructor(message: string, options?: ErrorOptions);
+}
+//#endregion
+//#region src/db/manager.d.ts
+type VecLoader = (db: BetterSqlite3.Database) => void;
+declare class DatabaseManager {
+  #private;
+  private constructor();
+  static open(dbPath?: string): DatabaseManager;
+  static openInMemory(): DatabaseManager;
+  /** For testing: inject a custom vec loader (e.g. a throwing stub). */
+  static _openInMemoryWithLoader(loader: VecLoader): DatabaseManager;
+  get db(): BetterSqlite3.Database;
+  close(): void;
+}
+//#endregion
+//#region src/embedding/infrastructure/model-downloader.d.ts
+declare const MODEL_NAME = "Xenova/bge-small-en-v1.5";
+interface DownloadProgress {
+  totalBytes: number;
+  downloadedBytes: number;
+  percentage: number;
+  estimatedSecondsRemaining: number;
+}
+interface DownloadResult {
+  skipped: boolean;
+}
+declare class ModelDownloadError extends Error {
+  constructor(message: string, options?: ErrorOptions);
+}
+declare class ModelDownloader extends EventEmitter {
+  private readonly modelPath;
+  constructor(modelPath?: string);
+  isAlreadyCached(): boolean;
+  get cachePath(): string;
+  download(): Promise<DownloadResult>;
+}
+//#endregion
+//#region src/memory/ports.d.ts
+interface SimilarMemoryResult {
+  id: string;
+  similarity: number;
+}
+interface StatsResult {
+  byType: Record<MemoryType, number>;
+  total: number;
+  pinned: number;
+  needsReview: number;
+  pinBudgetChars: number;
+}
+interface MemoryExportRecord {
+  id: string;
+  content: string;
+  type: MemoryType;
+  tags: string[];
+  sourceHarness: string | null;
+  accessCount: number;
+  pinned: boolean;
+  createdAt: string;
+  updatedAt: string;
+  embedding: Float32Array | null;
+}
+interface CreateMemoryOpts {
+  id: string;
+  content: string;
+  type: MemoryType;
+  tags: string[];
+  sourceHarness: string | null;
+  embedding: Float32Array;
+  projectScope?: {
+    hash: string;
+    name: string;
+  };
+}
+interface CreateReviewEventOpts {
+  memoryId: string;
+  conflictingMemoryId: string;
+  similarity: number;
+  conflictContentSnapshot: string;
+}
+interface MemoryRepository {
+  findById(id: string): Memory | undefined;
+  findSimilar(embedding: Float32Array, type: MemoryType, projectHash?: string): SimilarMemoryResult[];
+  list(opts?: {
+    type?: MemoryType;
+    pinned?: boolean;
+    needsReview?: boolean;
+    projectId?: string;
+  }): Memory[];
+  listPinnedGlobal(): Memory[];
+  listPinnedForProject(projectHash: string): Memory[];
+  listFlagged(): Memory[];
+  listReviewEvents(memoryId: string, opts?: {
+    unresolvedOnly?: boolean;
+  }): ReviewEvent[];
+  getPinnedCharCount(): number;
+  stats(): StatsResult;
+  create(opts: CreateMemoryOpts): Memory;
+  overwrite(id: string, content: string, embedding: Float32Array): Memory;
+  update(id: string, patch: MemoryPatch, embedding?: Float32Array): Memory;
+  delete(id: string): void;
+  createReviewEvent(opts: CreateReviewEventOpts): void;
+  resolveReviewEvents(memoryId: string): void;
+  setPin(id: string, pinned: boolean): Memory;
+  incrementAccessCount(id: string): void;
+  exportAll(): MemoryExportRecord[];
+  importAll(records: MemoryExportRecord[]): void;
+}
+interface Embedder {
+  embed(text: string): Promise<Float32Array>;
+}
+//#endregion
+//#region src/embedding/infrastructure/huggingface-embedding-service.d.ts
 type ProgressCallback = (progress: {
   status: string;
   progress?: number;
 }) => void;
-declare class EmbeddingService {
+declare class EmbeddingService implements Embedder {
   private readonly modelCachePath;
   private readonly onProgress;
   private pipelineInstance;
@@ -288,10 +385,120 @@ declare class EmbeddingService {
   embed(text: string): Promise<Float32Array>;
 }
 //#endregion
-//#region src/project/repository.d.ts
-declare class ProjectRepository {
-  #private;
-  constructor(db: DatabaseManager);
+//#region src/extraction/ports.d.ts
+interface ExtractionConfig {
+  /** Window after a run starts during which a duplicate run for the same session_id is skipped. */
+  inFlightTimeoutMs?: number;
+  /** Window after a successful run during which a repeated run for the same session_id is skipped. */
+  recentCompletionMs?: number;
+}
+interface ExtractionRunRecord {
+  sessionId: string;
+  startedAt: string;
+  completedAt: string | null;
+  status: "in_flight" | "completed" | "failed";
+  error: string | null;
+}
+interface ExtractionRunRepository {
+  /** Atomic claim: returns true if the caller should proceed, false if already in flight or recently completed. */
+  tryClaim(sessionId: string, now: Date, config: ExtractionConfig): boolean;
+  markCompleted(sessionId: string, now: Date): void;
+  markFailed(sessionId: string, now: Date, error: string): void;
+  get(sessionId: string): ExtractionRunRecord | undefined;
+}
+interface TranscriptReader {
+  /** Returns the recent transcript content (plain text) for the agent to inspect. */
+  read(transcriptPath: string): Promise<string>;
+}
+interface ExtractionAgentRunner {
+  /** Runs the extraction agent over the supplied transcript text and project hash. */
+  run(args: {
+    transcript: string;
+    projectHash: string;
+    sessionId: string;
+  }): Promise<void>;
+}
+interface ExtractionTools {
+  queryMemory: (args: {
+    query: string;
+    limit?: number;
+    global?: boolean;
+    projectHash?: string;
+  }) => Promise<string>;
+  saveMemory: (args: {
+    content: string;
+    type: string;
+    tags?: string[];
+    global?: boolean;
+  }) => Promise<string>;
+  updateMemory: (args: {
+    id: string;
+    content?: string;
+    type?: string;
+    tags?: string[];
+  }) => Promise<string>;
+}
+//#endregion
+//#region src/extraction/application/run-extraction.d.ts
+interface RunExtractionInput {
+  sessionId: string;
+  transcriptPath: string;
+  projectHash: string;
+}
+type RunExtractionResult = {
+  status: "completed";
+} | {
+  status: "skipped";
+  reason: "in_flight" | "recently_completed";
+} | {
+  status: "failed";
+  error: string;
+};
+declare function runExtraction(input: RunExtractionInput, deps: {
+  repo: ExtractionRunRepository;
+  transcripts: TranscriptReader;
+  agent: ExtractionAgentRunner;
+  config: ExtractionConfig;
+  now?: () => Date;
+}): Promise<RunExtractionResult>;
+//#endregion
+//#region src/extraction/infrastructure/claude-agent-runner.d.ts
+declare function createExtractionAgentRunner(tools: ExtractionTools): ExtractionAgentRunner;
+//#endregion
+//#region src/extraction/infrastructure/sqlite-extraction-run-repository.d.ts
+declare function createExtractionRunRepository(db: DatabaseManager): ExtractionRunRepository;
+//#endregion
+//#region src/extraction/infrastructure/transcript-reader.d.ts
+interface TranscriptReaderOptions {
+  maxTurns?: number;
+  maxChars?: number;
+}
+declare function createClaudeCodeTranscriptReader(opts?: TranscriptReaderOptions): TranscriptReader;
+//#endregion
+//#region src/memory/application/delete-memory.d.ts
+declare function deleteMemory(id: string, repo: MemoryRepository): Promise<void>;
+//#endregion
+//#region src/memory/application/resolve-review.d.ts
+declare function resolveReview(memoryId: string, repo: MemoryRepository): void;
+//#endregion
+//#region src/memory/application/save-memory.d.ts
+declare function saveMemory(opts: SaveOptions, deps: {
+  repo: MemoryRepository;
+  embedder: Embedder;
+}): Promise<Memory>;
+//#endregion
+//#region src/memory/application/update-memory.d.ts
+declare function updateMemory(id: string, patch: MemoryPatch, deps: {
+  repo: MemoryRepository;
+  embedder: Embedder;
+}): Promise<Memory>;
+//#endregion
+//#region src/memory/domain/pin-budget.d.ts
+declare const PIN_BUDGET_THRESHOLD = 8000;
+declare function isOverBudget(pinnedCharCount: number): boolean;
+//#endregion
+//#region src/project/ports.d.ts
+interface ProjectRepository {
   upsertByHash(hash: string, name: string): Project;
   rename(id: string, name: string): Project;
   list(): Project[];
@@ -303,34 +510,41 @@ declare class ProjectRepository {
   getProjectsForMemories(memoryIds: string[]): Map<string, Project[]>;
 }
 //#endregion
-//#region src/memory/repository.d.ts
-declare const PIN_BUDGET_THRESHOLD = 8000;
-declare class MemoryRepository {
+//#region src/memory/infrastructure/sqlite-memory-repository.d.ts
+declare class SqliteMemoryRepository implements MemoryRepository {
   #private;
-  constructor(db: DatabaseManager, embeddingService: EmbeddingService, projects: ProjectRepository);
-  save(options: SaveOptions): Promise<Memory>;
-  update(id: string, patch: MemoryPatch): Promise<Memory>;
-  delete(id: string): Promise<void>;
+  constructor(db: DatabaseManager, projects: ProjectRepository);
+  findSimilar(embedding: Float32Array, type: MemoryType, projectHash?: string): SimilarMemoryResult[];
+  create(opts: CreateMemoryOpts): Memory;
+  overwrite(id: string, content: string, embedding: Float32Array): Memory;
+  findById(id: string): Memory | undefined;
+  update(id: string, patch: MemoryPatch, embedding?: Float32Array): Memory;
+  delete(id: string): void;
   list(opts?: {
     type?: MemoryType;
     pinned?: boolean;
+    needsReview?: boolean;
+    projectId?: string;
   }): Memory[];
+  listPinnedGlobal(): Memory[];
+  listPinnedForProject(projectHash: string): Memory[];
   listFlagged(): Memory[];
   listReviewEvents(memoryId: string, opts?: {
     unresolvedOnly?: boolean;
   }): ReviewEvent[];
+  createReviewEvent(opts: CreateReviewEventOpts): void;
   resolveReviewEvents(memoryId: string): void;
   getPinnedCharCount(): number;
-  stats(): {
-    byType: Record<MemoryType, number>;
-    total: number;
-    pinned: number;
-    needsReview: number;
-    pinBudgetChars: number;
-  };
+  stats(): StatsResult;
   setPin(id: string, pinned: boolean): Memory;
   incrementAccessCount(id: string): void;
+  exportAll(): MemoryExportRecord[];
+  importAll(records: MemoryExportRecord[]): void;
 }
+declare function createMemoryRepository(db: DatabaseManager, projects: ProjectRepository): MemoryRepository;
+//#endregion
+//#region src/project/infrastructure/sqlite-project-repository.d.ts
+declare function createProjectRepository(db: DatabaseManager): ProjectRepository;
 //#endregion
 //#region src/migrations/index.d.ts
 interface MigrationMeta {
@@ -346,13 +560,35 @@ interface ScopeToProjectsResult {
 declare const MIGRATIONS: MigrationMeta[];
 declare function runScopeToProjectsMigration(projects: ProjectRepository): Promise<ScopeToProjectsResult | null>;
 //#endregion
+//#region src/query/ports.d.ts
+interface ScoredMemory extends Memory {
+  score: number;
+}
+interface QueryAdapter {
+  findByEmbedding(embedding: Buffer, opts: {
+    type?: MemoryType;
+    projectHash?: string;
+    includePinned?: boolean;
+  }): Array<Memory & {
+    cosineSim: number;
+  }>;
+}
+interface Querier {
+  query(opts: QueryOptions): Promise<ScoredMemory[]>;
+}
+//#endregion
+//#region src/query/application/query-memories.d.ts
+declare function queryMemories(options: QueryOptions, deps: {
+  adapter: QueryAdapter;
+  repo: Pick<MemoryRepository, "incrementAccessCount">;
+  embedder: Embedder;
+}): Promise<ScoredMemory[]>;
+//#endregion
 //#region src/query/engine.d.ts
-declare class QueryEngine {
+declare class QueryEngine implements Querier {
   #private;
-  constructor(db: DatabaseManager, embeddingService: EmbeddingService, repo: MemoryRepository);
-  query(options: QueryOptions): Promise<Array<Memory & {
-    score: number;
-  }>>;
+  constructor(db: DatabaseManager, embeddingService: Embedder, repo: MemoryRepository);
+  query(options: QueryOptions): Promise<ScoredMemory[]>;
 }
 //#endregion
 //#region src/scope/resolver.d.ts
@@ -362,31 +598,82 @@ declare function resolveProject(): Promise<{
 }>;
 declare function resolveScope(): Promise<string>;
 //#endregion
+//#region src/session/application/get-session-context.d.ts
+declare function getSessionContext(opts: {
+  projectHash: string;
+  synthesis?: string;
+}, deps: {
+  repo: MemoryRepository;
+}): SessionContext;
+//#endregion
 //#region src/session/builder.d.ts
 declare function listMemoryTypes(): MemoryType[];
 declare class SessionContextBuilder {
   #private;
-  constructor(db: DatabaseManager);
+  constructor(repo: MemoryRepository);
   getSessionContext(projectHash: string, synthesis?: string): SessionContext;
 }
 //#endregion
-//#region src/synthesis/repository.d.ts
-declare class SynthesisRepository {
-  #private;
-  constructor(db: DatabaseManager);
+//#region src/synthesis/domain/synthesis-job.d.ts
+type ScopeStatus = "expired" | "dirty" | "missing";
+interface DirtyScope {
+  scope: string;
+  reason: ScopeStatus;
+}
+//#endregion
+//#region src/synthesis/ports.d.ts
+interface SynthesisConfig {
+  enabled: boolean;
+  maxTokensPerRun?: number;
+  debounceMs?: number;
+  stalenessDays?: number;
+  inFlightTimeoutMs?: number;
+}
+interface SynthesisTools {
+  queryMemory: (args: {
+    query: string;
+    limit?: number;
+    global?: boolean;
+    projectHash?: string;
+  }) => Promise<string>;
+  getMemorySummary: () => Promise<string>;
+}
+interface AgentRunner {
+  run(scope: string, projectHash?: string): Promise<string>;
+}
+interface SynthesisRepository {
   saveSynthesis(scope: string, content: string, sourceHash: string): Synthesis;
   getSynthesis(scope: string): Synthesis | undefined;
+  listAll(): Synthesis[];
   markInFlight(scope: string): void;
   clearInFlight(scope: string): void;
   clearStaleInFlight(thresholdMs: number): void;
   computeSourceMemoryHash(scope: string): string;
-  getExpiredOrDirtyScopes(): {
-    scope: string;
-    reason: "expired" | "dirty" | "missing";
-  }[];
+  getExpiredOrDirtyScopes(): DirtyScope[];
   getAllActiveScopes(): string[];
   expireStale(): void;
 }
 //#endregion
-export { DatabaseError, DatabaseManager, EmbeddingService, MEMORY_TYPE_VALUES, MIGRATIONS, MembankError, Memory, MemoryPatch, MemoryPatchSchema, MemoryRepository, MemoryRow, MemoryRowSchema, MemorySchema, MemoryType, MemoryTypeSchema, MigrationMeta, PIN_BUDGET_THRESHOLD, ProgressCallback, Project, ProjectRepository, ProjectRow, ProjectRowSchema, ProjectSchema, QueryEngine, QueryOptions, QueryOptionsSchema, ReviewEvent, ReviewEventRow, ReviewEventRowSchema, ReviewEventSchema, ReviewReason, ReviewReasonSchema, SaveOptions, SaveOptionsSchema, ScopeToProjectsResult, SessionContext, SessionContextBuilder, SessionContextSchema, Synthesis, SynthesisRepository, SynthesisSchema, TagsJsonSchema, isSynthesisEnabled, listMemoryTypes, resolveProject, resolveScope, rowToMemory, rowToProject, runScopeToProjectsMigration };
+//#region src/synthesis/application/engine.d.ts
+declare class SynthesisEngine {
+  #private;
+  constructor(synthRepo: SynthesisRepository, config: SynthesisConfig, agentRunner: AgentRunner);
+  init(): Promise<void>;
+  shutdown(): Promise<void>;
+  markDirty(scope: string): void;
+}
+//#endregion
+//#region src/synthesis/application/run-synthesis.d.ts
+declare function runSynthesis(scope: string, deps: {
+  synthRepo: SynthesisRepository;
+  agentRunner: AgentRunner;
+}): Promise<string>;
+//#endregion
+//#region src/synthesis/infrastructure/claude-agent-runner.d.ts
+declare function createSynthesisAgentRunner(tools: SynthesisTools, config: SynthesisConfig): AgentRunner;
+//#endregion
+//#region src/synthesis/infrastructure/sqlite-synthesis-repository.d.ts
+declare function createSynthesisRepository(db: DatabaseManager): SynthesisRepository;
+//#endregion
+export { type AgentRunner, type CreateMemoryOpts, type CreateReviewEventOpts, DatabaseError, DatabaseManager, type DownloadProgress, type DownloadResult, type Embedder, EmbeddingService, type ExtractionAgentRunner, type ExtractionConfig, type ExtractionRunRecord, type ExtractionRunRepository, type ExtractionTools, MEMORY_TYPE_VALUES, MIGRATIONS, MODEL_NAME, MembankError, type Memory, type MemoryExportRecord, type MemoryPatch, MemoryPatchSchema, type MemoryRepository, type MemoryRow, MemoryRowSchema, MemorySchema, type MemoryType, MemoryTypeSchema, MigrationMeta, ModelDownloadError, ModelDownloader, PIN_BUDGET_THRESHOLD, type ProgressCallback, Project, type ProjectRepository, ProjectRow, ProjectRowSchema, ProjectSchema, type Querier, type QueryAdapter, QueryEngine, QueryOptions, QueryOptionsSchema, type ReviewEvent, type ReviewEventRow, ReviewEventRowSchema, ReviewEventSchema, ReviewReason, ReviewReasonSchema, type RunExtractionInput, type RunExtractionResult, type SaveOptions, SaveOptionsSchema, ScopeToProjectsResult, type ScoredMemory, SessionContext, SessionContextBuilder, SessionContextSchema, type SimilarMemoryResult, SqliteMemoryRepository, type StatsResult, Synthesis, type SynthesisConfig, SynthesisEngine, type SynthesisRepository, SynthesisSchema, type SynthesisTools, TagsJsonSchema, type TranscriptReader, createClaudeCodeTranscriptReader, createExtractionAgentRunner, createExtractionRunRepository, createMemoryRepository, createProjectRepository, createSynthesisAgentRunner, createSynthesisRepository, deleteMemory, getSessionContext, isOverBudget, isSynthesisEnabled, listMemoryTypes, queryMemories, resolveProject, resolveReview, resolveScope, rowToMemory, rowToProject, runExtraction, runScopeToProjectsMigration, runSynthesis, saveMemory, updateMemory };
 //# sourceMappingURL=index.d.mts.map