Developer Guide

Introduction

Beyond the MCP tools your AI assistant uses, JauMemory exposes a REST API you can call from any backend, script, or service. Use it as instant persistent storage for your own projects: store JSON-tagged notes, events, and documents, and get hybrid keyword + semantic search back without running a database.

• Zero infrastructure: no database to host, no schema migrations. POST content, search it back.
• Automatic classification: memories are typed (error / solution / insight / question / context / task) and importance-scored server-side if you don't set those fields.
• Real search: keyword, semantic, or hybrid, computed on JauMemory's own servers. Your content never touches a third-party AI API.
• Shared with your AI: everything your app stores over REST is the same memory pool your connected AI assistants read via MCP, and vice versa.

Base URLs

https://mem.jau.app/v1     # REST API (this page)
mem.jau.app:50051          # gRPC over TLS (used by the MCP server)

All REST endpoints below are relative to https://mem.jau.app/v1. All traffic is HTTPS.

Authentication: Bearer Tokens

The memory endpoints authenticate with a JWT access token in the Authorization header. You get one by logging in with your account credentials (accounts are invite-only during the beta · request an invite):

POST /v1/auth/login
Content-Type: application/json

{
  "email": "you@example.com",
  "password": "your-password",
  "mfa_code": "123456"        // only if you enabled TOTP 2FA
}

Response (fields abridged):

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "requires_mfa": false,
  "username": "you"
}

Then send the token on every request:

Authorization: Bearer eyJhbGciOi...

Access tokens are short-lived. Exchange the refresh token at POST /v1/auth/refresh when you get a 401, rather than storing the password. Treat both tokens as secrets: server-side code only, never in client-side JavaScript shipped to browsers you don't control.

Authentication: API Keys

JauMemory also has account-scoped API keys, managed over REST:

Keys look like jm_ followed by 32 random characters, are hashed with Argon2id server-side (the plaintext is never stored), and are sent in an X-API-Key header.

Memory Endpoints

Consolidation (merging similar memories into insights) is not available over REST; it runs through the MCP consolidate tool.

The Memory Object

Create request fields:

{
  "content": "string",        // required, 1 to 50,000 characters
  "context": "string",        // optional free-text context
  "memory_type": "task",      // optional: error | solution | insight | question | context | task
                              //   (auto-classified from content if omitted)
  "importance": 0.8,          // optional 0.0-1.0 (auto-scored if omitted)
  "tags": ["project-x"],      // optional, up to 20 tags
  "metadata": { "any": "json" } // optional arbitrary JSON
}

What you get back everywhere:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "content": "…",
  "context": "…",
  "importance": 0.8,
  "memory_type": "task",
  "tags": ["project-x"],
  "metadata": { "any": "json" },
  "created_at": "2026-07-06T18:30:00Z",
  "updated_at": "2026-07-06T18:30:00Z"
}

Search

POST /v1/memories/search
Content-Type: application/json

{
  "query": "database timeout",   // optional: omit for a filters-only search
  "mode": "hybrid",              // keyword | semantic | hybrid
  "limit": 10,                   // 1-100
  "min_similarity": 0.5,         // optional semantic threshold, 0.0-1.0
  "filters": {                   // all optional
    "memory_types": ["error", "solution"],
    "tags": ["project-x"],
    "importance_min": 0.5,
    "importance_max": 1.0,
    "date_range": {
      "start": "2026-06-01T00:00:00Z",
      "end": "2026-07-01T00:00:00Z"
    }
  }
}

The response is a plain array of memory objects, best matches first. (Relevance scores and matched-term details are exposed on the gRPC/MCP surface only; the HTTP contract stays thin.)

Credential Vault

Store an API key once, encrypted; your tools, skills, and agents then use it by reference without ever seeing the plaintext again. The vault is what lets a scheduled skill call a third-party API on your behalf while the secret never appears in a chat, a log, or a response body.

Every read returns a masked_value (plus metadata like provider, expiry, last rotation, and scopes); there is no endpoint that returns the plaintext. Same auth constraint as the memory endpoints: these handlers currently accept Bearer JWTs only, so use the login + refresh flow, not X-API-Key.

# Store (value is write-only; the response echoes masked metadata only)
curl -s https://mem.jau.app/v1/credentials \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openai-prod",
    "provider": "openai",
    "credential_type": "api_key",
    "value": "sk-..."
  }'
# → 201 { "id": "...", "name": "openai-prod", "masked_value": "sk-****...", ... }

# Rotate in place when the key changes
curl -s https://mem.jau.app/v1/credentials/CRED_ID/rotate \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "new_value": "sk-newkey..." }'

Example: curl

# 1. Log in and capture a token (requires jq)
TOKEN=$(curl -s https://mem.jau.app/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"your-password"}' \
  | jq -r .access_token)

# 2. Store a memory
curl -s https://mem.jau.app/v1/memories \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Customer #4521 prefers email contact, timezone UTC+2",
    "tags": ["crm", "customer-4521"]
  }'

# 3. Search it back
curl -s https://mem.jau.app/v1/memories/search \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "how does customer 4521 want to be contacted", "mode": "hybrid", "limit": 5}'

Example: JavaScript (fetch)

A minimal server-side client (Node 18+, no dependencies):

const BASE = "https://mem.jau.app/v1";

async function login(email, password) {
  const res = await fetch(`${BASE}/auth/login`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ email, password })
  });
  if (!res.ok) throw new Error(`Login failed: ${res.status}`);
  const { access_token } = await res.json();
  return access_token;
}

async function remember(token, content, tags = []) {
  const res = await fetch(`${BASE}/memories`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ content, tags })
  });
  if (!res.ok) throw new Error((await res.json()).error?.message);
  return res.json();  // the stored memory, with id + auto type/importance
}

async function search(token, query, limit = 5) {
  const res = await fetch(`${BASE}/memories/search`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ query, mode: "hybrid", limit })
  });
  if (!res.ok) throw new Error((await res.json()).error?.message);
  return res.json();  // array of memories, best match first
}

// The core loop
const token = await login(process.env.JM_EMAIL, process.env.JM_PASSWORD);
await remember(token, "Deploy checklist: run migrations before restarting workers", ["ops"]);
const hits = await search(token, "what do I do before restarting workers");
console.log(hits[0].content);

Example: Python (requests)

import os
import requests

BASE = "https://mem.jau.app/v1"

# 1. Log in
resp = requests.post(f"{BASE}/auth/login", json={
    "email": os.environ["JM_EMAIL"],
    "password": os.environ["JM_PASSWORD"],
})
resp.raise_for_status()
headers = {"Authorization": f"Bearer {resp.json()['access_token']}"}

# 2. Store a memory
memory = requests.post(f"{BASE}/memories", headers=headers, json={
    "content": "Sensor batch B-17 calibrated 2026-07-06, drift within 0.2%",
    "tags": ["lab", "batch-b17"],
}).json()
print("stored:", memory["id"], "type:", memory["memory_type"])

# 3. Search it back
hits = requests.post(f"{BASE}/memories/search", headers=headers, json={
    "query": "when was batch B-17 last calibrated",
    "mode": "hybrid",
    "limit": 5,
}).json()
print("found:", hits[0]["content"])

Errors

Errors come back as JSON with a stable machine-readable code:

{
  "error": {
    "code": "RES001",
    "message": "Memory not found"
  }
}

Validation failures (VAL002) add a details array of { "field", "message" } objects so you can surface per-field errors.

Rate Limits

Limits are enforced per account, by plan. All plans are free during the beta.

Hitting a limit returns 429. Design for it: batch writes where you can, cache reads where freshness allows, and use exponential backoff on retry.

Security Model

• Encrypted at rest with per-user keys: every memory is encrypted with your account's own AES-256-GCM key before it hits the database. Encryption and decryption happen server-side and transparently; the API speaks plaintext JSON to you over TLS.
• TLS in transit: HTTPS for REST, TLS for gRPC.
• Row-level isolation: PostgreSQL row-level security scopes every query to your user. Other users' IDs 404 for you.
• Hardened auth: Argon2id password and API-key hashing, revocable per-device sessions, optional TOTP 2FA, audit logging on sensitive operations.
• Your data stays yours: GDPR export and account deletion are built in; nothing you store trains AI models.

To be precise about what this is not: it is server-side encryption, not end-to-end encryption. The server holds the per-user keys so it can search and classify your content for you.