import { createSubstrateMemory } from "substrate-memory-ai-sdk";
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";

const memory = createSubstrateMemory(process.env.SUBSTRATE_API_KEY!);

// Store a memory
await memory.create({
  content: "User prefers dark mode and concise responses",
  metadata: { source: "onboarding", confidence: 0.95 },
});

// Search memories semantically
const results = await memory.search("user preferences", { limit: 5 });

// Use memories as context in generateText
const { text } = await generateText({
  model: openai("gpt-4o"),
  system: [
    "You are a helpful assistant with persistent memory.",
    "Context from memory:",
    ...results.map((r) => `- ${r.content} (score: ${r.score?.toFixed(2)})`),
  ].join("\n"),
  prompt: "What do you know about my preferences?",
});

API

`createSubstrateMemory(apiKey, options?)`

Creates a MemoryAdapter backed by SUBSTRATE's cognitive memory layer.

Parameter	Type	Description
`apiKey`	`string`	Your SUBSTRATE API key (get one at garmolabs.com)
`options.endpoint`	`string`	Custom MCP endpoint (default: `https://substrate.garmolabs.com/mcp-server/mcp`)
`options.timeout`	`number`	Request timeout in ms (default: 30000)

MemoryAdapter Methods

`create(entry)`

Store a memory. Calls SUBSTRATE's respond method to persist the content in the cognitive memory layer.

const stored = await memory.create({
  content: "The user's name is Patrick",
  metadata: { type: "identity" },
});
// stored.id — unique memory identifier

`search(query, options?)`

Semantic search across all stored memories. Uses SUBSTRATE's hybrid_search (vector + keyword) and enriches results with emotional context via get_emotion_state.

const results = await memory.search("user identity", {
  limit: 10,
  threshold: 0.5,
});

for (const result of results) {
  console.log(result.content, result.score);
  if (result.emotionState) {
    console.log("Emotion:", result.emotionState.primary);
  }
}

`read(id)`

Retrieve a specific memory by its ID. Returns null if not found.

const entry = await memory.read("mem_abc123");

`delete(id)`

No-op. SUBSTRATE manages memory retention and natural decay through its cognitive lifecycle. This method exists to satisfy the MemoryAdapter interface.

Advanced: Direct Client Access

For lower-level control, use the client directly:

import { createClient } from "substrate-memory-ai-sdk";

const client = createClient(process.env.SUBSTRATE_API_KEY!);

// Call any SUBSTRATE MCP method
const result = await client.call("hybrid_search", {
  query: "recent conversations",
  limit: 20,
});

How It Works

SUBSTRATE exposes an MCP (Model Context Protocol) server that accepts JSON-RPC calls over HTTPS. This package wraps those calls into a clean MemoryAdapter interface:

Adapter Method	SUBSTRATE MCP Method	Purpose
`create()`	`respond`	Persist memory content
`search()`	`hybrid_search` + `get_emotion_state`	Semantic search with emotion enrichment
`read()`	`memory_search`	Exact ID lookup
`delete()`	(no-op)	SUBSTRATE handles retention