SDK API reference

interface Oort {
  readonly mode: 'local' | 'cloud';
  readonly judge: OortJudge;
  recall(query: string, opts?: RecallOptions): Promise<RecallResult>;
  observe(turn: Turn, opts?: { signal?: AbortSignal }): Promise<ObserveResult>;
  remember(facts: string | readonly string[], opts?: { type?: MemoryType }): Promise<RememberResult>;
  forget(id: string, opts?: { everywhere?: boolean }): Promise<ForgetResult>;
  pin(id: string): Promise<PinResult>;
  unpin(id: string): Promise<PinResult>;
  recent(opts?: { since?: string | Date; limit?: number }): Promise<{ memories: MemoryView[]; warnings: Warning[] }>;
  explain(id: string): Promise<Explanation>;
  whoami(): Promise<Whoami>;
  consolidate(opts?: { budgetMs?: number; signal?: AbortSignal }): Promise<ConsolidateResult>;
  scoped(s: ScopedOptions): Oort;
  close(): Promise<void>;
  [Symbol.asyncDispose](): Promise<void>;
}

interface OortJudge {
  record(input: JudgmentInput): Promise<RecordJudgmentView>;
  apply(item: string | JudgeItem, opts?: JudgeOptions): Promise<JudgeResult>;
  list(opts?: { domain?: string; by?: string; all?: boolean; limit?: number }): Promise<{ judgments: (JudgmentView & { id: string })[] }>;
  confirm(id: string): Promise<{ id: string; changed: boolean }>;
}

interface Turn {
  user: string;
  assistant: string;
  tools?: string[];
  at?: string | Date;
  sessionId?: string;
  turnRef?: string;
}

interface ScopedOptions {
  user?: string;
  project?: string | null;
  agent?: string;
  judgeRole?: 'agent';
}

interface JudgmentInput {
  subject: string;
  ref?: string;
  verdict: string;
  verdicts?: readonly string[];
  reason: string;
  criteria?: readonly string[];
  domain: string;
  by: string;
  decidedAt?: string | Date;
}

interface JudgeItem {
  summary: string;
  details?: string;
  ref?: string;
  domain?: string;
  by?: string;
}

interface JudgeOptions {
  limit?: number;
  threshold?: number;
  minSimilarity?: number;
  minAgreement?: number;
  includeImported?: boolean;
  includeAgentRecorded?: boolean;
}

interface RecallResult {
  memories: RecalledMemory[];
  abstained: boolean;
  temporal: { mode: RecallMode; asOf?: string; knownAt?: string; inferred: boolean };
  read: string[];
  degraded: string[];
  warnings: Warning[];
}

interface MemoryView {
  id: string;
  text: string;
  type: MemoryType;
  tier: 'hot' | 'warm' | 'cold';
  pinned: boolean;
  status: MemoryStatus;
  validFrom: string;
  validTo: string | null;
  recordedAt: string;
  updatedAt: string;
  entities: string[];
  origin?: { level: IncludeLevel; space: string; author?: string; overriddenBy?: string };
  judgment?: JudgmentView & { id: string };
}

interface RecalledMemory extends MemoryView {
  score: number;
  stale?: true;
  why: { lexicalRank?: number; denseRank?: number; reranked?: number; coverage: number; dense?: number; activation: number; chain?: true }; // experimental
}

interface Warning {
  code: string;
  message: string;
}

interface ObserveResult {
  outcome: Outcome;
  memories: { outcome: Outcome; id?: string; supersedes?: string; reason?: string }[];
  counts: Partial<Record<Outcome, number>>;
  duplicate?: true;
  warnings: Warning[];
}

interface RememberResult {
  results: { fact: number; outcome: Outcome; id?: string; supersedes?: string; reason?: string }[];
  warnings: Warning[];
}

interface ForgetResult {
  forgotten: string;
  withdrawn?: string[];
}

interface PinResult {
  id: string;
  pinned: boolean;
  changed: boolean | null;
}

interface ConsolidateResult {
  promoted: string[];
  demoted: string[];
  evicted: string[];
  expired: string[];
  skipped: number;
  complete: boolean;
}

interface Explanation {
  memory: MemoryView & { salience: number; activation: number; source: string };
  decisions: { stage: string; question: string; answer: string; probability: number }[];
  chain: { id: string; text: string; validFrom: string; validTo: string | null; endReason: 'superseded' | 'corrected' | 'expired' | null }[];
  hiddenLinks: number;
}

interface Whoami {
  mode: 'local' | 'cloud';
  account: string | null;
  agent: string | null;
  project: string | null;
  user: string | null;
  reads: string[];
  writesTo: string;
  version: string;
  routes: Record<'embed' | 'rerank' | 'decide' | 'write', RouteKind>;
}

interface RecordJudgmentView {
  outcome: 'added' | 'corrected' | 'unchanged';
  id: string;
  corrects?: string;
  status: 'agent-recorded' | 'recorded';
  redacted: string[];
  embedFailed?: true;
}

interface JudgeResult {
  status: 'suggested' | 'needs-expert' | 'precedents-only';
  why?: 'no-precedents' | 'too-far' | 'too-few' | 'precedents-disagree' | 'low-confidence' | 'no-decider' | 'decider-failed';
  prediction?: { verdict: string; probability: number; probabilities: Record<string, number> };
  precedents: Precedent[];
  verdicts: string[];
  agreement: Record<string, number>;
  similarity: 'dense' | 'lexical';
  threshold: number;
  minSimilarity: number;
  degraded?: string[];
  decisions: { stage: string; question: string; answer: string; probability: number }[]; // experimental
  importedExcluded?: number;
  agentRecordedExcluded?: number;
}

interface Precedent {
  id: string;
  subject: { summary: string; ref?: string };
  verdict: string;
  reason: string;
  criteria: string[];
  domain: string;
  by: string;
  decidedAt: string;
  similarity: number;
  near: boolean;
  agrees?: boolean;
  via: JudgmentVia;
  confirmed: boolean;
  agentRecorded: boolean;
  pack?: { id: string; name: string };
}

interface JudgmentView {
  subject: { summary: string; ref?: string };
  verdict: string;
  verdicts: string[];
  reason: string;
  criteria: string[];
  domain: string;
  by: string;
  decidedAt: string;
  via: JudgmentVia;
  status: MemoryStatus;
  confirmed: boolean;
  agentRecorded: boolean;
  withdrawn?: { at: string; by: string };
  pack?: { id: string; name: string };
}