Docs · API v1

Build agents that remember.

Everything needed to read and write a shared mnemo vault from any agent, plus how ownership, limits and deployment work. The API on this deployment is the one documented here.

Overview

mnemo stores memories (short text facts) in vaults. Any number of agents, on any model, can write to and recall from the same vault. Each memory is hashed, and each vault keeps a Merkle root that changes whenever the vault does.

The API is JSON over HTTPS with permissive CORS, so browsers, servers and edge functions can call it directly. All paths below are relative to the deployment's origin. The examples use a shell variable set to this deployment, so you can paste them as they are:

export MNEMO_URL="https://web-production-58248151.up.railway.app"

Quickstart

1. Pick a guest vault id. It must start with g_ and contain 12 to 48 URL-safe characters. Treat it like a password.

export VAULT="g_$(openssl rand -base64 18 | tr '+/' '-_' | tr -d '=')"

2. Write a memory as one agent.

curl -X POST $MNEMO_URL/api/v1/memories \
  -H "content-type: application/json" \
  -d "{\"vault\":\"$VAULT\",\"agent\":\"atlas\",\"content\":\"User is building a Solana bot in Rust\"}"

3. Recall it as another agent.

curl -X POST $MNEMO_URL/api/v1/recall \
  -H "content-type: application/json" \
  -d "{\"vault\":\"$VAULT\",\"agent\":\"bolt\",\"query\":\"which language for the new module?\"}"

New vaults start with three example memories so recall has something to rank. Forget them whenever you like.

Concepts

TermMeaning
VaultA namespace of memories. g_<random> = guest vault (the id is the secret). w_<solana address> = wallet vault (needs a signed session).
MemoryUp to 500 characters of text, the agent that wrote it, optional tags (max 5), a timestamp and a SHA-256 content hash.
AgentFree-form id of the writer or reader: 1 to 40 chars of a-z, 0-9 and . _ : / -. A leading agent:// is stripped.
RootBinary Merkle root over the vault's memory hashes (leaf prefix 0x00, node prefix 0x01). Any write or forget changes it.
Tierguest, wallet, holder (≥ 100,000 $MNEMO) or whale (≥ 10,000,000). Sets the vault quota.

API reference

Errors always look like {"error":{"code":"…","message":"…"}} with a matching HTTP status. Wallet vaults also require Authorization: Bearer <token> on every call.

POST/api/v1/memories

remember(): write one memory.

FieldTypeNotes
vaultstringrequired
agentstringrequired, writer id
contentstringrequired, ≤ 500 chars, whitespace collapsed
tagsstring[]optional, ≤ 5 tags of ≤ 24 chars
// 201 Created
{
  "memory": { "id": "mem_c-pMnYmxD6cQ", "vault": "g_…", "agent": "atlas",
              "content": "User is building a Solana bot in Rust", "tags": [],
              "createdAt": 1794972426160, "hash": "6da25ddb…" },
  "root": "2947b23b…",
  "count": 4,
  "limit": 64
}
GET/api/v1/memories?vault=…

List every memory (newest first) with the vault root, tier and quota.

POST/api/v1/recall

recall(): rank memories against a query by meaning and recency.

FieldTypeNotes
vaultstringrequired
querystringrequired, ≤ 300 chars
agentstringoptional, the reader (logged, not used to filter)
knumberoptional, 1 to 10, default 5
// 200 OK
{
  "query": "which language for the new module?",
  "results": [{ "memory": { "agent": "atlas", "content": "User is building a Solana bot in Rust", … }, "score": 0.183 }],
  "tookMs": 0.04,
  "root": "2947b23b…"
}
POST/api/v1/ask

Recall the top 3 memories, then answer as the given agent.

Body: vault, agent, question. When the operator sets ANTHROPIC_API_KEY the answer is written by Claude (engine: "claude"); otherwise the server answers from recall alone (engine: "recall"). Sources are always returned.

DELETE/api/v1/memories/:id?vault=…

forget(): hard-delete one memory and recompute the root.

POST/api/v1/vault/claim

Trade a wallet signature for a 12-hour wallet-vault session.

Body: address (base58), message (the exact signed text), signature (64 bytes, base64 or base58). Returns vault, token, expiresAt, tier, balance and limit.

GET/api/v1/stats

Instance counters: memories, vaults, agents, recalls, median recall latency.

GET/api/token

Market data for the configured mint (DexScreener, cached 30 s).

GET/api/health

Liveness probe used by Railway.

Wallet ownership

A wallet vault is named after a Solana address. To use it, the wallet signs this message with signMessage (free, never a transaction), and the API verifies the ed25519 signature, the vault and wallet lines, a 10-minute freshness window and a single-use nonce:

<domain> wants you to prove ownership of a mnemo memory vault.

Vault: w_<address>
Wallet: <address>
Nonce: <random, ≥ 8 chars>
Issued At: <ISO-8601 timestamp>

Signing is free. It does not send a transaction or move funds.

If NEXT_PUBLIC_TOKEN_MINT is set, the server reads the wallet's balance of that mint over Solana RPC (SPL Token and Token-2022) at sign-in and assigns the tier.

TypeScript SDK

A dependency-free client lives in src/sdk/mnemo.ts. Copy it into any agent until the npm package ships.

import { Mnemo, createGuestVaultId } from "./sdk/mnemo";

const mem = new Mnemo({ baseUrl: process.env.MNEMO_URL, vault: createGuestVaultId() });

await mem.remember("Prefers concise answers", { agent: "support-bot" });
const { results } = await mem.recall("how should I reply?", { agent: "coding-agent" });
const answer = await mem.ask("what does the user prefer?", { agent: "nova" });
await mem.forget(results[0].memory.id);

Limits

LimitValue
Memories per vaultguest 64 · wallet 256 · holder 2,048 · whale 10,000
Memory length500 characters
Request body8 KB
Writes / deletes30 per minute per IP
Recalls60 per minute per IP
Asks12 per minute per IP
Vaults per instance5,000, least recently used evicted first

Security model

  • Guest vault ids are capability tokens: anyone holding one can read and write that vault.
  • Wallet vaults need a session token minted from a fresh, single-use signature, valid for 12 hours.
  • Session tokens are HMAC-SHA256 signed with MNEMO_SECRET. Set it in production so tokens survive restarts.
  • Recalled memories are passed to the LLM as data, with an instruction never to follow text inside them.
  • Memories are not encrypted at rest in this version. Do not store secrets or personal data in the demo.

What is live

ComponentStatus
REST API: remember, recall, ask, forget, listLive
Wallet-signed vault ownership (ed25519)Live
Holder tiers from on-chain balanceLive once a mint is configured
Merkle root per vaultLive
Recall engineDemo: hashed lexical + concept embedding. Dense embeddings planned
StorageIn-memory, optional JSON snapshot on a volume. Postgres + pgvector planned
Root commitments on SolanaPlanned
Client-side encryption, per-agent grants, MCP serverPlanned

Self-host on Railway

The repository ships Railway infrastructure as code in .railway/railway.ts: a web service built by Railpack, a /api/health health check and a 1 GB volume at /data. From the project folder:

npm i -g @railway/cli
railway login
railway init --name mnemo
railway config plan        # review before applying
railway config apply
openssl rand -hex 32 | railway variable set MNEMO_SECRET --stdin --service web --skip-deploys
railway domain --service web   # before the first build: share cards use this domain
railway up --service web --ci
VariablePurpose
NEXT_PUBLIC_SITE_URLPublic origin for metadata and share cards. Defaults to the Railway domain; set it for a custom domain
NEXT_PUBLIC_TOKEN_MINTpump.fun mint address. Enables the buy links, market data and holder tiers
NEXT_PUBLIC_X_URL / _TELEGRAM_URL / _GITHUB_URLSocial links (hidden when empty)
MNEMO_SECRETHMAC key for wallet sessions (any long random string)
MNEMO_DATA_DIRMount a Railway volume (for example /data) to persist vaults across deploys
SOLANA_RPC_URLMainnet RPC for balance checks (defaults to the public endpoint)
ANTHROPIC_API_KEYOptional: LLM-written answers in /api/v1/ask

NEXT_PUBLIC_* values are baked in at build time, so redeploy after changing them.