TypeScript SDK

import { MembraneClient, Sensitivity } from "@gustycube/membrane";

const client = new MembraneClient("localhost:9090", {
  apiKey: "your-api-key"
});

const record = await client.ingestEvent("file_edit", "src/main.ts", {
  summary: "Refactored auth middleware",
  sensitivity: Sensitivity.LOW,
  tags: ["auth", "typescript"]
});

const records = await client.retrieve("debug auth", {
  trust: {
    max_sensitivity: Sensitivity.MEDIUM,
    authenticated: true,
    actor_id: "agent-1",
    scopes: []
  },
  limit: 10
});

console.log(record.id, records.length);
client.close();

new MembraneClient(addr?: string, options?: MembraneClientOptions)

const client = new MembraneClient("membrane.example.com:443", {
  tls: true,
  tlsCaCertPath: "/path/to/ca.pem",
  apiKey: "your-api-key",
  timeoutMs: 10_000
});

async ingestEvent(
  eventKind: string,
  ref: string,
  options?: IngestEventOptions
): Promise<MemoryRecord>

const record = await client.ingestEvent("tool_call", "task#1", {
  summary: "Ran database migration successfully",
  tags: ["db", "migration"]
});

async ingestToolOutput(
  toolName: string,
  options?: IngestToolOutputOptions
): Promise<MemoryRecord>

const record = await client.ingestToolOutput("run_tests", {
  args: { suite: "auth" },
  result: { passed: 42, failed: 0 },
  tags: ["tests", "auth"]
});

async ingestObservation(
  subject: string,
  predicate: string,
  obj: unknown,
  options?: IngestObservationOptions
): Promise<MemoryRecord>

const record = await client.ingestObservation(
  "user",
  "prefers",
  { language: "TypeScript" },
  { sensitivity: Sensitivity.LOW, tags: ["preferences"] }
);

async ingestOutcome(
  targetRecordId: string,
  outcomeStatus: OutcomeStatus | string,
  options?: IngestOutcomeOptions
): Promise<MemoryRecord>

import { OutcomeStatus } from "@gustycube/membrane";

await client.ingestOutcome(record.id, OutcomeStatus.SUCCESS);

async ingestWorkingState(
  threadId: string,
  state: string,
  options?: IngestWorkingStateOptions
): Promise<MemoryRecord>

import { TaskState } from "@gustycube/membrane";

await client.ingestWorkingState("session-001", TaskState.EXECUTING, {
  nextActions: ["run tests", "deploy"],
  contextSummary: "Backend initialized, frontend pending"
});

async retrieve(
  taskDescriptor: string,
  options?: RetrieveOptions
): Promise<MemoryRecord[]>

const records = await client.retrieve("database operations", {
  trust: {
    max_sensitivity: Sensitivity.MEDIUM,
    authenticated: true,
    actor_id: "ts-agent",
    scopes: []
  },
  memoryTypes: ["semantic", "competence"],
  limit: 5
});

async retrieveWithSelection(
  taskDescriptor: string,
  options?: RetrieveOptions
): Promise<RetrieveResult>

interface RetrieveResult {
  records: MemoryRecord[];
  selection?: SelectionResult;
}

interface SelectionResult {
  selected: MemoryRecord[];
  confidence: number;
  needs_more: boolean;
}

const result = await client.retrieveWithSelection("fix build error", {
  trust: { max_sensitivity: Sensitivity.HIGH, authenticated: true, actor_id: "ci", scopes: [] },
  memoryTypes: ["competence", "episodic"]
});
console.log(result.records.length, result.selection?.confidence);

async retrieveById(
  recordId: string,
  options?: { trust?: TrustContext }
): Promise<MemoryRecord>

const record = await client.retrieveById("rec-uuid-here", {
  trust: { max_sensitivity: Sensitivity.MEDIUM, authenticated: true, actor_id: "agent", scopes: [] }
});

async supersede(
  oldId: string,
  newRecord: MemoryRecord | JsonObject,
  actor: string,
  rationale: string
): Promise<MemoryRecord>

const updated = await client.supersede(
  oldRecord.id,
  { ...oldRecord, payload: { ...oldRecord.payload, version: "2.0" } },
  "agent-1",
  "Updated version field"
);

async fork(
  sourceId: string,
  forkedRecord: MemoryRecord | JsonObject,
  actor: string,
  rationale: string
): Promise<MemoryRecord>

const variant = await client.fork(
  sourceRecord.id,
  { ...sourceRecord, scope: "dev" },
  "agent-1",
  "Different behavior for dev environment"
);

async retract(
  recordId: string,
  actor: string,
  rationale: string
): Promise<void>

await client.retract(record.id, "agent-1", "No longer accurate");

async merge(
  recordIds: string[],
  mergedRecord: MemoryRecord | JsonObject,
  actor: string,
  rationale: string
): Promise<MemoryRecord>

const merged = await client.merge(
  [id1, id2, id3],
  { type: "semantic", payload: { fact: "combined knowledge" } },
  "agent-1",
  "Consolidating duplicate semantic records"
);

async contest(
  recordId: string,
  contestingRef: string,
  actor: string,
  rationale: string
): Promise<void>

await client.contest(
  record.id,
  conflictingRecord.id,
  "agent-1",
  "New evidence contradicts this"
);

async reinforce(
  recordId: string,
  actor: string,
  rationale: string
): Promise<void>

await client.reinforce(record.id, "agent-1", "Used successfully in task");

async penalize(
  recordId: string,
  amount: number,
  actor: string,
  rationale: string
): Promise<void>

await client.penalize(record.id, 0.2, "agent-1", "Led to incorrect result");

async getMetrics(): Promise<JsonObject>

const metrics = await client.getMetrics();
console.log(metrics.total_records, metrics.avg_salience);

client.close(): void

interface TrustContext {
  max_sensitivity: Sensitivity | string; // highest sensitivity the caller may access
  authenticated: boolean;               // whether the caller is authenticated
  actor_id: string;                     // identifier of the calling actor
  scopes: string[];                     // optional scope constraints
}

interface MemoryRecord {
  id: string;
  type: MemoryType | string;           // "episodic" | "working" | "semantic" | "competence" | "plan_graph"
  sensitivity: Sensitivity | string;
  confidence: number;                  // 0–1 applicability score
  salience: number;                    // 0–1 current importance score
  scope?: string;
  tags?: string[];
  created_at?: string;
  updated_at?: string;
  lifecycle?: Lifecycle;
  provenance?: Provenance;
  relations?: Relation[];
  payload?: unknown;                   // type-specific structured payload
  audit_log?: AuditEntry[];
}

import { MembraneClient, MembraneError } from "@gustycube/membrane";

try {
  const record = await client.retrieveById("nonexistent-id");
} catch (err) {
  if (err instanceof MembraneError) {
    console.error(err.code);      // numeric gRPC status code
    console.error(err.codeName); // e.g. "NOT_FOUND", "UNAUTHENTICATED"
    console.error(err.details);  // gRPC details string
    console.error(err.metadata); // response metadata as string arrays
  }
}

import OpenAI from "openai";
import { MembraneClient, Sensitivity } from "@gustycube/membrane";

const memory = new MembraneClient("localhost:9090", {
  apiKey: process.env.MEMBRANE_API_KEY
});

const llm = new OpenAI({
  apiKey: process.env.LLM_API_KEY,
  // For OpenRouter or other OpenAI-compatible providers:
  // baseURL: "https://openrouter.ai/api/v1",
});

const records = await memory.retrieve("how should I handle this incident?", {
  trust: {
    max_sensitivity: Sensitivity.MEDIUM,
    authenticated: true,
    actor_id: "incident-agent",
    scopes: ["prod"],
  },
  memoryTypes: ["semantic", "competence", "working"],
  limit: 10,
});

const memoryContext = records.map((r) => JSON.stringify(r)).join("\n");

const completion = await llm.chat.completions.create({
  model: "gpt-5.2",
  messages: [
    { role: "system", content: "Use the memory context as evidence. Cite record ids." },
    { role: "user", content: `Incident task:\n...\n\nMemory:\n${memoryContext}` },
  ],
});

console.log(completion.choices[0]?.message?.content);
memory.close();