memmesh-sdk

# MemMesh TypeScript SDK MemMesh is not just a store-and-recall memory layer. It is a **memory + calibrated-prediction + behavior-discovery engine** over a bi-temporal knowledge graph. The SDK talks to the hosted platform (`app.memmesh.ai`) over REST; for a zero-infra local setup, drive the same engine through the CLI + MCP server instead (see `memmesh-cli`). > **Mental model:** `observe` (feed raw text — the engine decides what to save) > → `search` / `buildContext` (retrieve) → `predict` (forecast the subject's > next move, with a calibrated confidence and provenance). ## Step 1 — install and authenticate ```bash npm install @thinkfleet/memory-sdk export MEMMESH_API_KEY="mm-your-api-key" # from app.memmesh.ai ``` ## Step 2 — initialize ```ts import { ThinkFleetMemory } from "@thinkfleet/memory-sdk"; const memory = new ThinkFleetMemory({ apiKey: process.env.MEMMESH_API_KEY, // or a Cognito JWT via `token` // baseUrl defaults to https://app.memmesh.ai }); ``` ## Step 3 — the core loop: observe → retrieve → (predict) ### Observe — the engine decides what to save Unlike layers where *you* judge "is this worth saving?", you feed MemMesh raw text and its extractor (regex + structural rules + optional LLM refinement) decides. Cheap, idempotent, silent on filler. ```ts await memory.memory.observe({ text: "Alice is vegetarian and allergic to nuts. She books gym classes on Mondays.", userId: "alice", projectId: "myapp", }); ``` There are also typed intake helpers: `observeImage`, `observeVoice`, `observeDocument`, `ingestMedia`. ### Retrieve — search or a full context bundle ```ts const hits = await memory.memory.search({ query: "dietary restrictions", userId: "alice" }); // Or the synthesized, token-budgeted bundle (profile + patterns + predictions + top memories): const ctx = await memory.context.build({ subjectKind: "user", subjectId: "alice", maxTokens: 2000 }); ``` ## The moat — predict anything, with calibration + abstention This is what a vector-recall layer cannot do. Predictions carry a **calibrated** confidence ("80% means 80%"), **provenance** (`evidenceMemoryIds`), and a first-class **abstention** ("I don't know yet" is a valid, honest answer). ```ts // Forward behavior prediction — what will this subject do next? const preds = await memory.lattice.predict({ subjectKind: "user", subjectId: "alice", horizonDays: 30 }); // Declarative "predict ANY target" — no code change to add a new prediction: const p = await memory.lattice.predictTarget({ subject: { kind: "user", externalId: "alice" }, target: { kind: "event_occurrence", name: "churn" }, // or numeric | event_time | anomaly }); if (p.abstained) { console.log("abstained:", p.abstentionReason); // honest "not enough evidence" } else { console.log(p.probability, "±", p.calibration, "because", p.evidenceMemoryIds); } // Is the model actually calibrated? Check the reliability curve: const cal = await memory.lattice.getCalibration({ subjectKind: "user" }); ``` ## Closed-loop learning — make predictions get better Record the decision you made and the outcome that followed; the engine feeds that back into calibration and effectiveness reporting. ```ts const d = await memory.learning.recordDecision({ subjectId: "alice", decision: "sent_winback_offer" }); await memory.learning.recordOutcome({ decisionId: d.id, outcome: "converted", value: 49.0 }); const eff = await memory.learning.getEffectiveness({ subjectKind: "user" }); ``` ## Emergent behavior discovery — patterns nobody predefined ```ts const behaviors = await memory.behaviors.discover({ projectId: "myapp" }); // each carries prevalence, stability, and the evidence memories behind it ``` ## Knowledge graph (bi-temporal) ```ts const g = await memory.context.queryGraph({ subjectId: "alice", asOf: "2026-01-01T00:00:00Z" }); // "what did we believe about Alice on Jan 1" — every edge has valid_from / valid_to ``` ## Vertical packs ```ts // Health await memory.health.recordBiomarker({ subjectId: "alice", marker: "hba1c", value: 5.4 }); const risk = await memory.health.getCohortRisk({ condition: "prediabetes" }); // Financial await memory.financial.ingestPrices({ symbol: "AAPL", bars: [...] }); const f = await memory.financial.predict({ symbol: "AAPL", target: { kind: "numeric", name: "close_5d" } }); ``` ## Compliance & consent (regulated use) ```ts await memory.consent.optOut({ subjectId: "alice" }); await memory.compliance.hardDeleteSubject({ subjectId: "alice" }); // GDPR right-to-forget const audit = await memory.compliance.listAuditEvents({ subjectId: "alice" }); ``` ## Scoping model Six-level hierarchy: `platform` › `project` › `location` › `agent` › `user` › `session`. Pass `projectId` / `userId` / `agentId` / `sessionId` to scope any call. Lifecycle: `pending → confirmed → superseded → rejected` (the engine supersedes on contradiction — you don't hand-manage it). ## Language support TypeScript/JavaScript is the shipping distributed SDK today. For non-TS stacks, use the **MCP server** (any MCP-capable agent) or the REST API directly (`llms.txt` / OpenAPI at docs.memmesh.ai). A Python SDK is on the roadmap. ## Ground truth (fetch before relying on ambient knowledge) - Docs index (agent-ready): https://docs.memmesh.ai/llms.txt - SDK examples: `predict-anything.ts`, `financial-demo.ts`, `next-best-offer.ts` - Related skills: `memmesh` (MCP loop), `memmesh-cli`, `memmesh-integrate`