TypeScript SDK

The TypeScript SDK (@amfs/sdk) provides full parity with the Python SDK for Node.js and TypeScript applications — including ReadTracker, auto-causal linking, search, history, stats, and explainability.

Table of Contents

1. Installation
2. Quick Start
3. ReadTracker & Auto-Causal Linking
4. Version History
5. Search
6. Stats
7. Connecting to AMFS SaaS
   1. Via MCP Server
   2. Via REST API
8. Full API Reference
   1. Constructor
   2. write
   3. read
   4. list
   5. search
   6. history
   7. stats
   8. commitOutcome
   9. recordContext
   10. explain
   11. clearReadLog
9. Exports
10. Notes

---

Installation

npm install @amfs/sdk

---

Quick Start

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);

---

ReadTracker & Auto-Causal Linking

The TypeScript SDK includes a ReadTracker that automatically logs every read() call and external context. When you call commitOutcome() without explicit causal keys, the SDK uses the read log to build the causal chain — identical to the Python SDK behavior.

// 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();

---

Version History

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"),
});

---

Search

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
});

---

Stats

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

---

Connecting to AMFS SaaS

When using AMFS as a hosted service (SaaS), connect through the HTTP API with your API key instead of a direct database connection.

The TypeScript SDK currently uses an in-memory adapter by default. For SaaS, agents should use the MCP server (with AMFS_HTTP_URL set) or make direct REST API calls.

Via MCP Server

Configure the MCP server with HTTP adapter environment variables:

{
  "mcpServers": {
    "amfs": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/amfs", "amfs-mcp-server"],
      "env": {
        "AMFS_HTTP_URL": "https://amfs-login.sense-lab.ai",
        "AMFS_API_KEY": "amfs_sk_your_key_here"
      }
    }
  }
}

Via REST API

Make direct HTTP calls with the X-AMFS-API-Key header:

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 },
  }),
});

Never use AMFS_POSTGRES_DSN for external agents in multi-tenant mode. Always use AMFS_HTTP_URL + AMFS_API_KEY to ensure tenant isolation.

See the SaaS Connection Guide and Environment Variables for details.

---

Full API Reference

Constructor

const mem = new AgentMemory(agentId: string);

write

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

read

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

list

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

search

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

history

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

stats

mem.stats(): MemoryStats;

commitOutcome

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

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

recordContext

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

explain

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

clearReadLog

mem.clearReadLog(): void;

---

Exports

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

---

Notes

The TypeScript SDK uses an in-memory adapter by default. For persistent storage, use the Python SDK, HTTP API, or MCP server with a Postgres or S3 backend.