API Docs — Mnemonic

Quick Start

Store your first governed memory in under 5 minutes.

1

Get an API key

Sign up at mnemonicai.dev/pricing. Your key arrives by email within 60 seconds. It looks like this:

text

mnm_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6

⚠ Keys are shown exactly once at provisioning. Store yours in a secret manager, not in source code.

2

Write a memory

Send a POST to /v1/memories with the content you want to store. The tenant_id scopes the memory to one of your end-users.

curl

curl -X POST https://mnemonicai.dev/v1/memories \
  -H "Authorization:" "Bearer mnm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers dark mode and condensed layout",
    "tenant_id": "user_abc123"
  }'

3

Read it back

Query memories for a tenant. Results are filtered, governance-checked, and tenant-isolated.

curl

curl "https://mnemonicai.dev/v1/memories?tenant_id=user_abc123" \
  -H "Authorization:" "Bearer mnm_your_key"

4

Check your usage

Monitor memory counts, API calls, and governance events in real time.

curl

curl https://mnemonicai.dev/v1/usage \
  -H "Authorization:" "Bearer mnm_your_key"

Authentication

All API requests require a Bearer token in the Authorization header. API keys use the mnm_ prefix and are SHA-256 hashed before storage — Mnemonic never has access to your raw key after provisioning.

http

Authorization: Bearer mnm_your_api_key_here

Key properties

Property	Value
Prefix	mnm_ followed by 64 hex characters
Storage	SHA-256 hash only — raw key shown once at creation
Scope	Full API access for the provisioned tenant
Revocation	Keys can be revoked; revoked keys return 401 immediately

ℹ Each API call is logged to the api_calls table with method, path, status code, and response time — used for billing and rate limiting.

Memory Write

POST /v1/memories Write a memory with governance

Stores a memory for a tenant. Before writing, the content passes through the governance layer: PII patterns are auto-detected and redacted, retention limits are enforced, and the write is audit-logged. If permanent memory is disabled for your tier, all memories expire per your retention policy.

Request body

Parameter	Type	Required	Description
content	string	required	The memory text. Max length enforced by tier (4,096 chars on Free; up to 32,768 on Business). PII is auto-redacted before storage.
tenant_id	string	required	Your end-user's identifier. Memories are isolated per tenant — queries on one tenant never return another's memories.
external_id	string	optional	Your own identifier for this memory (e.g., a message ID). Useful for idempotency checks.
metadata	object	optional	Arbitrary JSON metadata attached to the memory. Not subject to PII scanning.
is_permanent	boolean	optional	If true, the memory never expires. Only available on Pro and Business tiers. Free and default-mode tiers will deny this.

Example request

curl

curl -X POST https://mnemonicai.dev/v1/memories \
  -H "Authorization: Bearer mnm_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User timezone is America/New_York, prefers 12h clock",
    "tenant_id": "user_abc123",
    "external_id": "msg_9876",
    "metadata": { "source": "onboarding", "session": "sess_01" }
  }'

Response — 201 Created

json

{
  "id": 1847,
  "content": "User timezone is America/New_York, prefers 12h clock",
  "tenant_id": "user_abc123",
  "external_id": "msg_9876",
  "metadata": { "source": "onboarding", "session": "sess_01" },
  "is_permanent": false,
  "expires_at": "2026-07-28T09:59:44Z",
  "governance": {
    "action": "stored",
    "pii_redacted": false,
    "redacted_fields": []
  },
  "created_at": "2026-04-28T09:59:44Z"
}

Governance — denied write

If governance rules block the write (e.g., permanent memory not allowed on free tier), you receive a 422:

json

{
  "error": "governance_denied",
  "message": "Permanent memories are not allowed on the free tier",
  "governance": {
    "action": "denied",
    "reason": "permanent_not_allowed"
  }
}

Error codes

Status	Code	Description
400	validation_error	Missing or invalid fields (e.g., content too long, missing tenant_id)
401	unauthorized	Missing, invalid, or revoked API key
422	governance_denied	Governance rules blocked the write. Check governance.reason.
429	rate_limit_exceeded	Too many requests in the current minute
500	internal_error	Unexpected server error

Memory Read / Search

GET /v1/memories List or search memories

Returns memories for a tenant, newest first. Optionally filter by keyword search. Expired and soft-deleted memories are excluded automatically. Results are always scoped to the authenticated API key's account — cross-tenant reads are impossible.

Query parameters

Parameter	Type	Required	Description
tenant_id	string	required	The end-user whose memories to retrieve.
q	string	optional	Keyword search query. Searches against memory content using full-text matching.
limit	integer	optional	Max memories to return. Default: 20. Max: 100.
offset	integer	optional	Pagination offset. Default: 0.

Example request

curl

curl "https://mnemonicai.dev/v1/memories?tenant_id=user_abc123&q=timezone&limit=10" \
  -H "Authorization: Bearer mnm_your_api_key"

Response — 200 OK

json

{
  "memories": [
    {
      "id": 1847,
      "content": "User timezone is America/New_York, prefers 12h clock",
      "tenant_id": "user_abc123",
      "external_id": "msg_9876",
      "metadata": { "source": "onboarding" },
      "is_permanent": false,
      "expires_at": "2026-07-28T09:59:44Z",
      "created_at": "2026-04-28T09:59:44Z"
    }
  ],
  "total": 1,
  "limit": 10,
  "offset": 0
}

Error codes

Status	Code	Description
400	validation_error	Missing tenant_id
401	unauthorized	Missing or invalid API key
429	rate_limit_exceeded	Rate limit exceeded

Memory Delete

DELETE /v1/memories/:id Soft-delete a memory

Marks a memory as deleted. Soft deletion sets deleted_at — the record is retained for audit purposes but is immediately excluded from all reads and counts. Deletes are tenant-scoped: you can only delete memories belonging to your account.

Path parameters

Parameter	Type	Required	Description
id	integer	required	Memory ID from the write or read response.

Example request

curl

curl -X DELETE https://mnemonicai.dev/v1/memories/1847 \
  -H "Authorization: Bearer mnm_your_api_key"

Response — 200 OK

json

{
  "success": true,
  "id": 1847,
  "deleted_at": "2026-04-28T10:15:00Z"
}

Error codes

Status	Code	Description
401	unauthorized	Missing or invalid API key
404	not_found	Memory doesn't exist or belongs to a different account
429	rate_limit_exceeded	Rate limit exceeded

Usage & Stats

GET /v1/usage Account usage and governance stats

Returns real-time usage data for the authenticated account: memory counts, API call volume, governance event totals, rate limit status, and retention info. No parameters required.

Example request

curl

curl https://mnemonicai.dev/v1/usage \
  -H "Authorization: Bearer mnm_your_api_key"

Response — 200 OK

json

{
  "total_memories": 247,
  "api_calls_this_period": 1832,
  "billing_period": {
    "start": "2026-04-01",
    "end": "2026-04-30"
  },
  "memories_denied": 3,
  "memories_pii_redacted": 14,
  "rate_limit": {
    "max_per_minute": 60,
    "used_last_minute": 4
  },
  "retention": {
    "max_days": 365,
    "days_remaining": 278
  },
  "max_memory_length": 16384,
  "permanent_memory_enabled": true,
  "tier": "pro"
}

Response fields

Field	Type	Description
total_memories	integer	Active (non-deleted, non-expired) memory count
api_calls_this_period	integer	Authenticated API calls since the start of the current calendar month
billing_period	object	Current billing period as ISO date strings (start, end)
memories_denied	integer	All-time count of writes blocked by governance rules
memories_pii_redacted	integer	All-time count of writes where PII was auto-redacted before storage
rate_limit.max_per_minute	integer	Your tier's maximum requests per minute
rate_limit.used_last_minute	integer	Requests made in the last 60 seconds
retention.max_days	integer	Maximum memory age in days before automatic expiration
retention.days_remaining	integer	Days until the oldest memory expires
max_memory_length	integer	Max character length for memory content on your tier
permanent_memory_enabled	boolean	Whether is_permanent: true is allowed on this tier
tier	string	free, pro, or business

Error codes

Status	Code	Description
401	unauthorized	Missing or invalid Authorization header
500	internal_error	Failed to retrieve usage stats

Governance

Governance is applied automatically on every write. There's no opt-in, no configuration needed to start using it, and no way for a misconfigured call to bypass it. Every write decision — allow, redact, or deny — is recorded as an immutable audit event.

🔍

PII Auto-Redaction

Social security numbers, credit card numbers, email addresses, phone numbers, passwords, and API key patterns are detected and scrubbed before writing to storage. The write succeeds with redacted content.

📅

Retention Policies

Memories expire automatically based on your tier's retention window. Free: 30 days. Pro: 365 days. Business: 7 years. Expired memories are excluded from all reads before physical deletion.

🔒

Multi-Tenant Isolation

Every memory is scoped to a tenant_id. Reads, writes, and deletes are enforced at the database layer — there's no code path that can cross tenant boundaries.

📋

Immutable Audit Log

Every governance decision is appended as an event record. Events are never updated or deleted — your audit trail is complete and tamper-evident.

PII Redaction

The following patterns are detected and replaced with redaction tokens before a memory is written.

Pattern	Redacted as	Examples detected
SSN	[REDACTED:SSN]	123-45-6789, 123456789
Credit card	[REDACTED:CREDIT_CARD]	Visa, Mastercard, Amex — 13–16 digit numbers
Email address	[REDACTED:EMAIL]	user@example.com
Phone number	[REDACTED:PHONE]	+1-555-867-5309, (555) 867-5309
Password fields	[REDACTED:PASSWORD]	Patterns like "password: abc123", "pwd=..."
API keys / secrets	[REDACTED:API_KEY]	sk_live_..., Bearer token patterns in content

ℹ Redactions are applied to content only. The metadata field is stored as-is. Do not put sensitive data in metadata.

Retention policies

Memory lifetime by tier:

Tier	Retention	Permanent memory	Max memories	Max content length
Free	30 days	✗	500	4,096 chars
Pro	365 days	✓	50,000	16,384 chars
Business	7 years	✓	500,000	32,768 chars

Access control

Tenant isolation is enforced at the query layer — every database operation filters by user_id (your account) and tenant_id (your end-user). There is no admin override that bypasses this. Memories from one API key account are never visible to another.

Error Handling

All errors return JSON with a consistent shape. Check error for machine-readable codes and message for a human-readable description.

json — error shape

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded 60 requests per minute"
}

All error codes

Status	Code	When it occurs
400	validation_error	Request body or query parameters are malformed or missing required fields
400	invalid_email	Email address format is invalid (signup endpoint)
401	unauthorized	Missing, empty, malformed, or revoked API key
404	not_found	Requested resource doesn't exist or belongs to a different account
422	governance_denied	Write was blocked by a governance rule. Check governance.reason for specifics.
429	rate_limit_exceeded	Exceeded the per-minute request limit for your tier
500	internal_error	Unexpected server error. If this persists, contact support@mnemonicai.dev

Rate Limits

Rate limits apply per API key, measured in a rolling 60-second window. When exceeded, the request fails immediately with 429. The current usage is always visible via GET /v1/usage.

Tier	Requests / minute	API calls / month
Free	10 req/min	1,000 / month
Pro	60 req/min	100,000 / month
Business	300 req/min	1,000,000 / month

ℹ Monthly API call limits reset on the 1st of each calendar month. Rate limits (per-minute) are rolling windows and do not reset on a schedule.

Need higher limits?

Business tier limits can be extended on request. Custom contracts available for high-volume or regulated workloads.

Contact us →

Mnemonic API

Quick Start

Get an API key

Write a memory

Read it back

Check your usage

Authentication

Memory Write

Memory Read / Search

Memory Delete

Usage & Stats

Governance

PII Auto-Redaction

Retention Policies

Multi-Tenant Isolation

Immutable Audit Log

PII Redaction

Error Handling

Rate Limits

Need higher limits?