Docs/Memory API

Reference

Memory API

REST API reference for reading and writing to the MNEMOS memory layer from external applications.

Base URL: https://mnemosbase.com

Authentication

Wallet signature — write operations

All mutation endpoints require proof of wallet ownership. Sign a canonical message and include the auth payload in the request body:

typescript

// Canonical message format
const timestamp = Date.now()
const message = `mnemos:${action}:${walletAddress}:${timestamp}`
const signature = await wallet.signMessage(message)

// Include in every mutation body:
{
  walletAddress: "0x...",
  timestamp:     1234567890,
  signature:     "0x..."
}

// Actions by endpoint:
// POST /api/memory           → "create-memory"
// DELETE /api/vault/session  → "revoke-session"
// POST /api/vault/apikey     → "generate-api-key"

WARNING

Signatures are valid for 5 minutes from the timestamp. Replay attacks outside this window return 401.

Bearer API key — read operations and ingest

http

Authorization: Bearer YOUR_API_KEY

Endpoints

POST/api/ingest/:apiKey

Ingest a plaintext memory from any external source. Identified by API key in the URL — no Authorization header needed. Memories are stored as api-plain source (not encrypted).

WARNING

Do not ingest sensitive content through this endpoint. Memories are stored as readable plaintext in Neon Postgres.

Request body

json

{
  "note":     "Completed Q2 revenue review with the team",
  "source":   "notion",
  "category": "context",
  "tags":     ["work", "finance", "q2"]
}

Property	Type	Required	Description
note	string	yes	Memory content (max 10,000 chars)
source	string	no	Origin label e.g. "notion", "zapier"
category	string	no	Memory category — defaults to "api"
tags	string[]	no	Array of tag strings

Response

json

{ "success": true, "id": "mem_abc123", "createdAt": "2026-03-17T10:00:00Z" }

GET/api/vault/query

Query memories accessible via API key — includes api-plain memories and the active MCP session cache.

Query parameters

Property	Type	Required	Description
q	string	no	Semantic search query
category	string	no	Filter by category
limit	number	no	Max results (default 20, max 100)
source	string	no	Filter by source e.g. "api-plain", "mcp"

http

GET /api/vault/query?q=health+goals&category=health&limit=10
Authorization: Bearer YOUR_API_KEY

Response

json

{
  "memories": [
    {
      "id":        "mem_abc123",
      "note":      "Logged 8.5 hours sleep — feeling strong",
      "category":  "health",
      "tags":      ["sleep", "energy"],
      "source":    "api-plain",
      "createdAt": "2026-03-17T10:00:00Z"
    }
  ],
  "count": 1
}

POST/api/vault/session

Sync wallet-decrypted memories into the AI Vault Bridge session cache so MCP tools can recall them. Requires wallet signature.

Request body

json

{
  "walletAddress": "0x...",
  "timestamp": 1234567890,
  "signature": "0x...",
  "memories": [
    {
      "id":       "mem_abc123",
      "content":  "Decrypted memory content",
      "category": "goal",
      "tags":     ["finance"]
    }
  ]
}

NOTE

Limits: max 500 memories per session, max 10,000 chars per memory. Session TTL: 60 minutes.

Response

json

{ "success": true, "count": 42, "expiresAt": "2026-03-17T11:00:00Z" }

DELETE/api/vault/session

Immediately revoke the active AI Vault Bridge session. Clears the session cache instantly — Claude loses access to wallet-encrypted memories.

typescript

const timestamp = Date.now()
const message = `mnemos:revoke-session:${walletAddress}:${timestamp}`
const signature = await wallet.signMessage(message)

await fetch("/api/vault/session", {
  method: "DELETE",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ walletAddress, timestamp, signature }),
})

POST/api/vault/apikey

Generate a new API key for your vault. The raw key is returned once — MNEMOS stores only the SHA-256 hash.

Response

json

{ "key": "mnemos_live_abc123...", "createdAt": "2026-03-17T10:00:00Z" }

Shared vault endpoints

POST/api/vault/shared

Create a new shared vault. Returns the vault object with the owner as first member.

GET/api/vault/shared

List all shared vaults the connected wallet belongs to.

POST/api/vault/shared/:id/invite

Invite another wallet to a shared vault. Wraps the vault key for the invitee using ECDH.

POST/api/vault/shared/:id/accept

Accept a vault invite. Stores the unwrapped vault key for future use.

POST/api/vault/shared/:id/memories

Write a memory to a shared vault (encrypted with the vault key, not the wallet key).

GET/api/vault/shared/:id/memories

List all memories in a shared vault. Returns ciphertext for client-side decryption.

Error codes

Code	Meaning
400	Bad request — missing or invalid fields
401	Unauthorized — invalid, expired, or missing signature/API key
403	Forbidden — valid auth but insufficient permissions (e.g. viewer trying to write)
404	Memory or resource not found
429	Rate limit exceeded
500	Internal server error

←

SDK Reference