enigma-memory 0.1.18 → 0.1.22

package/packages/sdk/index.d.ts

@@ -0,0 +1,760 @@
+/// <reference types="node" />
+import type { EmbeddingProvider, EncryptedVectorStore } from '../rag/index.js';
+import type {
+  ContextCarrierDescriptor,
+  CostInputs,
+  ProviderImageBlock,
+  RenderLimits,
+  RepetitionOptions,
+  TokenEstimateOverrides,
+  TransportEstimates,
+} from '../snapcompact/index.js';
+export * from '../snapcompact/index.js';
+
+export interface EnigmaOptions {
+  scope?: string;
+  agentId?: string;
+  vaultKey?: Buffer | string;
+  passphrase?: string;
+  storagePath?: string;
+  apiBase?: string;
+  authToken?: string;
+  identity?: MeshIdentity;
+  autoStartMesh?: boolean;
+  ragClient?: EnigmaRagClient;
+  meshClient?: EnigmaMeshClient;
+  marketClient?: EnigmaMarketClient;
+  ownRagClient?: boolean;
+  ownMeshClient?: boolean;
+  ownMarketClient?: boolean;
+}
+
+export interface MeshIdentity {
+  publicKey: Buffer;
+  secretKey: Buffer;
+  encryptionPublicKey: Buffer;
+  encryptionSecretKey: Buffer;
+  destination: Buffer;
+  destinationHex: string;
+}
+
+export interface TemporalMetadata {
+  validFrom: number;
+  validUntil: number | null;
+  observedAt: number;
+  isPermanent: boolean;
+}
+
+export interface MemoryAtom {
+  id: string;
+  scope: string;
+  text: string;
+  type?: string;
+  importance?: number;
+  createdAt: number;
+  temporal?: TemporalMetadata;
+  metadata?: Record<string, unknown>;
+}
+
+export interface RememberOptions {
+  id?: string;
+  scope?: string;
+  type?: 'episodic' | 'semantic' | 'procedural' | 'preference' | 'policy' | 'identity' | 'goal' | 'working' | string;
+  importance?: number;
+  validFrom?: number | string | Date;
+  validUntil?: number | string | Date | null;
+  observedAt?: number | string | Date;
+  ttlMs?: number;
+  supersedes?: string[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface RecallOptions {
+  scope?: string;
+  topK?: number;
+  threshold?: number;
+  type?: string;
+  filterSuperseded?: boolean;
+  asOfTime?: number | string | Date;
+  signal?: AbortSignal;
+}
+
+export interface RecallResult {
+  id: string;
+  text: string;
+  score: number;
+  scope: string;
+  type?: string;
+  superseded?: boolean;
+  createdAt?: number;
+  commitment?: string;
+  temporal?: TemporalMetadata;
+  importance?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface ContextPackOptions extends RecallOptions {
+  maxTokens?: number;
+}
+
+export interface ContextPack {
+  contextText: string;
+  items: RecallResult[];
+  totalChars: number;
+  estimatedTokens: number;
+}
+
+export interface EnigmaStatus {
+  agentId: string;
+  scope: string;
+  memoryCount: number;
+  vectorCount: number;
+  storagePath: string | null;
+  meshConnected: boolean;
+  activeRules: number;
+  contradictionsTracked: number;
+}
+
+export interface MemoryReceipt {
+  schema: string;
+  version: number;
+  receipt_id: string;
+  memory_id: string;
+  operation: 'append' | 'update' | 'revoke' | string;
+  commitment: string;
+  previous_root: string;
+  new_root: string;
+  leaf_index: number;
+  inclusion_proof?: unknown;
+  transition_proof?: {
+    type: string;
+    operation: string;
+    prior_size: number;
+    new_size: number;
+    prior_commitments: string[];
+    prior_commitment?: string;
+    prior_inclusion_proof?: unknown;
+    new_non_membership_proof?: unknown;
+  };
+  timestamp: string;
+  agent_pubkey: string;
+  signature: string;
+  metadata?: Record<string, unknown>;
+}
+
+export declare const AGENT_TURN_RECEIPT_REF_SCHEMA: 'enigma.agent_turn_receipt_ref.v1';
+
+export interface AgentTurnReceiptRef {
+  schema: typeof AGENT_TURN_RECEIPT_REF_SCHEMA;
+  receiptId: string;
+  memoryId: string;
+  operation: string;
+  commitment: string;
+  previousRoot: string;
+  newRoot: string;
+  agentPubkey: string;
+  receiptDigest: string;
+}
+
+export type AgentContextCarrierMode = 'text' | 'bitmap-png' | 'auto';
+
+export interface AgentContextCarrierOptions {
+  mode?: AgentContextCarrierMode;
+  provider?: string;
+  model?: string;
+  vision?: boolean;
+  costs?: CostInputs;
+  costAssumptions?: CostInputs;
+  expectedReuse?: number;
+  tokenEstimates?: TokenEstimateOverrides;
+  limits?: RenderLimits;
+  renderLimits?: RenderLimits;
+  tabWidth?: number;
+  collapseRepeatedLines?: boolean;
+  repetition?: RepetitionOptions;
+}
+
+export interface AgentContextCarrierDecision {
+  readonly requested: AgentContextCarrierMode;
+  readonly selected: 'text' | 'bitmap-png';
+  readonly eligible: boolean;
+  readonly reason: string;
+  readonly profile: string | null;
+  readonly preparationStatus: 'prepared' | 'text-fallback';
+  readonly deliveryConfirmed: false;
+  readonly expectedReuse?: number;
+  readonly frameCount?: number;
+  readonly estimates?: Readonly<TransportEstimates>;
+}
+export interface AgentContextCarrierPublicDescriptor {
+  readonly codec: ContextCarrierDescriptor['codec'];
+  readonly version: string;
+  readonly profile: string | null;
+  readonly commitment: Readonly<{
+    scheme: 'sha256-blinded-v1';
+    value: string;
+  }>;
+  readonly dimensions: ContextCarrierDescriptor['dimensions'];
+  readonly bytes: number;
+  readonly counts: ContextCarrierDescriptor['counts'];
+}
+
+
+export interface AgentContextCarrierInvocation {
+  selected: 'text' | 'bitmap-png';
+  textFallback: string;
+  blocks: Array<Readonly<ProviderImageBlock>>;
+  readonly descriptor: Readonly<ContextCarrierDescriptor>;
+  readonly decision: Readonly<AgentContextCarrierDecision>;
+}
+
+export interface AgentContextCarrierDisclosure {
+  readonly descriptor: Readonly<AgentContextCarrierPublicDescriptor>;
+  readonly decision: Readonly<AgentContextCarrierDecision>;
+}
+
+export interface AgentTurnInvocation {
+  prompt: string;
+  context: string;
+  contextPack: ContextPack;
+  metadata: Record<string, unknown>;
+  contextCarrier?: AgentContextCarrierInvocation;
+}
+
+export interface RunAgentTurnOptions<TResult = unknown> {
+  prompt: string;
+  invoke: (input: AgentTurnInvocation) => TResult | Promise<TResult>;
+  metadata?: Record<string, unknown>;
+  retrieval?: ContextPackOptions;
+  rememberResponse?: boolean;
+  contextCarrier?: AgentContextCarrierOptions;
+}
+
+export interface RunAgentTurnResult<TResult = unknown> {
+  context: ContextPack;
+  result: TResult;
+  memory: MemoryAtom | null;
+  receipts: {
+    refs: AgentTurnReceiptRef[];
+    memory: MemoryReceipt | null;
+  };
+  contextCarrier?: AgentContextCarrierDisclosure;
+}
+
+export interface UpdateMemoryOptions {
+  type?: RememberOptions['type'];
+  importance?: number;
+  validFrom?: number | string | Date;
+  validUntil?: number | string | Date | null;
+  observedAt?: number | string | Date;
+  ttlMs?: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface UpdatedMemoryAtom extends MemoryAtom {
+  updatedAt: number;
+}
+
+export interface UpdateMemoryResult {
+  memory: UpdatedMemoryAtom;
+  receipt: MemoryReceipt;
+  receiptRef: AgentTurnReceiptRef;
+}
+
+export interface CreateMemoryReceiptResult {
+  receipt: MemoryReceipt;
+  opening: {
+    blindingFactor: string;
+    contentHash: string;
+  };
+}
+
+export interface ReceiptVerificationResult {
+  ok: boolean;
+  verified: boolean;
+  receipt_id: string;
+  memory_id: string;
+  operation?: string;
+  commitment: string;
+  previous_root?: string;
+  new_root?: string;
+  signatureValid: boolean;
+  inclusionValid: boolean;
+  transitionValid: boolean;
+  openingValid?: boolean;
+  errors: string[];
+}
+
+export declare const MEMORY_RECEIPT_SCHEMA: string;
+
+export interface ErasureReceipt {
+  schema: string;
+  version: number;
+  erasure_id: string;
+  agent_id: string;
+  scope: string;
+  erased_memory_count: number;
+  pre_erasure_root: string;
+  erasure_digest: string;
+  storage_wiped?: boolean;
+  timestamp: string;
+  agent_pubkey: string;
+  signature: string;
+  metadata?: Record<string, unknown>;
+}
+
+export type ErasureAttestation = ErasureReceipt;
+
+export interface ErasureVerificationResult {
+  ok: boolean;
+  verified: boolean;
+  erasure_id: string;
+  agent_id: string;
+  signatureValid: boolean;
+  digestValid?: boolean;
+  errors: string[];
+}
+
+export declare const ERASURE_RECEIPT_SCHEMA: string;
+export declare const ERASURE_ATTESTATION_SCHEMA: string;
+export interface BlindedMemoryGrant {
+  schema: string;
+  version: number;
+  grant_id: string;
+  granter_agent_id: string;
+  granter_pubkey: string;
+  grantee_pubkey: string;
+  scope: string;
+  allowed_types: string[];
+  max_access_count: number;
+  valid_until: string;
+  issued_at: string;
+  signature: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface GrantVerificationResult {
+  ok: boolean;
+  valid: boolean;
+  grant_id: string;
+  granter_agent_id: string;
+  signatureValid: boolean;
+  expired: boolean;
+  errors: string[];
+}
+
+export declare const BLINDED_GRANT_SCHEMA: string;
+
+export interface FederatedQueryRequest {
+  schema: string;
+  version: number;
+  grant: BlindedMemoryGrant;
+  grant_id: string;
+  query: string;
+  requester_pubkey: string;
+  nonce: string;
+  timestamp: string;
+  signature: string;
+}
+
+export interface FederatedQueryVerificationResult {
+  ok: boolean;
+  valid: boolean;
+  signatureValid: boolean;
+  errors: string[];
+}
+
+export declare const FEDERATED_QUERY_REQUEST_SCHEMA: string;
+
+export declare function computeHidingCommitment(
+  plaintext: string,
+  blindingFactor?: Buffer | string | null
+): { commitment: string; blindingFactor: string; contentHash: string };
+
+export declare function verifyCommitmentOpening(
+  plaintext: string,
+  blindingFactorHex: string,
+  expectedCommitmentHex: string
+): boolean;
+
+export declare function createErasureReceipt(params: {
+  agentId: string;
+  scope: string;
+  erasedMemoryCount: number;
+  preErasureRoot: string;
+  activeCommitments?: string[];
+  signingSecretKey: Buffer | string;
+  signingPublicKey: Buffer | string;
+  metadata?: Record<string, unknown>;
+}): ErasureReceipt;
+export declare function createErasureAttestation(params: {
+  agentId: string;
+  scope: string;
+  erasedMemoryCount: number;
+  preErasureRoot: string;
+  activeCommitments?: string[];
+  storageWiped?: boolean;
+  signingSecretKey: Buffer | string;
+  signingPublicKey: Buffer | string;
+  metadata?: Record<string, unknown>;
+}): ErasureReceipt;
+
+export declare function verifyErasureReceipt(
+  receipt: ErasureReceipt,
+  options?: { expectedAgentPubkey?: string; expectedCommitments?: string[] }
+): ErasureVerificationResult;
+
+export declare function verifyErasureAttestation(
+  receipt: ErasureReceipt,
+  options?: { expectedAgentPubkey?: string; expectedCommitments?: string[] }
+): ErasureVerificationResult;
+export declare function createBlindedMemoryGrant(params: {
+  granterAgentId: string;
+  granterSecretKey: Buffer | string;
+  granterPublicKey: Buffer | string;
+  granteePublicKey: Buffer | string;
+  scope?: string;
+  allowedTypes?: string[];
+  maxAccessCount?: number;
+  validUntil?: number | string | Date;
+  metadata?: Record<string, unknown>;
+}): BlindedMemoryGrant;
+
+export declare function verifyBlindedMemoryGrant(
+  grant: BlindedMemoryGrant,
+  options?: { expectedGranteePubkey?: string; asOfTime?: number }
+): GrantVerificationResult;
+
+export declare function createFederatedQueryRequest(params: {
+  grant: BlindedMemoryGrant;
+  query: string;
+  requesterSecretKey: Buffer | string;
+  requesterPublicKey?: Buffer | string;
+  nonce?: string;
+  timestamp?: string;
+}): FederatedQueryRequest;
+
+export declare function verifyFederatedQueryRequest(
+  request: FederatedQueryRequest,
+  options?: { maxClockSkewMs?: number }
+): FederatedQueryVerificationResult;
+
+export interface EncryptedVaultBundle {
+  format: string;
+  version: number;
+  kdf?: {
+    algorithm: string;
+    hash: string;
+    salt: string;
+  };
+  ciphertext: string;
+  iv: string;
+  authTag: string;
+  count: number;
+}
+
+export declare class Enigma {
+  scope: string;
+  agentId: string;
+  storagePath: string | null;
+  passphrase: string | null;
+  vaultKey: Buffer;
+  rag: EnigmaRagClient;
+  mesh: EnigmaMeshClient;
+  market: EnigmaMarketClient;
+  contradictionGraph: unknown;
+  decisionEngine: unknown;
+  federation: EnigmaFederationRouter;
+
+  constructor(options?: EnigmaOptions);
+
+  static connect(options?: EnigmaOptions): Promise<Enigma>;
+  dispose(): Promise<void>;
+
+  static verifyReceipt(
+    receipt: MemoryReceipt,
+    options?: { expectedAgentPubkey?: string; plaintext?: string; blindingFactor?: string }
+  ): ReceiptVerificationResult;
+
+  static verifyErasure(
+    receipt: ErasureReceipt,
+    options?: { expectedAgentPubkey?: string; expectedCommitments?: string[] }
+  ): ErasureVerificationResult;
+
+  static verifyAttestation(
+    receipt: ErasureReceipt,
+    options?: { expectedAgentPubkey?: string; expectedCommitments?: string[] }
+  ): ErasureVerificationResult;
+
+  static verifyCapability(
+    grant: BlindedMemoryGrant,
+    options?: { expectedGranteePubkey?: string; asOfTime?: number }
+  ): GrantVerificationResult;
+  createReceipt(
+    memoryId: string,
+    options?: {
+      operation?: 'append' | 'update' | 'revoke' | string;
+      blindingFactor?: Buffer | string | null;
+      priorCommitment?: string;
+      metadata?: Record<string, unknown>;
+    }
+  ): Promise<MemoryReceipt>;
+
+  remember(text: string, options?: RememberOptions): Promise<{ id: string; scope: string; text: string; type: string; temporal: TemporalMetadata; createdAt: number }>;
+
+  updateMemory(id: string, text: string, options?: UpdateMemoryOptions): Promise<UpdateMemoryResult>;
+
+  runAgentTurn<TResult = unknown>(input: RunAgentTurnOptions<TResult>): Promise<RunAgentTurnResult<TResult>>;
+
+  recall(query: string, options?: RecallOptions): Promise<RecallResult[]>;
+
+  evaluateObservation(text: string, metadata?: Record<string, unknown>): { shouldRemember: boolean; novelty: number; importance: number; type: string; conflicts: Array<unknown>; reason: string };
+
+  consolidate(): Array<unknown>;
+
+  getContextPack(query: string, options?: ContextPackOptions): Promise<ContextPack>;
+
+  forget(id: string): Promise<boolean>;
+
+  grantCapability(
+    granteePublicKey: Buffer | string,
+    options?: {
+      allowedTypes?: string[];
+      maxAccessCount?: number;
+      validUntil?: number | string | Date;
+      scope?: string;
+      metadata?: Record<string, unknown>;
+    }
+  ): BlindedMemoryGrant;
+  resetSession(options?: { wipeStorage?: boolean; metadata?: Record<string, unknown> }): Promise<ErasureReceipt>;
+
+  zeroizeSession(options?: { wipeStorage?: boolean; metadata?: Record<string, unknown> }): Promise<ErasureReceipt>;
+
+  save(targetPath?: string): Promise<void>;
+
+  load(sourcePath?: string): Promise<void>;
+
+  status(): EnigmaStatus;
+}
+
+export declare class EnigmaFederationRouter {
+  enigma: Enigma;
+  activeGrants: Map<string, { grant: BlindedMemoryGrant; usedCount: number }>;
+  seenNonces: Map<string, number>;
+  constructor(options: { enigma: Enigma });
+  registerGrant(grant: BlindedMemoryGrant): { ok: boolean; grant_id: string };
+  revokeGrant(grantId: string): boolean;
+  queryFederatedCluster(
+    grantOrRequest: BlindedMemoryGrant | FederatedQueryRequest,
+    query?: string,
+    options?: {
+      requesterSecretKey?: Buffer | string;
+      requesterPublicKey?: Buffer | string;
+      requesterAgent?: Enigma;
+      authorization?: { requester_pubkey: string; nonce: string; timestamp: string; signature: string };
+      topK?: number;
+    }
+  ): Promise<{ ok: boolean; grant_id: string; scope: string; items: RecallResult[]; remainingAccess: number }>;
+}
+export declare class EnigmaRagClient {
+  store: EncryptedVectorStore;
+  constructor(options?: {
+    vectorStore?: EncryptedVectorStore;
+    embeddingProvider?: EmbeddingProvider;
+    embeddingModel?: 'neural' | 'lexical';
+  });
+  index(
+    id: string,
+    text: string,
+    metadata?: Record<string, unknown>,
+    options?: { epoch?: number; signal?: AbortSignal }
+  ): Promise<{ id: string; scope: string } | null>;
+  updateMetadata(id: string, metadata: Record<string, unknown>): boolean;
+  search(query: string, options?: RecallOptions): Promise<RecallResult[]>;
+  compileContext(query: string, options?: ContextPackOptions): Promise<ContextPack>;
+  encryptAtRest(vaultKey: Buffer | string): EncryptedVaultBundle;
+  dispose(): Promise<void>;
+  static fromEncryptedBundle(
+    bundle: EncryptedVaultBundle,
+    vaultKey: Buffer | string,
+    options?: { embeddingProvider?: EmbeddingProvider }
+  ): EnigmaRagClient;
+}
+
+export declare class EnigmaMeshClient {
+  node: unknown;
+  scope: string;
+  nodeId: string;
+  identity: MeshIdentity | null;
+  constructor(options?: { scope?: string; nodeId?: string; identity?: MeshIdentity });
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  announce(metadata?: Record<string, unknown>): Promise<{ action: string; nodeId: string }>;
+  send(destinationHex: string, recipientEncryptionPubKey: string | Uint8Array, message: string): Promise<{ routed: boolean; packetId: string }>;
+  onCapsule(handler: (capsule: unknown) => void): void;
+  status(): { nodeId: string; scope: string; destinationHex: string; publicKeyHex: string; encryptionPublicKeyHex: string | null; peersCount: number };
+}
+
+export interface ZkSettlementEvidence {
+  schema: 'enigma.zk_settlement_evidence.v1';
+  version: 1;
+  receipt_ref: string;
+  event: 'action.append' | 'action.revoke' | 'sale.list' | 'sale.claim' | 'sale.open';
+  circuit: 'action_transition' | 'sealed_sale_release' | null;
+  constraint_count: 90897 | 87422 | null;
+  program_id: string;
+  cluster: string;
+  transaction: { signature: string; explorer_url: string | null } | null;
+  proof: {
+    algorithm: 'groth16-bn254';
+    encoding: 'enigma.groth16_raw_be.c1c0.v1';
+    a: string;
+    b: string;
+    c: string;
+    digest: string;
+    public_inputs: string[];
+    circuit_artifact: { r1cs_sha256: string };
+    verification_key: { sha256: string };
+  } | null;
+  state: Record<string, string | number | boolean | null>;
+  predecessor_refs: string[];
+  created_at: string;
+  signer: {
+    algorithm: 'Ed25519';
+    public_key: string;
+    key_id: string;
+    signer_id: string | null;
+    signer_domain: string;
+  };
+  signature: string;
+}
+
+export interface PreparedMarketListing extends Record<string, unknown> {
+  ok: boolean;
+  proofBytes: { a: string; b: string; c: string };
+  publicInputs: string[];
+  ciphertextChunks: string[];
+  saleTermsHashHex: string;
+  payloadCommitPosHex: string;
+  keyCommitHex: string;
+  envelopeCommitHex: string;
+  receiptPda: string;
+}
+
+export interface SubmittedMarketListing extends Record<string, unknown> {
+  ok: boolean;
+  sig: string;
+  signature: string;
+  txSignature: string;
+  receiptPda: string;
+  receiptRef: string;
+  settlementReceipt: ZkSettlementEvidence;
+}
+
+export declare class EnigmaMarketClient {
+  apiBase: string;
+  authToken: string | null;
+  constructor(options?: { apiBase?: string; authToken?: string });
+  getStatus(): Promise<Record<string, unknown>>;
+  getBuyerIdentity(): Promise<Record<string, unknown>>;
+  prepareListing(options: Record<string, unknown>): Promise<PreparedMarketListing>;
+  submitListing(prepared: {
+    proofBytes: { a: string; b: string; c: string };
+    publicInputs: string[];
+    predecessorReceiptRefs?: string[];
+  }): Promise<SubmittedMarketListing>;
+  createListing(options: Record<string, unknown> & { predecessorReceiptRefs?: string[] }): Promise<{
+    ok: true;
+    listing: PreparedMarketListing & Pick<SubmittedMarketListing, 'receiptPda' | 'receiptRef' | 'settlementReceipt'>;
+    submission: SubmittedMarketListing;
+  }>;
+  verifyListing(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+  fundEscrow(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+  claim(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+  open(options: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+
+export interface SwarmAgentEntry {
+  agentId: string;
+  role: string;
+  scope: string;
+  permissions: string[];
+  memoryCount: number;
+  vectorCount: number;
+  destinationHex: string;
+  inboxCount: number;
+}
+
+export interface SwarmTopology {
+  swarmId: string;
+  agentCount: number;
+  roster: SwarmAgentEntry[];
+}
+
+export declare class EnigmaSwarmOrchestrator {
+  swarmId: string;
+  passphrase: string | null;
+  storageDir: string | null;
+  bus: unknown;
+  agents: Map<string, unknown>;
+  enigmaFactory: (options: EnigmaOptions) => Promise<Enigma>;
+
+  constructor(options?: {
+    swarmId?: string;
+    passphrase?: string;
+    storageDir?: string;
+    bus?: unknown;
+    enigmaFactory?: (options: EnigmaOptions) => Promise<Enigma>;
+  });
+
+  registerAgent(agentId: string, options?: { role?: string; permissions?: string[]; scope?: string }): Promise<Enigma>;
+  getAgent(agentId: string): Enigma | undefined;
+  unregisterAgent(agentId: string): Promise<boolean>;
+  syncGlobalRule(ruleText: string, metadata?: Record<string, unknown>): Promise<{ ruleId: string; syncedCount: number }>;
+  dispatchSignal(senderAgentId: string, targetAgentId: string, message: string): Promise<{ delivered: boolean; packetId: string; receivedPlaintext?: string }>;
+  getTopology(): SwarmTopology;
+  shutdown(): Promise<void>;
+  on(event: string, listener: (...args: unknown[]) => void): this;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+export declare class EnigmaLangChainMemory {
+  enigma: Enigma;
+  memoryKey: string;
+  inputKey: string;
+  outputKey: string;
+  maxTokens: number;
+  scope: string;
+  selectiveMemory: boolean;
+  readonly memoryKeys: string[];
+  constructor(options: { enigma: Enigma; memoryKey?: string; inputKey?: string; outputKey?: string; maxTokens?: number; scope?: string; selectiveMemory?: boolean });
+  loadMemoryVariables(values?: Record<string, unknown>): Promise<Record<string, string>>;
+  saveContext(inputValues: Record<string, unknown>, outputValues: Record<string, unknown>): Promise<void>;
+  beforeModel(promptOrMessages: unknown): Promise<{ sovereignContext: string; items: unknown[] }>;
+  afterTool(toolName: string, toolInput: unknown, toolOutput: unknown): Promise<void>;
+  onCorrection(priorFact: string, updatedFact: string, reason?: string): Promise<unknown>;
+  clear(): Promise<number>;
+}
+
+export interface EnigmaContextMiddleware {
+  enrichPrompt(params?: { prompt?: string; messages?: Array<{ role: string; content: string }>; system?: string }): Promise<Record<string, unknown>>;
+  recordTurn(userPrompt: string, modelCompletion: string, metadata?: Record<string, unknown>): Promise<MemoryAtom | null>;
+  onToolExecution(toolName: string, args: unknown, result: unknown): Promise<unknown>;
+  onCorrection(priorFact: string, updatedFact: string): Promise<unknown>;
+}
+
+export declare function createEnigmaContextMiddleware(
+  enigma: Enigma,
+  options?: { maxTokens?: number; scope?: string; autoRemember?: boolean; selectiveMemory?: boolean }
+): EnigmaContextMiddleware;
+
+export declare class EnigmaLlamaIndexRetriever {
+  enigma: Enigma;
+  similarityTopK: number;
+  scope: string;
+  constructor(options: { enigma: Enigma; similarityTopK?: number; scope?: string });
+  retrieve(query: string): Promise<Array<{ node: { id_: string; text: string; metadata: Record<string, unknown> }; score: number }>>;
+  insertNodes(nodes: Array<{ id_?: string; text: string; metadata?: Record<string, unknown> }>): Promise<number>;
+  deleteNodes(nodeIds: string[]): Promise<number>;
+  onCorrection(priorFact: string, updatedFact: string): Promise<unknown>;
+}