Federate and test existing memory

This tutorial uses the public, dependency-free @praxa/sdk/memory entrypoint. The SDK is read-only. It receives provider clients your backend already owns, and it requires explicit tenant and subject namespace resolution.

Prerequisites

Before you begin, prepare:

a backend-owned provider client and explicit tenant-subject namespace resolver;
synthetic records for at least two tenants and two subjects per tenant;
the exact @praxa/sdk memory package version and supported provider contract;
a provider cleanup procedure plus degraded-state and timeout fixtures;
an acceptance assertion that proves federated recall preserves source status, provenance, contradictions, bounds, and isolation.

1. Install the package

npm install @praxa/sdk@0.3.0

The supported portable record kinds are message, fact, summary, episode, pinned_context, document, entity, and edge.

2. Create a source

Mem0 namespace filters must use positive equality with current camel-case keys: userId, agentId, appId, or runId.

import { createMem0MemorySource } from "@praxa/sdk/memory";

const mem0Source = createMem0MemorySource({
  client: mem0,
  mapNamespace: ({ tenantId, subjectId }) => ({
    userId: `${tenantId}:${subjectId}`,
  }),
  threshold: 0.6,
  rerank: true,
});

Only long-term BaseStore items are adapted. Checkpoints are intentionally excluded.

import { createLangGraphMemorySource } from "@praxa/sdk/memory";

const langGraphSource = createLangGraphMemorySource({
  store,
  mapNamespace: ({ tenantId, subjectId }) => [
    tenantId,
    subjectId,
    "memory",
  ],
  kind: "document",
});

Choose one graph scope. It maps to one portable kind: edges to edge, nodes to entity, or episodes to episode.

import { createZepMemorySource } from "@praxa/sdk/memory";

const zepSource = createZepMemorySource({
  client: zep,
  scope: "edges",
  mapNamespace: ({ tenantId, subjectId }) => ({
    graphId: `${tenantId}:${subjectId}`,
  }),
});

Graphiti uses an injected transport so your application owns the exact client version and result mapping.

import { createGraphitiMemorySource } from "@praxa/sdk/memory";

const graphitiSource = createGraphitiMemorySource({
  transport: {
    async search({ query, namespace, limit, signal }) {
      return graphitiSearch({ query, groupId: namespace, limit, signal });
    },
  },
  mapNamespace: ({ tenantId, subjectId }) => `${tenantId}:${subjectId}`,
  retrievalModes: ["graph"],
  supportsAbort: true,
});

Every returned transport record must already contain sourceRecordId, a Graphiti-compatible kind, and non-empty text. Provenance is retained when your transport supplies it.

The adapter reads named blocks and recent messages. It does not expose a general archival-memory search API.

import { createLettaMemorySource } from "@praxa/sdk/memory";

const lettaSource = createLettaMemorySource({
  client: letta,
  include: "both",
  mapNamespace: ({ tenantId, subjectId }) => ({
    agentId: lookupLettaAgent(tenantId, subjectId),
    blockLabels: ["persona", "human"],
  }),
});

The adapter reads official message items from the session resolved for the subject. It ranks the recent window newest first.

import { createOpenAIAgentsSessionSource } from "@praxa/sdk/memory";

const openaiSource = createOpenAIAgentsSessionSource({
  sessionForNamespace: ({ tenantId, subjectId }) =>
    sessions.get(`${tenantId}:${subjectId}`),
});

3. Combine the sources

import { MemoryFederation } from "@praxa/sdk/memory";

const memory = new MemoryFederation({
  sources: [mem0Source, langGraphSource, zepSource],
  maxConcurrency: 3,
  maxSources: 8,
  maxResultsPerSource: 50,
  maxTotalResults: 100,
  defaultTimeoutMs: 5_000,
});

const result = await memory.recall({
  query: "What does this customer prefer?",
  namespace: {
    tenantId: "acme",
    subjectId: "customer-42",
    scope: ["support"],
  },
  limit: 10,
});

Inspect both the aggregate and each source:

if (result.status === "failed") {
  throw new Error(JSON.stringify(result.sources));
}

for (const source of result.sources) {
  console.log(source.sourceId, source.status, source.durationMs, source.itemCount);
}

for (const item of result.items) {
  console.log(item.kind, item.text, item.matches.map((match) => match.provider));
}

4. Add a custom source

import type { MemorySource } from "@praxa/sdk/memory";

const customSource: MemorySource = {
  id: "customer-profile",
  provider: "custom",
  capabilities: {
    retrievalModes: ["exact"],
    recordKinds: ["fact"],
    readOnly: true,
    sourceLocalScores: true,
    supportsAbort: true,
    supportsFilter: false,
  },
  async recall({ query, namespace, signal }) {
    signal.throwIfAborted();
    const row = await profiles.find(namespace.tenantId, namespace.subjectId, query);
    return row === null
      ? []
      : [{
          sourceRecordId: row.id,
          kind: "fact",
          text: row.text,
          provenance: {
            origin: "explicit",
            confidence: 1,
            capturedAt: row.updatedAt,
          },
        }];
  },
};

If a custom source includes provenance, provide all required fields. Do not send a partial provenance object and invent missing confidence or timestamps.

5. Test the federation engine

This Vitest test proves success plus explicit partial degradation without calling a real provider:

memory.test.ts

import { describe, expect, it } from "vitest";
import {
  MemoryFederation,
  MemorySourceUnavailableError,
  type MemorySource,
} from "@praxa/sdk/memory";

const capabilities = {
  retrievalModes: ["exact"],
  recordKinds: ["fact"],
  readOnly: true,
  sourceLocalScores: true,
  supportsAbort: true,
  supportsFilter: false,
} as const;

const profile: MemorySource = {
  id: "profile",
  provider: "custom",
  capabilities,
  async recall() {
    return [{
      sourceRecordId: "preference-1",
      kind: "fact",
      text: "Prefers concise answers",
      provenance: {
        origin: "explicit",
        confidence: 1,
        capturedAt: "2026-08-13T12:00:00.000Z",
      },
    }];
  },
};

const archive: MemorySource = {
  id: "archive",
  provider: "custom",
  capabilities,
  async recall() {
    throw new MemorySourceUnavailableError("Archive is offline");
  },
};

describe("memory federation", () => {
  it("returns partial context without hiding the outage", async () => {
    const memory = new MemoryFederation({ sources: [profile, archive] });
    const result = await memory.recall({
      query: "answer style",
      namespace: { tenantId: "acme", subjectId: "person-1" },
    });

    expect(result.status).toBe("partial");
    expect(result.items[0]?.text).toBe("Prefers concise answers");
    expect(result.sources.map(({ sourceId, status }) => ({ sourceId, status })))
      .toEqual([
        { sourceId: "profile", status: "ok" },
        { sourceId: "archive", status: "unavailable" },
      ]);
  });
});

6. Run provider-level canaries

For each real provider, seed data through that provider’s normal write API and then assert:

Subject A retrieves its known record.
Subject B in the same tenant does not retrieve it.
The same subject ID in tenant B does not retrieve it.
Disabling the provider produces the expected source status.
Matching content from two sources retains both source matches.
Contradictory content remains separate.
An abort stops underlying work only when the adapter advertises supportsAbort: true.

The SDK test proves federation behavior. Provider canaries prove that your namespace mapper, client permissions, and provider data layout are correct.

Troubleshooting

Symptom	Resolution
Expected record is absent	Verify provider-native data shape, namespace mapping, filters, and source status.
Another subject sees a record	Stop the rollout and repair server-owned tenant-subject resolution before further tests.
Provider outage looks like no memory	Expose the source status and keep unavailable distinct from an empty successful recall.
Delete did not remove provider data	Use the provider’s lifecycle; read-only federation and hosted-candidate deletion do not erase provider sources.

Best practices

Keep provider writes and lifecycle under the provider’s documented API.
Resolve tenant and subject in trusted backend code and test 2x2 isolation.
Preserve provenance, source matches, contradictions, and per-source status.
Bound concurrency, result count, context bytes, and source timeout.
Never promote checkpoint, hidden, or unverified content into portable recall.

Optimize for production

Query only providers and record kinds relevant to the current purpose.
Use bounded parallel recall and give each source an explicit timeout budget.
Deduplicate normalized content while retaining every source match and contradiction.
Measure source p50/p95 latency, partial/failed recalls, result precision, context bytes, and isolation failures.

Optimize only after the correctness and isolation matrix passes. Lower latency or cost is not an improvement if verified outcomes, authority checks, or recovery rates regress.

Cleanup and next steps

Delete synthetic provider records using the provider’s normal API.
Hard-erase disposable hosted candidates and verify content-free receipts when used.
Revoke test credentials and remove namespace fixtures for every tenant and subject.
Retain only non-content source statuses, identifiers, and test results required for audit.

After cleanup, run the shared integration test matrix and record any environment-specific check that remains pending.

Frequently asked questions

What proves this tutorial works?

The minimum observable result is that federated recall preserves source status, provenance, contradictions, bounds, and isolation. A compile, package import, mocked response, or initial admission alone does not prove the complete workflow.

Can a browser, mobile app, or model prompt hold the credential?

No. Provider clients and Praxa credentials stay in the backend; adapters receive clients, not raw credentials.

How should an ambiguous mutation be retried?

Persist the exact logical input and idempotency key before the first attempt. Reconcile through authoritative readback or replay the exact request with that same key before creating new work.

What should we monitor after release?

Monitor per-source latency/status, partial and failed recall rates, result precision, context bytes, provenance coverage, and isolation failures. Alert on authorization bypass, cross-tenant disclosure, repeated conflicts, or cleanup failure.

Get started

Core Concepts

Releases

Federate and test existing memory

Prerequisites

1. Install the package

2. Create a source

3. Combine the sources

4. Add a custom source

5. Test the federation engine

6. Run provider-level canaries

Troubleshooting

Best practices

Optimize for production

Cleanup and next steps

Frequently asked questions

What proves this tutorial works?

Can a browser, mobile app, or model prompt hold the credential?

How should an ambiguous mutation be retried?

What should we monitor after release?

​Prerequisites

​1. Install the package

​2. Create a source

​3. Combine the sources

​4. Add a custom source

​5. Test the federation engine

​6. Run provider-level canaries

​Troubleshooting

​Best practices

​Optimize for production

​Cleanup and next steps

​Frequently asked questions

​What proves this tutorial works?

​Can a browser, mobile app, or model prompt hold the credential?

​How should an ambiguous mutation be retried?

​What should we monitor after release?

Prerequisites

1. Install the package

2. Create a source

3. Combine the sources

4. Add a custom source

5. Test the federation engine

6. Run provider-level canaries

Troubleshooting

Best practices

Optimize for production

Cleanup and next steps

Frequently asked questions

What proves this tutorial works?

Can a browser, mobile app, or model prompt hold the credential?

How should an ambiguous mutation be retried?

What should we monitor after release?