TypeScript SDK

The TypeScript SDK (@senselab-ai/amfs) connects Node.js and TypeScript agents to your SenseLab account — briefings, reads and writes, search, outcomes and decision traces over the HttpAdapter — and ships an in-memory adapter with ReadTracker, auto-causal linking, scopes, transactions and integrity verification for tests and prototypes.

Installation

npm install @senselab-ai/amfs

The package is ESM-only, has no runtime dependencies, and needs Node.js 18 or later for the built-in fetch. The package name still carries the project’s original name, AMFS (Agent Memory File System); npm install @senselab-ai/amfs gets you SenseLab.

Two ways to run it

The HttpAdapter is how the SDK reaches your account. Its *Async methods are what you use in an agent; the synchronous API exists for the in-memory adapter.

Mode	Adapter	API	When
Connected to SenseLab	`HttpAdapter`	`await adapter.*Async(...)`	Your agents. Everything learned is shared across sessions, agents and machines, and runs appear on the dashboard.
In memory	default `InMemoryAdapter`	synchronous `mem.read()`, `mem.write()`, …	Unit tests and prototypes. Nothing persists when the process exits, and nothing reaches SenseLab.

Over the HttpAdapter, the synchronous methods read(), write(), list() and commitOutcome() are stubs: they return null, the unsaved entry, [] and [] without calling the server, and they do not throw. Use the *Async methods on the adapter for anything that should reach SenseLab.

Quick start: connected to SenseLab

Get an API key from Settings → API Keys (see Connect to SenseLab), then:

import { AgentMemory, HttpAdapter } from "@senselab-ai/amfs";

const adapter = new HttpAdapter({
  url: "https://amfs-login.sense-lab.ai",
  apiKey: process.env.AMFS_API_KEY,
  agentId: "deploy-agent",
});
const mem = new AgentMemory("deploy-agent", { adapter });

// 1. Get briefed: compiled, confidence-ranked context for what you are about to touch.
const briefing = await adapter.briefingAsync({ entityPath: "acme/checkout", limit: 5 });

// 2. Recall specifics.
const hits = await adapter.searchAsync({
  query: "checkout worker restart loop",
  entityPath: "acme/checkout",
  minConfidence: 0.5,
  limit: 5,
});

// ... do the work ...

// 3. Write what a future agent would need.
await adapter.writeAsync({
  entityPath: "acme/checkout",
  key: "risk-worker-restart-loop",
  value: "Worker restarts loop when the Redis URL has no db index; add /0.",
  memoryType: "belief",
  confidence: 0.8,
});

// 4. Commit the outcome, naming the entries the run relied on.
await adapter.commitOutcomeAsync({
  outcomeRef: "INC-2291",
  outcomeType: "success",
  entityPath: "acme/checkout",
  causalEntryKeys: hits.map((h) => `${h.entityPath}/${h.key}`),
});

Pass causalEntryKeys on remote commits: the SDK’s ReadTracker only sees synchronous reads, so it has nothing to credit for entries fetched with searchAsync or readAsync.

The SDK does not read AMFS_HTTP_URL or AMFS_API_KEY on its own. Those variables are honoured by the MCP server and the CLI; in TypeScript, pass the URL and key to HttpAdapter yourself, as above.

Connecting to SenseLab

Using the HttpAdapter

import { AgentMemory, HttpAdapter } from "@senselab-ai/amfs";

const adapter = new HttpAdapter({
  url: "https://amfs-login.sense-lab.ai",
  apiKey: process.env.AMFS_API_KEY,
  agentId: "review-agent",          // stamped on outcomes committed through this adapter
  headers: { "X-Team": "payments" }, // optional extra headers on every request
});

const mem = new AgentMemory("review-agent", { adapter });

The HttpAdapter provides async methods for everything that reaches your account:

// Read and write
const entry = await adapter.readAsync("checkout-service", "retry-pattern");
const written = await adapter.writeAsync({
  entityPath: "checkout-service",
  key: "retry-pattern",
  value: { maxRetries: 3 },
  confidence: 0.9,
  memoryType: "fact",        // "fact" | "belief" | "experience"
  patternRefs: ["retry"],
});

// Search and list
const results = await adapter.searchAsync({
  query: "retry strategy",
  entityPath: "checkout-service",
  minConfidence: 0.7,
  sortBy: "confidence",
  limit: 10,
});
const entries = await adapter.listAsync("checkout-service");

// Briefing — compiled, ranked knowledge about an entity
const briefing = await adapter.briefingAsync({ entityPath: "checkout-service", limit: 5 });

// Outcomes — this is where learning happens
const result = await adapter.commitOutcomeAsync({
  outcomeRef: "DEP-500",
  outcomeType: "success",   // "success" | "minor_failure" | "failure" | "critical_failure"
  entityPath: "checkout-service",
  causalEntryKeys: ["checkout-service/retry-pattern"],
  causalConfidence: 0.9,
});

// Stats and health
const stats = await adapter.statsAsync();
const health = await adapter.healthAsync();

// Decision traces
const traces = await adapter.listTracesAsync({
  entityPath: "checkout-service",
  outcomeType: "success",
  limit: 5,
});
const trace = await adapter.getTraceAsync(traces[0].id);
console.log(trace?.causalEntries, trace?.externalContexts, trace?.sessionDurationMs);

Requests that fail are thrown as Error("AMFS API <status>: <body>"), so a wrong key surfaces as a 401 on the first call rather than as silently missing data.

Direct REST calls

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

See the Connect to SenseLab guide, MCP server, and REST API reference for details.

Quick start: in memory

The sections from here through Stats describe the synchronous API, which runs on the in-memory adapter. Use it in unit tests and prototypes; in an agent, use the *Async methods above.

import { AgentMemory, OutcomeType } from "@senselab-ai/amfs";

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

Constructor

import { AgentMemory } from "@senselab-ai/amfs";

const mem = new AgentMemory(agentId: string, options?: AgentMemoryOptions);

interface AgentMemoryOptions {
  sessionId?: string;
  adapter?: AmfsAdapter;
  config?: AMFSConfig;
}

Pass the HttpAdapter to reach your SenseLab account. Without adapter, the SDK uses the in-memory adapter and nothing leaves the process.

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", { source: "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();

Agent-Scoped Memory

The SDK distinguishes between shared memory and agent-scoped memory. Use recall, myEntries, and readFrom for explicit agent-level operations.

// Recall your own memory for a key (only entries written by this agent)
const mine = mem.recall("checkout-service", "retry-pattern");

// List everything this agent has written
const allMine = mem.myEntries("checkout-service");

// Read from another agent's memory (cross-agent knowledge transfer)
const theirs = mem.readFrom("deploy-agent", "checkout-service", "deploy-config");

Scopes

A MemoryScope provides a focused view bound to a single entity path, reducing boilerplate when working with one service or module.

const checkout = mem.scope("checkout-service");

// All operations are scoped — no need to repeat the entity path
checkout.write("retry-pattern", { maxRetries: 5 }, { confidence: 0.9 });
const entry = checkout.read("retry-pattern");
const all = checkout.list();
const history = checkout.history("retry-pattern");
const scopeInfo = checkout.info();

// Readonly scopes prevent accidental writes
const readonlyScope = mem.scope("checkout-service", { readonly: true });
readonlyScope.write("key", "value"); // throws Error

// List all entity paths that contain entries
const scopes = mem.listScopes();

// Get summary info about a scope
const info = mem.info("checkout-service");
// → { path, entryCount, avgConfidence, keys, oldest, newest }

// Render entity paths as a tree
const tree = mem.tree();

Search

import { SearchOptions } from "@senselab-ai/amfs";

const results = mem.search({
  query: "retry",                  // text query
  entityPath: "checkout-service",  // filter by entity
  entityPaths: ["svc-a", "svc-b"],// multi-scope search
  agentId: "review-agent",         // filter by author
  minConfidence: 0.5,              // minimum confidence
  maxConfidence: 1.0,              // maximum confidence
  since: "2026-03-01T00:00:00Z",  // filter by time
  patternRef: "retry-pattern",     // filter by pattern reference
  sortBy: "confidence",            // "confidence" | "recency" | "version" | "priority"
  limit: 20,                       // max results
});

Composite Scoring with RecallConfig

Pass a recallConfig to get scored results with breakdown information:

import type { RecallConfig, ScoredEntry } from "@senselab-ai/amfs";

const scored: ScoredEntry[] = mem.search({
  entityPath: "checkout-service",
  recallConfig: {
    semanticWeight: 0.4,
    recencyWeight: 0.3,
    confidenceWeight: 0.3,
    recencyHalfLifeDays: 14,
  },
});

scored.forEach(({ entry, score, breakdown }) => {
  console.log(entry.key, score, breakdown);
});

Version History

const versions = mem.history("checkout-service", "retry-pattern");
// Returns all versions, ordered by version number

// Filter by time range (ISO date strings)
const recent = mem.history("checkout-service", "retry-pattern", {
  since: "2026-03-01T00:00:00Z",
  until: "2026-04-01T00:00:00Z",
});

Watch

Subscribe to changes on an entity path:

const handle = mem.watch("checkout-service", (entry) => {
  console.log(`Updated: ${entry.key} v${entry.version}`);
});

// Later, cancel the subscription
handle.cancel();
console.log(handle.cancelled); // true

Transactions

Group multiple writes into an atomic commit:

const tx = mem.transaction("batch update retry configs");

tx.write("checkout-service", "retry-pattern", { maxRetries: 5 });
tx.write("checkout-service", "timeout-config", { timeoutMs: 3000 });
tx.write("payment-service", "retry-pattern", { maxRetries: 2 });

console.log(tx.pendingCount); // 3

// Commit all writes together
tx.commit();

Integrity Verification

Verify content hashes and integrity chains for stored entries:

const result = mem.verify("checkout-service");
// Or verify all: mem.verify()

console.log(result.totalChecked);
console.log(result.valid);
console.log(result.corrupted);   // Array of corrupted entry info
console.log(result.chainBreaks); // Array of chain break info

Commit Log & DAG

Inspect the commit history and navigate the commit DAG:

// Get recent commits on the current branch
const commits = mem.commitLog(10);
commits.forEach((c) => {
  console.log(c.id, c.message, c.entries.length);
});

// Find common ancestor of two commits
const ancestor = mem.commonAncestor(commitAId, commitBId);

Stats

const stats = mem.stats();
console.log(stats.totalEntries);
console.log(stats.totalEntities);
console.log(stats.totalAgents);
console.log(stats.confidenceAvg);
console.log(stats.outcomeLinkedCount);
console.log(stats.agents);   // Record<string, number>
console.log(stats.entities); // Record<string, number>

Rooms & Collaboration

The SDK includes room-based collaboration APIs for multi-agent knowledge sharing and negotiation. These require an HttpAdapter connection.

In the current release (0.3.2) the room and negotiation helpers below build their own request and do not attach the adapter’s API key, so against SenseLab they are rejected with 401. Until a later release fixes this, use rooms through the MCP server or the REST API.

// List rooms available to this agent
const rooms = await mem.myRooms();

// Join a room
await mem.roomJoin("room-123");

// Get room details
const info = await mem.roomInfo("room-123");

// Get recent activity
const updates = await mem.roomUpdates("room-123", { since: "2026-05-01T00:00:00Z" });

// Post a discussion message
await mem.roomDiscuss("room-123", "I've updated the retry config based on recent incidents", {
  messageType: "update",
  addressedTo: "deploy-agent",
});

// Read discussions
const messages = await mem.roomDiscussions("room-123", { limit: 20 });

// Leave a room (snapshots are preserved)
await mem.roomLeave("room-123");

Negotiation

Rooms support structured negotiation sessions between agents:

// Create a negotiation session
const session = await mem.negotiateCreate("room-123", "Retry Config Agreement", {
  description: "Agree on shared retry parameters",
  maxRounds: 5,
});

// Make a proposal
await mem.negotiatePropose("room-123", session.id, {
  action: "propose",
  proposal: { maxRetries: 3, backoffMs: 1000 },
  rationale: "Based on P99 latency data from last week",
});

// Respond to a proposal
await mem.negotiateRespond("room-123", session.id, "accept", {
  rationale: "Aligns with our SLA requirements",
});

// Check negotiation status
const status = await mem.negotiateStatus("room-123", session.id);

Full API Reference

AgentMemory

Constructor

new AgentMemory(agentId: string, options?: AgentMemoryOptions)

read

mem.read(entityPath: string, key: string, options?: {
  minConfidence?: number;
}): MemoryEntry | null;

write

mem.write(entityPath: string, key: string, value: unknown, options?: {
  confidence?: number;
  ttlAt?: string | null;
  patternRefs?: string[];
  shared?: boolean;
}): MemoryEntry;

list

mem.list(entityPath?: string, options?: {
  includeSuperseded?: boolean;
}): MemoryEntry[];

search

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

// With composite scoring
mem.search(options: SearchOptions & { recallConfig: RecallConfig }): ScoredEntry[];

history

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

stats

mem.stats(): MemoryStats;

watch

mem.watch(entityPath: string, callback: (entry: MemoryEntry) => void): WatchHandle;

verify

mem.verify(entityPath?: string): {
  totalChecked: number;
  valid: number;
  corrupted: Array<Record<string, unknown>>;
  chainBreaks: Array<Record<string, unknown>>;
};

transaction

mem.transaction(message?: string): TransactionContext;

commitLog

mem.commitLog(limit?: number): Commit[];

commonAncestor

mem.commonAncestor(commitAId: string, commitBId: string): string | null;

recordContext

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

explain

mem.explain(outcomeRef?: string): Record<string, unknown>;

commitOutcome

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

// Explicit causal keys
mem.commitOutcome(
  outcomeRef: string,
  outcomeType: OutcomeType,
  causalEntryKeys: string[],
  options?: { causalConfidence?: number },
): MemoryEntry[];

recall

mem.recall(entityPath: string, key: string, options?: {
  minConfidence?: number;
}): MemoryEntry | null;

myEntries

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

readFrom

mem.readFrom(agentId: string, entityPath: string, key: string): MemoryEntry | null;

scope

mem.scope(entityPath: string, options?: { readonly?: boolean }): MemoryScope;

listScopes

mem.listScopes(): string[];

info

mem.info(entityPath: string): ScopeInfo;

tree

mem.tree(maxDepth?: number): string;

clearReadLog

mem.clearReadLog(): void;

MemoryScope

A scoped view bound to a fixed entity path. When readonly is true, writes throw an error.

scope.read(key: string, options?: { minConfidence?: number }): MemoryEntry | null;
scope.write(key: string, value: unknown, options?: {
  confidence?: number;
  ttlAt?: string | null;
  patternRefs?: string[];
}): MemoryEntry;
scope.list(options?: { includeSuperseded?: boolean }): MemoryEntry[];
scope.search(options?: Omit<SearchOptions, "entityPath" | "entityPaths">): MemoryEntry[];
scope.history(key: string, options?: { since?: string; until?: string }): MemoryEntry[];
scope.info(): ScopeInfo;

TransactionContext

tx.write(entityPath: string, key: string, value: unknown, options?: Record<string, unknown>): void;
tx.setMessage(message: string): void;
tx.pendingCount: number;
tx.commit(): void;

Exports

import {
  // Classes
  AgentMemory,
  MemoryScope,
  CoWEngine,
  CausalTagger,
  ReadTracker,
  OutcomeBackPropagator,
  InMemoryAdapter,
  HttpAdapter,

  // Functions & constants
  createWatchHandle,
  defaultConfig,
  OutcomeType,
  OUTCOME_MULTIPLIERS,

  // Types
  type AgentMemoryOptions,
  type SearchOptions,
  type MemoryStats,
  type AmfsAdapter,
  type WatchHandle,
  type HttpAdapterOptions,
  type DecisionTrace,
  type DecisionTraceSummary,
  type ExternalContext,
  type MemoryEntry,
  type OutcomeRecord,
  type Provenance,
  type ArtifactRef,
  type AMFSConfig,
  type LayerConfig,
  type RecallConfig,
  type ScopeInfo,
  type ScoredEntry,
} from "@senselab-ai/amfs";

OutcomeType Values

enum OutcomeType {
  SUCCESS = "success",
  MINOR_FAILURE = "minor_failure",
  FAILURE = "failure",
  CRITICAL_FAILURE = "critical_failure",
}

Troubleshooting

Nothing shows up on the dashboard. Either the memory is on the default in-memory adapter, or you called the synchronous methods over an HttpAdapter — they are stubs and never reach the server. Pass { adapter: new HttpAdapter({ url, apiKey }) } and use adapter.readAsync / writeAsync / commitOutcomeAsync. See Two ways to run it. Error: AMFS API 401. The API key is missing or wrong. Keys come from Settings → API Keys on the dashboard; the SDK does not read AMFS_API_KEY from the environment for you. commitOutcomeAsync moved no confidence. Pass causalEntryKeys — the entries the run relied on, as "entity/key" strings. The local ReadTracker cannot see reads made with the async methods. Room calls fail with 401. Known limitation of 0.3.2 — see the warning under Rooms & Collaboration above. Use the MCP server or the REST API for rooms in the meantime.

​TypeScript SDK

​Installation

​Two ways to run it

​Quick start: connected to SenseLab

​Connecting to SenseLab

​Using the HttpAdapter

​Direct REST calls

​Quick start: in memory

​Constructor

​ReadTracker & Auto-Causal Linking

​Agent-Scoped Memory

​Scopes

​Search

​Composite Scoring with RecallConfig

​Version History

​Watch

​Transactions

​Integrity Verification

​Commit Log & DAG

​Stats

​Rooms & Collaboration

​Negotiation

​Full API Reference

​AgentMemory

​Constructor

​read

​write

​list

​search

​history

​stats

​watch

​verify

​transaction

​commitLog

​commonAncestor

​recordContext

​explain

​commitOutcome

​recall

​myEntries

​readFrom

​scope

​listScopes

​info

​tree

​clearReadLog

​MemoryScope

​TransactionContext

​Exports

​OutcomeType Values

​Troubleshooting

​See also

TypeScript SDK

Installation

Two ways to run it

Quick start: connected to SenseLab

Connecting to SenseLab

Using the HttpAdapter

Direct REST calls

Quick start: in memory

Constructor

ReadTracker & Auto-Causal Linking

Agent-Scoped Memory

Scopes

Search

Composite Scoring with RecallConfig

Version History

Watch

Transactions

Integrity Verification

Commit Log & DAG

Stats

Rooms & Collaboration

Negotiation

Full API Reference

AgentMemory

Constructor

read

write

list

search

history

stats

watch

verify

transaction

commitLog

commonAncestor

recordContext

explain

commitOutcome

recall

myEntries

readFrom

scope

listScopes

info

tree

clearReadLog

MemoryScope

TransactionContext

Exports

OutcomeType Values

Troubleshooting

See also