deja
Documentation

API Reference

Everything you need to give your agents durable memory.

# Quick Start

Deploy deja to your Cloudflare account:

# Install wrangler
npm install -g wrangler

# Create vectorize index
wrangler vectorize create deja-embeddings --dimensions 384 --metric cosine

# Set your API key
wrangler secret put API_KEY

# Deploy
wrangler deploy

# Authentication

All mutating endpoints require a Bearer token:

Authorization: Bearer YOUR_API_KEY

Public endpoints (/, /inject, /query) work without auth for read operations.

# Universal MCP Setup (Any Agent)

deja is an MCP server. If your assistant supports MCP, it can use deja. Point your client to /mcp and pass your bearer token.

Generic MCP config

{
  "mcpServers": {
    "deja": {
      "type": "http",
      "url": "https://deja.your-subdomain.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${DEJA_API_KEY}"
      }
    }
  }
}

Install examples by client

Claude Code CLI

claude mcp add --transport http deja https://deja.your-subdomain.workers.dev/mcp   --header "Authorization: Bearer $DEJA_API_KEY"

Continue (config.yaml)

mcpServers:
  - name: deja
    type: streamable-http
    url: https://deja.your-subdomain.workers.dev/mcp
    headers:
      Authorization: Bearer ${secrets.DEJA_API_KEY}

Cline / JSON clients

{
  "mcpServers": {
    "deja": {
      "type": "http",
      "url": "https://deja.your-subdomain.workers.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${DEJA_API_KEY}"
      }
    }
  }
}

Available MCP Tools

learnStore a memory for future recall
injectRetrieve context-relevant memories
inject_traceDebug retrieval: candidates, scores, threshold (observability)
querySemantic search across memory
forgetDelete a specific memory
forget_bulkBulk delete by confidence, staleness, or scope
learning_neighborsFind semantically similar memories (contradiction checks)
listList memories by scope
statsRead memory usage/statistics

If it speaks MCP, it works with deja.

# REST Endpoints

POST /learn

Store a new learning with semantic embedding.

{
  "trigger": "deploying to production",
  "learning": "always run wrangler deploy --dry-run first",
  "confidence": 0.9,
  "scope": "shared",
  "reason": "caught a typo in wrangler.toml",
  "source": "deploy-agent"
}

Parameters:

  • trigger (required) — What triggers this memory
  • learning (required) — What was learned
  • confidence — 0.0 to 1.0 (default 0.5), memories below 0.3 are auto-cleaned
  • scope — "shared", "agent:id", or "session:id" (default: "shared")
  • reason — Optional context
  • source — Optional source identifier
POST /inject

Get relevant memories formatted for prompt injection. Each recalled memory gets last_recalled_at and recall_count updated.

{
  "context": "about to deploy the worker",
  "scopes": ["shared", "agent:deploy-bot"],
  "limit": 5
}

Returns a formatted string ready to inject into your agent's system prompt. Learnings include last_recalled_at, recall_count.

POST /inject/trace

Full retrieval pipeline for debugging. Returns candidates, similarity scores, threshold pass/fail, and timing. Use ?threshold=0.X or body to experiment with cutoffs.

POST /query

Semantic search over stored memories.

{
  "query": "deployment issues",
  "scopes": ["shared"],
  "limit": 10
}
GET /stats

Returns counts of learnings and secrets by scope.

GET /learnings?scope=shared

List all learnings, optionally filtered by scope. Each learning includes last_recalled_at, recall_count.

GET /learning/:id/neighbors?threshold=0.85&limit=10

Find semantically similar memories for a learning. Use before saving to check for contradictions. Default threshold 0.85.

DELETE /learning/:id

Delete a specific learning by ID. Requires authentication.

DELETE /learnings?confidence_lt=0.5&not_recalled_in_days=90&scope=shared

Bulk delete memories. Requires at least one filter: confidence_lt, not_recalled_in_days, or scope. Returns { deleted, ids }.

# Memory Tracking

Each learning tracks usage for observability and pruning:

last_recalled_atISO timestamp of last /inject recall
recall_countNumber of times this memory was injected

Use DELETE /learnings?not_recalled_in_days=90 to prune stale memories.

# Scopes

Memories are organized by scope for isolation and relevance:

shared

Global memories accessible by all agents. Auto-cleaned after 30 days with low confidence.

agent:<id>

Agent-specific memories. Use for learnings unique to a particular agent's behavior.

session:<id>

Temporary session memories. Auto-cleaned after 7 days — use for ephemeral context.

# For AI Agents

A machine-readable summary is available at /llms.txt for AI agents to quickly understand deja's API.

# Compatibility Notes

  • Use type: http, transport: http, or your client's equivalent key.
  • Always target https://.../mcp (not the root URL).
  • Pass Authorization: Bearer ... in headers/env as your client expects.
  • If tools don’t show up, fully restart your MCP client after config changes.