MNEMO API Documentation

MNEMO API

MNEMO (Mnemosyne) is the shared memory bus for the DOE multi-agent architecture. It provides persistent, ranked memory retrieval across AI agents using a 5-signal ranking engine: recency, keyword relevance, semantic similarity (pgvector), access frequency, and outcome scoring.

Base URL

/api/v1/mnemo

Protocol

REST / JSON

Endpoints

12 endpoints

Auth

API Key header

Authentication

All API requests require an API key passed via the X-MNEMO-Key header. API keys are provisioned per tenant and include scope restrictions.

Required Header

X-MNEMO-Key: your-api-key-here

Scopes

read Query and retrieve memories

write Create, update, and manage memories

Rate Limits

Rate limits are applied per API key. Exceeding the limit returns a 429 status code.

Tier	Requests / Day	Burst (per minute)	Scopes
Basic	100	10	read
Pro	1,000	60	read write
Enterprise	10,000	300	read write

Error Codes

The API uses standard HTTP status codes. Error responses include a JSON body with a detail field.

401

Invalid API Key

The X-MNEMO-Key header is missing or contains an invalid key.

{"detail": "Invalid MNEMO API key"}

403

Insufficient Scope

Your API key does not have the required scope (read/write) for this endpoint.

{"detail": "Insufficient scope: write required"}

429

Rate Limit Exceeded

You have exceeded the rate limit for your tier. Retry after the cooldown period.

{"detail": "Rate limit exceeded. Try again later."}

500

Internal Error

An unexpected server error occurred. Details are logged server-side for investigation.

{"detail": "Internal error"}

GET /api/v1/mnemo/context read

Retrieve ranked memories for a task query. Used by agents at session start or before planning to load relevant context. Returns memories sorted by a composite score combining 5 signals: recency, keyword, semantic, frequency, and outcome.

Query Parameters

Parameter	Type	Description
query REQUIRED	string	The task or topic to search for (1-2000 chars)
node_type optional	string	Agent role: planner, executor, tester, finalize, escalation (default: executor)
top_k optional	integer	Max results to return, 1-50 (default: 10)
min_score optional	float	Minimum composite score threshold, 0.0-1.0 (default: 0.0)

import requests

response = requests.get(
    "https://api.tds-automation.com/api/v1/mnemo/context",
    headers={"X-MNEMO-Key": "your-api-key"},
    params={"query": "database migration", "top_k": 5},
)
memories = response.json()
for m in memories:
    print(f"[{m['composite']:.2f}] {m['summary'][:80]}")

const response = await fetch(
  "https://api.tds-automation.com/api/v1/mnemo/context?query=database+migration&top_k=5",
  {
    headers: { "X-MNEMO-Key": "your-api-key" },
  }
);
const memories = await response.json();
memories.forEach(m =>
  console.log(`[${m.composite.toFixed(2)}] ${m.summary.slice(0, 80)}`)
);

curl -s -H "X-MNEMO-Key: your-api-key" \
  "https://api.tds-automation.com/api/v1/mnemo/context?query=database+migration&top_k=5" \
  | python -m json.tool

Response Example 200

[
  {
    "memory_id": 42,
    "memory_source": "memory.decisions",
    "summary": "Chose PostgreSQL for persistence layer due to pgvector support",
    "timestamp": "2026-03-15T10:30:00",
    "category": "architecture",
    "composite": 0.8523,
    "recency": 0.7200,
    "keyword": 0.9100,
    "semantic": 0.8800,
    "frequency": 0.6500,
    "outcome": 0.9000,
    "synthesis_entry_count": null
  }
]

POST /api/v1/mnemo/save write

Store a new memory entry and auto-embed it for semantic search. Used by any agent to persist decisions, events, lessons, or errors. The memory is automatically vectorized via pgvector for future semantic retrieval.

Request Body (JSON)

Field	Type	Description
type REQUIRED	string	Memory type: decision, event, lesson, or error
text REQUIRED	string	Memory content (1-10000 chars)
tags optional	string[]	Categorization tags (e.g. ["db", "architecture"])
layer optional	string	DOE layer: L1_PLANNING, L2_ORCHESTRATION, L3_CODING, L4_VALIDATION, ENV
agent optional	string	Agent that created this memory (default: "unknown")
detail optional	object	Extra JSONB metadata (e.g. reviewed, source_url)

import requests

response = requests.post(
    "https://api.tds-automation.com/api/v1/mnemo/save",
    headers={
        "X-MNEMO-Key": "your-api-key",
        "Content-Type": "application/json",
    },
    json={
        "type": "decision",
        "text": "Chose PostgreSQL for persistence",
        "tags": ["db", "architecture"],
        "agent": "claude",
    },
)
result = response.json()
print(f"Saved memory #{result['memory_id']} to {result['source']}")

const response = await fetch(
  "https://api.tds-automation.com/api/v1/mnemo/save",
  {
    method: "POST",
    headers: {
      "X-MNEMO-Key": "your-api-key",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      type: "decision",
      text: "Chose PostgreSQL for persistence",
      tags: ["db", "architecture"],
      agent: "claude",
    }),
  }
);
const result = await response.json();
console.log(`Saved memory #${result.memory_id} to ${result.source}`);

curl -s -X POST \
  -H "X-MNEMO-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"type":"decision","text":"Chose PostgreSQL for persistence","tags":["db","architecture"],"agent":"claude"}' \
  "https://api.tds-automation.com/api/v1/mnemo/save" \
  | python -m json.tool

Response Example 200

{
  "memory_id": 123,
  "source": "memory.decisions",
  "embedded": true,
  "agent": "claude"
}

GET /api/v1/mnemo/search read

Semantic search across all memory sources. Finds specific past memories by topic using pgvector similarity. Optionally filter by source table.

Query Parameters

Parameter	Type	Description
query REQUIRED	string	Search query text (1-2000 chars)
top_k optional	integer	Max results, 1-50 (default: 10)
sources optional	string	Comma-separated source filter (e.g. memory.lessons_learned,memory.decisions)

import requests

response = requests.get(
    "https://api.tds-automation.com/api/v1/mnemo/search",
    headers={"X-MNEMO-Key": "your-api-key"},
    params={
        "query": "security audit",
        "top_k": 10,
        "sources": "memory.lessons_learned",
    },
)
for m in response.json():
    print(f"#{m['memory_id']} [{m['composite']:.2f}] {m['summary'][:60]}")

const params = new URLSearchParams({
  query: "security audit",
  top_k: "10",
  sources: "memory.lessons_learned",
});
const response = await fetch(
  `https://api.tds-automation.com/api/v1/mnemo/search?${params}`,
  { headers: { "X-MNEMO-Key": "your-api-key" } }
);
const results = await response.json();

curl -s -H "X-MNEMO-Key: your-api-key" \
  "https://api.tds-automation.com/api/v1/mnemo/search?query=security+audit&top_k=10&sources=memory.lessons_learned"

Response

Same format as /context endpoint. Array of MemoryResult objects sorted by composite score.

GET /api/v1/mnemo/exists read

Check if a memory containing the given text already exists (exact substring match). Used for deduplication before saving, e.g. to verify if a URL was already transcribed.

Query Parameters

Parameter	Type	Description
text REQUIRED	string	Text to check for (exact substring match, case-insensitive)

Response Example 200

// Found
{"exists": true, "source": "events", "memory_id": 456, "summary": "..."}

// Not found
{"exists": false}

GET /api/v1/mnemo/unreviewed read

Get events marked as unreviewed (detail->>'reviewed' = 'false'). Used at session start to surface video learnings and knowledge items not yet discussed with the user.

Response Example 200

{
  "count": 3,
  "items": [
    {"id": 789, "summary": "Video transcript: AI agent patterns", "detail": {"reviewed": false}}
  ]
}

POST /api/v1/mnemo/mark-reviewed write

Mark events as reviewed after strategic discussion. Updates the detail JSONB to set reviewed=true.

Request Body (JSON)

Field	Type	Description
memory_ids REQUIRED	integer[]	Array of event IDs to mark as reviewed (min 1 item)

Response Example 200

{"updated": 3}

GET /api/v1/mnemo/stats read

Get MNEMO system health and statistics. Returns memory counts per source, embedding coverage percentage, ranking engine stats, and overall system health status.

import requests

response = requests.get(
    "https://api.tds-automation.com/api/v1/mnemo/stats",
    headers={"X-MNEMO-Key": "your-api-key"},
)
stats = response.json()
print(f"Status: {stats['status']}")
print(f"Memories: {stats['memory_store']}")

const response = await fetch(
  "https://api.tds-automation.com/api/v1/mnemo/stats",
  { headers: { "X-MNEMO-Key": "your-api-key" } }
);
const stats = await response.json();
console.log(`Health: ${stats.status}`);

curl -s -H "X-MNEMO-Key: your-api-key" \
  "https://api.tds-automation.com/api/v1/mnemo/stats" \
  | python -m json.tool

Response Example 200

{
  "ranking": {
    "total_memories": 892,
    "sources": {"memory.decisions": 312, "memory.events": 280, "memory.lessons_learned": 200, "memory.errors": 100}
  },
  "embeddings": {
    "total_embeddings": 845,
    "coverage_pct": 94.7
  },
  "memory_store": {
    "decisions": 312,
    "events": 280,
    "lessons": 200,
    "errors": 100
  },
  "status": "healthy"
}

POST /api/v1/mnemo/access write

Record that a memory was accessed (feedback loop). Agents call this after using a memory to improve future ranking via the frequency signal.

Request Body (JSON)

Field	Type	Description
memory_id REQUIRED	integer	ID of the accessed memory
source REQUIRED	string	Source table (e.g. memory.decisions)
node optional	string	Agent node that accessed it
query_context optional	string	The query that retrieved this memory
useful optional	boolean	Whether the memory was useful (reinforcement signal)

Response Example 200

{"status": "recorded"}

POST /api/v1/mnemo/evaluate-risk read

Evaluate risk of a code change against guardrail rules and MNEMO history. The active guardrail checks a rules table and searches MNEMO for related incidents/lessons before allowing destructive operations. Returns risk level, block status, and recommendations.

Request Body (JSON)

Field	Type	Description
action REQUIRED	string	Type of change: rewrite, modify, delete, refactor
file REQUIRED	string	File path being changed (1-500 chars)
change_description optional	string	Description of the change (max 2000 chars)
change_pct optional	integer	Percentage of file being changed (0-100)

Response Example 200

{
  "risk_level": "HIGH",
  "blocked": false,
  "reasons": ["MNEMO found 2 related incidents about destructive changes"],
  "related_incidents": [
    {"memory_id": 230, "source": "memory.lessons_learned", "summary": "...", "score": 0.712}
  ],
  "recommendation": "HIGH RISK: Proceed with caution. Review MNEMO incidents above."
}

POST /api/v1/mnemo/decay write

Apply time-based decay to all memory scores. Should be called periodically (daily or weekly) by the orchestrator to ensure recent memories are ranked higher than stale ones.

Response Example 200

{"records_updated": 847}

POST /api/v1/mnemo/synthesize write

Cluster and synthesize semantically similar memories using pgvector embeddings + LLM summarization. Creates or updates synthesis records that group related memories. Supports dry_run mode to preview clusters without persisting.

Request Body (JSON)

Field	Type	Description
source_type optional	string	Filter by source type (null = all sources)
threshold optional	float	Similarity threshold 0.0-1.0 (default: 0.80)
min_cluster_size optional	integer	Minimum entries per cluster, 2-20 (default: 2)
dry_run optional	boolean	Preview clusters without writing (default: false)

Response Example 200

{
  "clusters_found": 12,
  "syntheses_created": 8,
  "syntheses_updated": 4,
  "entries_processed": 156
}

GET /api/v1/mnemo/syntheses read

List existing synthesis records. Returns synthesis metadata including source type, title, entry count, and creation date. Optionally include stale (outdated) entries.

Query Parameters

Parameter	Type	Description
source_type optional	string	Filter by source type
include_stale optional	boolean	Include outdated syntheses (default: false)
limit optional	integer	Max results, 1-200 (default: 50)

Response Example 200

[
  {
    "id": 1,
    "source_type": "memory.decisions",
    "title": "Database architecture decisions cluster",
    "entry_count": 7,
    "created_at": "2026-03-20T14:00:00",
    "is_stale": false
  }
]

Try It

Test the GET /stats endpoint directly from this page. Enter your API key below to make a live request.

API Key

Endpoint

GET /api/v1/mnemo/stats