Self-hosting

Node.js 22.19 or newer. The SDK is a workspace dependency, so build it before the app on a fresh checkout.

pnpm installpnpm --filter cogmemory buildpnpm --filter cognitive-memory dev

Open http://localhost:3000, sign up, and mint a key. Every environment value is optional in development — the service creates its SQLite file and its schema on first connection, and a key is still required in production.

cp .env.example .env.local

A browser asks for https://memory.example.com. Your proxy asks the app for http://localhost:3000. The app therefore has to be told which of the two is its public name, or the session cookie loses its Secure flag and sign-ins are rejected as an invalid origin.

The proxy says so in two headers. Forward both, and the app works out its own public origin:

proxy_set_header Host              $host;proxy_set_header X-Forwarded-Host   $host;proxy_set_header X-Forwarded-Proto  $scheme;

Next.js fills X-Forwarded-Proto in itself when no proxy sent one, and what it fills in is the scheme of the internal hop — so a proxy that terminates TLS and forwards only the host leaves the app thinking it is served over http. Set BETTER_AUTH_URL to the public URL in that case; it wins over everything the request says.

One deployment, one origin. A build that serves several hostnames — a preview and a custom domain — reads the right one per request, and the session cookie is named after the scheme it was issued on, so switching schemes signs everyone out once.

These set the deployment defaults. Each organisation can override the three budgets from the dashboard, and null means it follows the deployment again — see the dashboard.

With no model key the service is not degraded, it is rules-only: deterministic patterns still learn URLs, assignments and stated requirements, and GET /api/v1/health reports extractor: "rules-only". Check that field before concluding that extraction is broken.

The per-prompt ceiling is the single most consequential number in the deployment, and it is the one most likely to be set by copying the default. The useful question is not “how big can this be” but “how much of this store is worth a full body” — because index lines and bodies have very different prices and very different values.

A build that spends its whole budget on index lines and no bodies is not a memory that needs a bigger budget. It is a store with nothing worth promoting, and the two problems have opposite fixes. Analytics splits the spend by reason precisely so this is visible rather than guessed at.

measure is worth running against your own store rather than trusting the published numbers, because the ratio between index lines and full bodies depends entirely on what your agents have been told.

GET /api/v1/health   // liveness, limits, extractor mode. No key spent.

The server has no await in its domain logic: every service returns an Effect, one respond helper maps a tagged error to a status, and route handlers are ordinary async functions that await a Response. The consequence for you is that an error is a value you can match on — which is what makes the error shape uniform enough to branch on.