npm install @amfs/sdk

import { AgentMemory, OutcomeType } from "@amfs/sdk";

const mem = new AgentMemory("review-agent");

// Write
mem.write("checkout-service", "retry-pattern", {
  pattern: "exponential-backoff",
  maxRetries: 3,
});

// Read — automatically tracked by ReadTracker
const entry = mem.read("checkout-service", "retry-pattern");
console.log(entry?.value);    // { pattern: "exponential-backoff", ... }
console.log(entry?.version);  // 1

// List all entries for an entity
const entries = mem.list("checkout-service");

// Search with filters
const results = mem.search({
  entityPath: "checkout-service",
  minConfidence: 0.7,
  sortBy: "confidence",
  limit: 10,
});

// Auto-causal outcome — uses ReadTracker (no explicit keys needed)
const updated = mem.commitOutcome("DEP-500", OutcomeType.SUCCESS);

// These reads are automatically tracked
mem.read("checkout-service", "retry-pattern");
mem.read("checkout-service", "pool-config");

// Record external context
mem.recordContext("pagerduty-status", "No active incidents", "PagerDuty API");

// Commit outcome — auto-links to everything read in this session
const updated = mem.commitOutcome("DEP-500", OutcomeType.SUCCESS);

// Explain the causal chain
const chain = mem.explain();
// → causalEntries: [retry-pattern, pool-config]
// → externalContexts: [{ label: "pagerduty-status", ... }]

// Clear the read log between tasks
mem.clearReadLog();

const versions = mem.history("checkout-service", "retry-pattern");
// Returns all versions, newest first

// Filter by time range
const recent = mem.history("checkout-service", "retry-pattern", {
  since: new Date("2026-03-01"),
  until: new Date("2026-04-01"),
});

import { SearchOptions } from "@amfs/sdk";

const results = mem.search({
  entityPath: "checkout-service",  // filter by entity
  agentId: "review-agent",         // filter by author
  minConfidence: 0.5,              // minimum confidence threshold
  sortBy: "confidence",            // "confidence" or "recency"
  limit: 20,                       // max results
});

const stats = mem.stats();
console.log(stats.totalEntries);
console.log(stats.totalEntities);
console.log(stats.avgConfidence);

const response = await fetch("https://amfs-login.sense-lab.ai/api/v1/entries", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-AMFS-API-Key": process.env.AMFS_API_KEY!,
  },
  body: JSON.stringify({
    entity_path: "checkout-service",
    key: "retry-pattern",
    value: { maxRetries: 3 },
  }),
});

const mem = new AgentMemory(agentId: string);

mem.write(entityPath: string, key: string, value: any, options?: {
  confidence?: number;
  patternRefs?: string[];
}): MemoryEntry;

mem.read(entityPath: string, key: string): MemoryEntry | undefined;

mem.list(entityPath?: string): MemoryEntry[];

mem.search(options?: SearchOptions): MemoryEntry[];

mem.history(entityPath: string, key: string, options?: {
  since?: Date;
  until?: Date;
}): MemoryEntry[];

mem.stats(): MemoryStats;

// Auto-causal (uses ReadTracker)
mem.commitOutcome(outcomeRef: string, outcomeType: OutcomeType): MemoryEntry[];

// Explicit causal keys
mem.commitOutcome(
  outcomeRef: string,
  outcomeType: OutcomeType,
  causalEntryKeys: string[],
): MemoryEntry[];

mem.recordContext(label: string, summary: string, source?: string): void;

mem.explain(): { causalEntries: object[]; externalContexts: object[] };

mem.clearReadLog(): void;

import {
  AgentMemory,
  CoWEngine,
  ReadTracker,
  ExternalContext,
  MemoryEntry,
  OutcomeType,
  MemoryType,
  SearchOptions,
  MemoryStats,
  ArtifactRef,
} from "@amfs/sdk";