Memory
Point the client, memory happens. Pin when you care. Same Strix key for chat and MCP.
The idea
Strix memory is gateway-native. You point Cursor, Claude Code, Codex, or any OpenAI-compatible client at https://api.strixgate.dev/v1 with a strix_… key. Completions extract short facts, embed them, and inject a recall block on later turns. There is no Python/JS memory SDK and no Notion connector.
Pin when you care. Silent derive is the default.
How to use it
- Point the client. Pick
strix-auto(or another public id). - Keep working. After a few turns, derived facts show in Dashboard → Memory.
- Optional: send
x-strix-project(or we infer git remote / workspace). With Share memory across all coding agents on (the default), recall isall-agents+ this project +default, deduplicated. - Optional: pin a fact from the dashboard or MCP
memory_add.
A completion may include x-strix-memory-hits. Treat it like other x-strix-* headers.
Projects
| Field | Source | Default |
|---|---|---|
project | x-strix-project, or git remote / workspace in the turn, else default | default |
Use the reserved all-agents project for facts that should follow the account
across Cursor, Claude Code, Codex, OpenCode, Cline, Roo Code, Continue, Aider,
and other clients.
Extraction still writes to the inferred project unless the request explicitly
sets x-strix-project: all-agents. Turn cross-agent recall on or off in
Dashboard → Account.
Forget-all stays account-wide. Forget this project tombstones that container and deletes its Vectorize vectors.
Builder includes 5 projects; Team includes 50. Limits apply to explicit pins, not silent derive.
HTTP (same key as chat)
POST /v1/memory—{ content, kind?, importance?, project?, metadata?, categories?, ttl_days?, timestamp?, supersedes_id? }pin (verbatim; no deriver)POST /v1/memory/batch—{ facts: [...] }up to 20POST /v1/memory/batch/update—{ updates: [{ fact_id, ...patch }] }up to 100POST /v1/memory/batch/delete—{ fact_ids: [...] }up to 100GET /v1/memory—?project=&kind=&category=&metadata=&filter=&created_after=&created_before=&updated_after=&updated_before=&expires_after=&expires_before=×tamp_after=×tamp_before=&latest_only=&cursor=&limit=GET /v1/memory/events— recent add, update, delete, and search events; optionalprojectandlimitGET /v1/memory/:id— one fact + provenance (source_event_ids)GET /v1/memory/:id/historyPOST /v1/memory/:id/feedback—{ value: "up" | "down" | "clear" }PATCH /v1/memory/:id—{ content?, importance?, metadata?, categories?, ttl_days?, expires_at?, timestamp?, supersedes_id? }DELETE /v1/memory/:idPOST /v1/memory/recall—{ query, project?, kind?, category?, metadata?, filter?, created_after?, created_before?, updated_after?, updated_before?, expires_after?, expires_before?, timestamp_after?, timestamp_before?, latest_only?, limit?, threshold?, rerank?, decay? }GET/POST /v1/memory/settings—enabled,retention_days,extract_instructions,webhook_url,webhook_secret,category_catalog,decay_enabled,share_across_agentsPOST /v1/memory/exportPOST /v1/memory/forget— omit body for account-wide;{ "project": "…" }for one project
extract_instructions is one account-level textarea prepended to the deriver. Not a dual user/agent instruction API.
Dates use ISO 8601 everywhere. timestamp is when the event happened; created_at remains when Strix stored it. Existing facts use created_at as their timestamp. ttl_days accepts 1–3650 days. Expired facts stop appearing in list and recall before cleanup tombstones them.
filter is a JSON object with a maximum nesting depth of four. Combine leaves with and, or, and not. Leaves support kind, category_in, category_contains, metadata.eq, metadata.ne, metadata.contains, and date ranges on created_*, updated_*, expires_*, and timestamp_*. List and recall exclude superseded facts by default; pass latest_only=false to list historical superseded rows.
Use optional session metadata when one project has several distinct work
threads. It remains ordinary, filterable metadata—not a second tenant or
identity axis. The dashboard exposes a Session shortcut while keeping the full
metadata filter available.
Recall reranks by default. Set rerank: false to skip the external reranker, threshold from 0–1 to drop weak results, and decay: true to mildly favor recently useful facts and damp stale ones. Account-level decay_enabled supplies the default and is off initially.
Configure the HTTPS mutation webhook in Dashboard → Account. memory_add, memory_update, and memory_delete are delivered after successful writes without holding the API response open. Verify the hexadecimal SHA-256 HMAC in x-strix-signature against the exact request body. Secrets must be 16–200 characters and are never returned after saving.
The dashboard exposes the same primitives, split by scope:
- Dashboard → Memory is the per-project ledger: combine project, kind, category, metadata, and date filters; tune recall threshold/reranking; pin event time; edit categories/metadata; select facts for batch update/delete; inspect activity; and Forget this project.
- Dashboard → Account owns account controls: turn memory on/off, save
extract_instructions, configure webhooks and the category catalog, opt into decay, Export JSON, and Forget everything.
MCP (optional)
Same Worker, same key:
{
"mcpServers": {
"strix-memory": {
"url": "https://api.strixgate.dev/mcp",
"headers": {
"Authorization": "Bearer strix_…"
}
}
}
}OAuth-capable MCP clients can instead configure only
https://api.strixgate.dev/mcp. The Worker advertises OAuth 2.1 metadata,
requires PKCE S256, sends you to the existing Strix sign-in and consent screen,
and issues short-lived, refresh-rotated tokens. Choose read-only
memory.read or read/write memory.read memory.write access. Connected clients
can be revoked from Dashboard → Account.
Native tools: memory_search, memory_add, memory_add_batch, memory_list,
memory_get, memory_update, memory_batch_update, memory_batch_delete,
memory_delete, memory_list_events, memory_get_event,
memory_forget_project, memory_history, memory_feedback.
Compatibility aliases: add_memory, search_memories, get_memories,
get_memory, update_memory, delete_memory, delete_all_memories,
list_events, get_event_status. Identity-shaped fields (user_id,
agent_id, app_id, run_id) are rejected: the API key or OAuth grant is the
tenant and project is the only extra axis. add_memory requires
infer: false; automatic extraction belongs to routed chat.
Read-scoped keys and OAuth grants with only memory.read can search, list,
inspect activity, and read history; write access is required to mutate memory.
Users who never enable MCP still get silent inject.
CLI
The Bun CLI covers the same fact lifecycle as the dashboard and HTTP API:
export STRIX_API_KEY="strix_…"
bun run --cwd apps/worker memory -- list --project model-router
bun run --cwd apps/worker memory -- search "Which package manager?" --project model-router
bun run --cwd apps/worker memory -- pin "Use Bun for this repo" --project model-router --kind instruction --session qa
bun run --cwd apps/worker memory -- get mf_…
bun run --cwd apps/worker memory -- patch mf_… --importance 0.9 --category tooling
bun run --cwd apps/worker memory -- delete mf_… --yes
bun run --cwd apps/worker memory -- forget-project old-project --yesSTRIX_BASE_URL defaults to https://api.strixgate.dev. Keys are accepted
from the environment only and are never printed. Destructive commands require
--yes; omit it to get help without changing anything.
Gateway-native memory
Strix is the router you already call, so memory follows the API key. You do not need a second client call, hosted service, or set of credentials for each turn.
Security
- Every D1 and Vectorize read is scoped to the authenticated
user_id. - Event payloads store role only (not tool args or full messages).
- Vectorize metadata is tenant filters (
userId,project_key,kind,factId) — not fact text. Metadata is flat primitives only. - Recall hydrates fact text from D1 after the Vectorize filter.
- History, forget, and purge stay user-scoped. GDPR forget deletes history too.
- MCP accepts a
strix_key or OAuth 2.1 access token. Read-scoped credentials cannot mutate.
Capabilities and boundaries
This is the product contract for gateway-native memory.
| Strix ships | How |
|---|---|
| Silent extract + inject | Every public model on the same strix_ key |
| Project scopes | x-strix-project or inferred git/workspace + default |
| Pin / list / rich patch / delete | Dashboard, HTTP, MCP |
| Batch update / delete | Up to 100 facts per mutation |
| Search (recall) | Vector + lexical + optional rerank, threshold, decay |
| History + feedback | Per-fact audit and helpful/not |
| Rich filters | AND / OR / NOT, dates, category, metadata operators |
| Event time + expiration | Optional timestamp, TTL, or expires_at |
| Supersession | Latest-only by default; history remains available |
| Activity feed | Recent project add, update, delete, and search events |
| Signed webhooks | Account-level HTTPS target in Account |
| Category catalog | Account defaults plus freeform fact labels |
| Batch pin | Up to 20 verbatim facts from the dashboard or API |
| Cross-agent recall | Optional all-agents scope across coding clients |
| MCP on the Worker | Same key as chat — optional |
| MCP compatibility aliases | Native tools plus common add/search/get/update/delete aliases |
| OAuth for MCP | PKCE S256, scoped grants, refresh rotation, and revocation |
| Forget project / account | Tombstone + Vectorize ids |
| Deliberate non-goals | Why we skip it |
|---|---|
| Entity / knowledge graph | Use a graph store when you need relations |
| Notion / Drive / file connectors | Strix stores short facts, not a corpus |
| Document RAG | Bring your own retrieval layer |
| Python / JS memory SDK | The gateway is the API — HTTP or MCP |
| user_id / agent_id / run_id filters | Tenant is the API key; the extra axis is project |
Memory runs on every public id. See Models and lanes for the catalog and typed-only inventory.
Opt out / GDPR
Dashboard: off, delete one fact, export, forget project, or forget everything. Account delete also purges Vectorize ids. Forget by project_key deletes those vectors.
See privacy and errors and evidence.