hrr-memory 0.3.2 → 0.4.0

package/types/index.d.ts

@@ -1,257 +1,257 @@
-// ── Core types ───────────────────────────────────────
-
-export interface QueryResult {
-  match: string | null;
-  score: number;
-  confident: boolean;
-  bucket: string | null;
-}
-
-export interface Fact {
-  relation: string;
-  object: string;
-}
-
-export interface Triple {
-  subject: string;
-  relation: string;
-  object: string;
-}
-
-export interface DirectAskResult {
-  type: 'direct';
-  match: string;
-  score: number;
-  confident: boolean;
-  subject: string;
-  relation: string;
-  bucket: string | null;
-}
-
-export interface SubjectAskResult {
-  type: 'subject';
-  subject: string;
-  facts: Fact[];
-}
-
-export interface SearchAskResult {
-  type: 'search';
-  term: string;
-  results: Triple[];
-}
-
-export interface MissAskResult {
-  type: 'miss';
-  query: string;
-}
-
-export type AskResult = DirectAskResult | SubjectAskResult | SearchAskResult | MissAskResult;
-
-export interface BucketStats {
-  name: string;
-  facts: number;
-  full: boolean;
-}
-
-export interface Stats {
-  dimensions: number;
-  maxBucketSize: number;
-  symbols: number;
-  buckets: number;
-  subjects: number;
-  totalFacts: number;
-  ramBytes: number;
-  ramMB: number;
-  perBucket: BucketStats[];
-}
-
-export interface SerializedMemory {
-  version: number;
-  d: number;
-  symbols: Record<string, number[]>;
-  buckets: Record<string, unknown>;
-  routing: Record<string, string[]>;
-}
-
-export class HRRMemory {
-  constructor(dimensions?: number);
-
-  store(subject: string, relation: string, object: string): boolean;
-  forget(subject: string, relation: string, object: string): boolean;
-  query(subject: string, relation: string): QueryResult;
-  querySubject(subject: string): Fact[];
-  search(relation: string | null, object: string | null): Triple[];
-  ask(question: string): AskResult;
-  stats(): Stats;
-
-  save(filePath: string): void;
-  static load(filePath: string, dimensions?: number): HRRMemory;
-
-  toJSON(): SerializedMemory;
-  static fromJSON(data: SerializedMemory): HRRMemory;
-}
-
-export class SymbolTable {
-  constructor(dimensions?: number);
-  get(name: string): Float32Array;
-  has(name: string): boolean;
-  readonly size: number;
-  readonly bytes: number;
-  nearest(
-    vec: Float32Array,
-    candidates?: Map<string, Float32Array> | null,
-    topK?: number
-  ): { name: string; score: number } | { name: string; score: number }[] | null;
-  toJSON(): Record<string, number[]>;
-  static fromJSON(data: Record<string, number[]>, dimensions: number): SymbolTable;
-}
-
-export class Bucket {
-  constructor(name: string, dimensions?: number);
-  readonly name: string;
-  readonly count: number;
-  readonly isFull: boolean;
-  storeVector(association: Float32Array, triple: Triple): void;
-  rebuild(symbols: SymbolTable): void;
-  toJSON(): unknown;
-  static fromJSON(data: unknown, dimensions: number): Bucket;
-}
-
-export function bind(a: Float32Array, b: Float32Array): Float32Array;
-export function unbind(key: Float32Array, memory: Float32Array): Float32Array;
-export function similarity(a: Float32Array, b: Float32Array): number;
-export function randomVector(dimensions: number): Float32Array;
-export function normalize(v: Float32Array): Float32Array;
-
-// ── Observation layer types ───��──────────────────────
-
-export interface TimelineEntry {
-  ts: number;
-  subject: string;
-  relation: string;
-  object: string;
-  op: 'store' | 'forget';
-  conflict?: { oldObject: string; similarity: number };
-}
-
-export interface ConflictFlag {
-  ts: number;
-  subject: string;
-  relation: string;
-  newObject: string;
-  oldObject: string;
-  similarity: number;
-}
-
-export interface Observation {
-  id: string;
-  subject: string;
-  observation: string;
-  evidence: Array<{ ts: number; triple: [string, string, string] }>;
-  confidence: 'high' | 'medium' | 'low';
-  supersedes: string[];
-  createdAt: number;
-}
-
-export interface ConsolidationInput {
-  entries: TimelineEntry[];
-  flags: ConflictFlag[];
-  existingObservations: Array<{
-    id: string;
-    subject: string;
-    observation: string;
-    confidence: string;
-  }>;
-}
-
-export interface ObservationMemoryOptions {
-  executor?: (prompt: string) => Promise<string>;
-  autoConsolidateAfter?: number | null;
-  promptFn?: (input: ConsolidationInput) => string;
-  conflictThreshold?: number;
-}
-
-export interface SerializedObservationMemory {
-  version: number;
-  meta: {
-    createdAt: number;
-    lastConsolidation: number | null;
-    totalStores: number;
-    totalForgets: number;
-    totalConsolidations: number;
-  };
-  timeline: TimelineEntry[];
-  observations: Observation[];
-  flags: ConflictFlag[];
-  obsCounter: number;
-}
-
-export class Timeline {
-  constructor();
-  append(entry: TimelineEntry): void;
-  history(subject: string, relation?: string): TimelineEntry[];
-  all(): TimelineEntry[];
-  readonly length: number;
-  at(ts: number): SymbolicProxy;
-  toJSON(): TimelineEntry[];
-  static fromJSON(data: TimelineEntry[]): Timeline;
-}
-
-export class SymbolicProxy {
-  constructor(entries: TimelineEntry[], ts: number);
-  facts(subject: string, relation?: string): string[];
-}
-
-export class ConflictDetector {
-  constructor(hrr: HRRMemory, threshold?: number);
-  track(subject: string, relation: string): void;
-  check(subject: string, relation: string, object: string, ts?: number): ConflictFlag | null;
-}
-
-export class ObservationParseError extends Error {
-  constructor(message: string, raw: string);
-  readonly name: 'ObservationParseError';
-  readonly raw: string;
-}
-
-export class ObservationMemory {
-  constructor(hrr: HRRMemory, options?: ObservationMemoryOptions);
-
-  // Delegated to HRRMemory
-  query(subject: string, relation: string): QueryResult;
-  querySubject(subject: string): Fact[];
-  search(relation: string | null, object: string | null): Triple[];
-  ask(question: string): AskResult;
-  stats(): Stats;
-
-  // Store/forget with observation tracking
-  store(subject: string, relation: string, object: string): Promise<boolean>;
-  forget(subject: string, relation: string, object: string): Promise<boolean>;
-
-  // Timeline
-  history(subject: string, relation?: string): TimelineEntry[];
-  at(ts: number): SymbolicProxy;
-
-  // Conflict flags
-  flags(): ConflictFlag[];
-  clearFlags(subject: string): void;
-
-  // Observations
-  observations(subject?: string): Observation[];
-  addObservation(obs: {
-    subject: string;
-    observation: string;
-    evidence: Array<{ ts: number; triple: [string, string, string] }>;
-    confidence: 'high' | 'medium' | 'low';
-    supersedes?: string[];
-  }): Observation;
-  consolidate(): Promise<Observation[]>;
-
-  // Persistence
-  save(hrrPath: string, obsPath: string): void;
-  static load(hrrPath: string, obsPath: string, options?: ObservationMemoryOptions): ObservationMemory;
-  toJSON(): SerializedObservationMemory;
-  static fromJSON(hrr: HRRMemory, data: SerializedObservationMemory, options?: ObservationMemoryOptions): ObservationMemory;
-}
-
-export function defaultPrompt(input: ConsolidationInput): string;
+// ── Core types ───────────────────────────────────────
+
+export interface QueryResult {
+  match: string | null;
+  score: number;
+  confident: boolean;
+  bucket: string | null;
+}
+
+export interface Fact {
+  relation: string;
+  object: string;
+}
+
+export interface Triple {
+  subject: string;
+  relation: string;
+  object: string;
+}
+
+export interface DirectAskResult {
+  type: 'direct';
+  match: string;
+  score: number;
+  confident: boolean;
+  subject: string;
+  relation: string;
+  bucket: string | null;
+}
+
+export interface SubjectAskResult {
+  type: 'subject';
+  subject: string;
+  facts: Fact[];
+}
+
+export interface SearchAskResult {
+  type: 'search';
+  term: string;
+  results: Triple[];
+}
+
+export interface MissAskResult {
+  type: 'miss';
+  query: string;
+}
+
+export type AskResult = DirectAskResult | SubjectAskResult | SearchAskResult | MissAskResult;
+
+export interface BucketStats {
+  name: string;
+  facts: number;
+  full: boolean;
+}
+
+export interface Stats {
+  dimensions: number;
+  maxBucketSize: number;
+  symbols: number;
+  buckets: number;
+  subjects: number;
+  totalFacts: number;
+  ramBytes: number;
+  ramMB: number;
+  perBucket: BucketStats[];
+}
+
+export interface SerializedMemory {
+  version: number;
+  d: number;
+  symbols: Record<string, number[]>;
+  buckets: Record<string, unknown>;
+  routing: Record<string, string[]>;
+}
+
+export class HRRMemory {
+  constructor(dimensions?: number);
+
+  store(subject: string, relation: string, object: string): boolean;
+  forget(subject: string, relation: string, object: string): boolean;
+  query(subject: string, relation: string): QueryResult;
+  querySubject(subject: string): Fact[];
+  search(relation: string | null, object: string | null): Triple[];
+  ask(question: string): AskResult;
+  stats(): Stats;
+
+  save(filePath: string): void;
+  static load(filePath: string, dimensions?: number): HRRMemory;
+
+  toJSON(): SerializedMemory;
+  static fromJSON(data: SerializedMemory): HRRMemory;
+}
+
+export class SymbolTable {
+  constructor(dimensions?: number);
+  get(name: string): Float32Array;
+  has(name: string): boolean;
+  readonly size: number;
+  readonly bytes: number;
+  nearest(
+    vec: Float32Array,
+    candidates?: Map<string, Float32Array> | null,
+    topK?: number
+  ): { name: string; score: number } | { name: string; score: number }[] | null;
+  toJSON(): Record<string, number[]>;
+  static fromJSON(data: Record<string, number[]>, dimensions: number): SymbolTable;
+}
+
+export class Bucket {
+  constructor(name: string, dimensions?: number);
+  readonly name: string;
+  readonly count: number;
+  readonly isFull: boolean;
+  storeVector(association: Float32Array, triple: Triple): void;
+  rebuild(symbols: SymbolTable): void;
+  toJSON(): unknown;
+  static fromJSON(data: unknown, dimensions: number): Bucket;
+}
+
+export function bind(a: Float32Array, b: Float32Array): Float32Array;
+export function unbind(key: Float32Array, memory: Float32Array): Float32Array;
+export function similarity(a: Float32Array, b: Float32Array): number;
+export function randomVector(dimensions: number): Float32Array;
+export function normalize(v: Float32Array): Float32Array;
+
+// ── Observation layer types ───��──────────────────────
+
+export interface TimelineEntry {
+  ts: number;
+  subject: string;
+  relation: string;
+  object: string;
+  op: 'store' | 'forget';
+  conflict?: { oldObject: string; similarity: number };
+}
+
+export interface ConflictFlag {
+  ts: number;
+  subject: string;
+  relation: string;
+  newObject: string;
+  oldObject: string;
+  similarity: number;
+}
+
+export interface Observation {
+  id: string;
+  subject: string;
+  observation: string;
+  evidence: Array<{ ts: number; triple: [string, string, string] }>;
+  confidence: 'high' | 'medium' | 'low';
+  supersedes: string[];
+  createdAt: number;
+}
+
+export interface ConsolidationInput {
+  entries: TimelineEntry[];
+  flags: ConflictFlag[];
+  existingObservations: Array<{
+    id: string;
+    subject: string;
+    observation: string;
+    confidence: string;
+  }>;
+}
+
+export interface ObservationMemoryOptions {
+  executor?: (prompt: string) => Promise<string>;
+  autoConsolidateAfter?: number | null;
+  promptFn?: (input: ConsolidationInput) => string;
+  conflictThreshold?: number;
+}
+
+export interface SerializedObservationMemory {
+  version: number;
+  meta: {
+    createdAt: number;
+    lastConsolidation: number | null;
+    totalStores: number;
+    totalForgets: number;
+    totalConsolidations: number;
+  };
+  timeline: TimelineEntry[];
+  observations: Observation[];
+  flags: ConflictFlag[];
+  obsCounter: number;
+}
+
+export class Timeline {
+  constructor();
+  append(entry: TimelineEntry): void;
+  history(subject: string, relation?: string): TimelineEntry[];
+  all(): TimelineEntry[];
+  readonly length: number;
+  at(ts: number): SymbolicProxy;
+  toJSON(): TimelineEntry[];
+  static fromJSON(data: TimelineEntry[]): Timeline;
+}
+
+export class SymbolicProxy {
+  constructor(entries: TimelineEntry[], ts: number);
+  facts(subject: string, relation?: string): string[];
+}
+
+export class ConflictDetector {
+  constructor(hrr: HRRMemory, threshold?: number);
+  track(subject: string, relation: string): void;
+  check(subject: string, relation: string, object: string, ts?: number): ConflictFlag | null;
+}
+
+export class ObservationParseError extends Error {
+  constructor(message: string, raw: string);
+  readonly name: 'ObservationParseError';
+  readonly raw: string;
+}
+
+export class ObservationMemory {
+  constructor(hrr: HRRMemory, options?: ObservationMemoryOptions);
+
+  // Delegated to HRRMemory
+  query(subject: string, relation: string): QueryResult;
+  querySubject(subject: string): Fact[];
+  search(relation: string | null, object: string | null): Triple[];
+  ask(question: string): AskResult;
+  stats(): Stats;
+
+  // Store/forget with observation tracking
+  store(subject: string, relation: string, object: string): Promise<boolean>;
+  forget(subject: string, relation: string, object: string): Promise<boolean>;
+
+  // Timeline
+  history(subject: string, relation?: string): TimelineEntry[];
+  at(ts: number): SymbolicProxy;
+
+  // Conflict flags
+  flags(): ConflictFlag[];
+  clearFlags(subject: string): void;
+
+  // Observations
+  observations(subject?: string): Observation[];
+  addObservation(obs: {
+    subject: string;
+    observation: string;
+    evidence: Array<{ ts: number; triple: [string, string, string] }>;
+    confidence: 'high' | 'medium' | 'low';
+    supersedes?: string[];
+  }): Observation;
+  consolidate(): Promise<Observation[]>;
+
+  // Persistence
+  save(hrrPath: string, obsPath: string): void;
+  static load(hrrPath: string, obsPath: string, options?: ObservationMemoryOptions): ObservationMemory;
+  toJSON(): SerializedObservationMemory;
+  static fromJSON(hrr: HRRMemory, data: SerializedObservationMemory, options?: ObservationMemoryOptions): ObservationMemory;
+}
+
+export function defaultPrompt(input: ConsolidationInput): string;