Self-hosted dashboard

The fishmem engine is a library you embed. This page is about the layer above it: the control-plane, the full application that wraps the engine with a UI and a REST surface. It ships as the apps/web app in the open-source fishmem-labs/fishmem repo, and is the same app that powers FishMem Cloud.

If you only need memory inside one service, self-host the engine instead — see Self-hosting the engine. Run the control-plane when you want a team-facing platform.

What it provides

• A web dashboard to manage projects, keys, and memories.
• A Sources workspace for direct text, asynchronous PDF/Office/image extraction, immutable originals, and citation-ready RAG.
• API key management — issue and revoke fm_... keys per project.
• A usage view over operations and storage.
• Webhooks that fire on memory events.
• The FishMem REST API — the same add / search / get / update / delete / history surface documented in the API reference.

Choose one runtime:

Both use the same document-ingestion module, task states, retry rules, and artifact format. The open-source control plane leaves out managed billing, operated infrastructure, and SLA.

Run with Docker

The bundled Compose stack is the shortest complete self-host path.

git clone https://github.com/fishmem-labs/fishmem
cd fishmem
cp .env.example .env

Set OPENAI_API_KEY, BETTER_AUTH_SECRET, FISHMEM_SETUP_TOKEN, and CRON_SECRET to distinct non-placeholder values in the root .env. Compose fails closed when the three application secrets are absent. Then start the web process and durable task poller:

docker compose up -d web task-worker
docker compose logs -f web task-worker extractor

Compose brings up:

• web on http://localhost:3000;
• extractor, the pinned CPU Docling image on the private Compose network;
• task-worker, which wakes due tasks every two seconds and maintenance daily;
• one persistent fishmem-webdata volume containing libSQL and raw/artifact objects.

The web container applies schema changes before startup. Back up the whole volume: the relational rows and object directory form one retention unit. Uploads left incomplete for 24 hours are removed by maintenance.

Run on Cloudflare

git clone https://github.com/fishmem-labs/fishmem
cd fishmem
pnpm install
cd apps/web

wrangler secret put OPENAI_API_KEY
wrangler secret put BETTER_AUTH_SECRET
wrangler secret put FISHMEM_SETUP_TOKEN
wrangler secret put CRON_SECRET

wrangler queues create fishmem-document-tasks
wrangler queues create fishmem-document-tasks-dlq
wrangler r2 bucket create fishmem

{
  "d1_databases": [{ "binding": "D1", "database_name": "fishmem", "database_id": "<id>" }],
  "vectorize": [{ "binding": "VECTORIZE", "index_name": "fishmem-memories" }],
  "r2_buckets": [{ "binding": "R2", "bucket_name": "fishmem" }],
  "containers": [{
    "class_name": "FishMemExtractorContainer",
    "image": "./services/extractor/Dockerfile",
    "max_instances": 3,
    "instance_type": "standard-2"
  }],
  "durable_objects": {
    "bindings": [{
      "name": "DOCUMENT_EXTRACTOR",
      "class_name": "FishMemExtractorContainer"
    }]
  },
  "queues": {
    "producers": [{
      "binding": "DOCUMENT_TASKS",
      "queue": "fishmem-document-tasks"
    }]
  },
  "ratelimits": [{
    "name": "MEMORY_RATE_LIMITER",
    "namespace_id": "1001",
    "simple": { "limit": 600, "period": 60 }
  }]
}

wrangler vectorize create fishmem-memories --dimensions=1536 --metric=cosine
for prop in namespaceId recordKind userId agentId runId memoryType documentId sourceKey; do
  wrangler vectorize create-metadata-index fishmem-memories \
    --property-name="$prop" --type=string
done

pnpm run deploy:database

pnpm run deploy

curl https://<your-worker>.workers.dev/v1/memories \
  -H "Authorization: Bearer fm_..." \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "I prefer dark mode."}],
    "user_id": "alex"
  }'

The Worker dispatches export/import, rebuild, derivation, and maintenance tasks. File completion sends a Queue wakeup; the Queue consumer processes one extraction task per message with bounded concurrency. A */1 * * * * trigger repairs lost wakeups and expired leases, while 0 4 * * * also enqueues nightly maintenance. Keep both cron entries and CRON_SECRET configured.

The container image is pinned in apps/web/services/extractor/Dockerfile. Extraction uses Docling's async submit/status/result endpoints. The D1 task row—not the Queue or Container instance—owns retries and terminal status.

Next steps