Memory API
Select one Space, save a memory, and retrieve bounded context with evidence.
memory.v1 from GET /memory/v1 and an SDK exposing memory(). Check your deployment before switching an integration. Existing graph and ingestion APIs remain available.Choose a Space
This client selects one Space within your credential's existing access. A Space is a visibility boundary; a Project narrows reads to its source documents. Selecting either does not grant access. Organization routing still comes from your credential and organization header.
Remember and retrieve
import { MindGraph } from "mindgraph";
const client = new MindGraph({ baseUrl: "https://api.mindgraph.cloud", apiKey: process.env.MINDGRAPH_API_KEY });
if (!(await client.contracts()).contracts.includes("memory.v1")) throw new Error("memory.v1 unavailable");
const memory = client.memory({ space_uid: "space:project:alpha" });
const saved = await memory.remember("Use the staging cluster", { custom_id: "deploy-target" });
console.log(saved.uid, saved.searchable);
const context = await memory.context({ query: "Which cluster should I use?", format: "text", max_tokens: 1000 });
console.log(context.context_text, context.budget);
A successful save reports lexical and vector readiness separately. Vector search may be unavailable while lexical search is ready. An unrestricted credential can create a named Space's first memory; a restricted credential needs existing write access. Source-restricted credentials use authorized document ingestion instead.
Start a session with a profile
A profile reads current stored memories, preferences, lessons, active goals and open decisions without a query or generated biography. Named Spaces normally contain direct memories; typed and extracted knowledge lives in the organization Space.
const local = await memory.profile({ format: "text" });
// Usually memories plus four empty sections in a named Space.
const shared = await memory.profile({ include_org_space: true, format: "text" });
// Includes permitted organization knowledge; each item names its Space.
console.log(shared.complete, shared.omitted, shared.unavailable);
// Optional Project selection intersects both Spaces with Project source membership:
const project = await memory.profile({ project_uid: "project:alpha", include_org_space: true });
Inspect completeness before treating a profile as exhaustive. A section with more than 5,000 eligible items is unavailable; narrow it with a filter or omit that section. Other sections may also have omissions. Empty results are successful reads; authorization and resource failures are errors. Conflicting facts retain their caveats.
Inspect and filter
const page = await memory.list({ limit: 20, node_filter: {
op: "and", operands: [
{ field: "node_type", op: "eq", value: "Observation" },
{ field: "salience", op: "gte", value: 0.5 },
],
} });
// Reuse the same Space, Project and filter with page.next_cursor.
console.log(page.items, page.next_cursor);
Items use stable UID order, which is not chronological. Filter on created_at for a recent window. A cursor is bound to its Space, Project and filter; results reflect live changes between pages. Filters select primary nodes before ranking. In filtered context requests, article, chunk and ontology legs default off; explicitly enabling them is rejected.
Preview and forget
const preview = await memory.forget({ custom_id: "deploy-target" }, { dry_run: true });
console.log(preview.uid, preview.label, preview.edges_tombstoned);
const receipt = await memory.forget({ custom_id: "deploy-target" });
console.log(receipt.action, receipt.undo);
Forget tombstones one memory and leaves connected edges unchanged. Provide exactly one UID or custom ID. Cascade is unsupported. Preview does not reserve the target; a changed target may require inspection before retrying. Restore remains available through the advanced evolve API.
Keys, compatibility and errors
A custom ID names a memory within one Space. Keys written through the legacy /memory/remember route belong to a separate organization-wide set. Switching routes and reusing a legacy key creates a second memory; use the existing UID to inspect or forget that legacy memory. The SDK never silently retries a scoped operation through a legacy route.
Preserve typed errors such as scope_not_found, invalid_filter, invalid_cursor and profile_too_large. Missing capability is different from an inaccessible memory. A retry hint does not make an uncertain write safe to replay.
Download the OpenAPI 3.1 subset: the five memory POST operations and capability read. It does not describe the complete advanced API or document readiness.