XTRACE MEMORY API · @xtraceai/memory
Pulling out facts, storing them and finding them again, all in one service. Nothing to tune and no query language to learn. You scope it by what you send.
INSTALL
npm install @xtraceai/memory
OR IN YOUR AGENT CLIENT
claude mcp add xtrace
THE PRIMITIVES
You don’t pre-classify anything. The server decides.
fact
A single semantic claim
Extracted from a conversation turn. Most ingested memory is facts.
artifact
A structured object
A doc, spec or snippet worth keeping on its own, with its version history.
episode
A session-scoped summary
Covers a stretch of the conversation and sets the time frame for its facts.
WRITE PATH
Ingest is async by default.
Pulling out the facts takes 3 to 10 seconds, so the API hands back a job right away. pollUntilDone handles backoff, or pass wait: true for a 30-second sync window.
messages
the conversation turns
user_id
keys the per-user namespace
conv_id
anchors memories for replay and retract
group_ids
optional: tag into shared groups
POST /v1/memories
const job = await client.memories.ingest({
messages: [
{ role: 'user', content: 'We renew Nimbus in Q3.' },
{ role: 'assistant', content: 'Noted.' },
],
user_id: 'alice',
conv_id: 'conv_2026_08_01',
group_ids: [team.id],
});
const done = await client.memories
.jobs.pollUntilDone(job.id);
done.result.memories_created;
// [ { id, type: 'fact', text }, … ]READ PATH
// scope by what you send; each one narrows the search
await client.memories.search({
query: 'how do we quote a renewal?',
user_id: 'alice',
agent_id: 'planner',
});
// personal + shared, one injectable block
const { prompt } = await client.memories.recall({
query: 'what should we send the customer?',
pools: [
{ user_id: 'alice' },
{ group_ids: [team.id] },
],
});READ PATH
No filter DSL. Scope by what you pass.
Pass any combination of user_id, group_ids, agent_id, app_id. Each one narrows the search. Leave one out and it stays open. Your org always comes from the key.
mode: 'retrieve'
Raw ranked results. Cheaper, no extra model call.
mode: 'compose'
A picked set of results, put together as a block you can drop into a prompt.
SHARING & PRIVACY
Groups share memory across users. The personal gate keeps the rest out.
Give a group a prompt and only matching memories go in. Leave the prompt out and it takes everything shareable. Either way, anything personal stays out, and when it isn’t sure it keeps things private.
Prompted group
A focused slice on one topic. The prompt tells it what belongs there.
Catch-all group
A shared bucket for the whole workspace. Everything shareable lands in it, on purpose.
The personal gate
Private notes stay with the person who wrote them. They can still find them, and no one else can.
WORKS WITH YOUR STACK
Four lines in the agent loop. No framework to adopt.
Recall before the model call, ingest after it. That is the whole integration, and it is the same two calls whichever runtime you build on.
Vercel AI SDK
Pydantic AI
LangChain
OpenAI Agents SDK
Claude Agent SDK
MCP
CLI
PROCEDURAL MEMORY
Not just what is true. What to do about it.
Most memory layers store facts. XTrace also stores the sequence that worked — the steps, the order, the dead ends already ruled out — so the next run starts from a procedure instead of a blank prompt.
fact
a single claim, with its source
artifact
a spec or doc, versioned and diffable
episode
the run that produced them
RETRIEVAL VS. A FILE SYSTEM
Markdown files do not scale past one repo.
A folder of notes has no ranking, no scoping and no way to retire a claim that is no longer true. Memory that agents can actually rely on needs all three.
Grep a folder
Ranked by relevance
One shared blob
Scoped per user, agent, group
Stale lines linger
Superseded claims retire
IN YOUR TERMINAL
MCP, plugins and skills. Memory where your agents already run.
Claude Code & Codex plugin
Sessions are saved when they end and on every commit and PR, so other sessions see new decisions within minutes. Only what changed gets processed.
/plugin marketplace add XTraceAI/memhub-claude-plugin /plugin install memhub@memhub
Skills your agent can call
You or your agent can call any of them. Say it in plain language and the right one runs.
/memhub:search-memory
/memhub:spec
/memhub:handoff-session
/memhub:save-artifact
/memhub:import-session
A quickstart, the API reference and a TypeScript SDK built from the live spec.