Quickstart

Sign in to the dashboard, create an organisation if you do not have one, and issue a key from Keys. The secret is shown exactly once — it is stored as a sha256 hash, so it cannot be shown again and cannot be recovered. If you lose it, revoke it and issue another.

Keys are scoped. memories:read and memories:write are the two that matter, and stats:read is optional. An agent that only reads should only hold the read scope; see credentials for what a key cannot do.

The dashboard itself is authenticated by your session, not by a key. You do not need a key to look at your own memory, and reaching for one would train exactly the habit this service discourages.

One official package, cogmemory. It is ~3kB gzipped, ESM-first, and its only hard dependency is ofetch.

pnpm add cogmemory

It contains two things, deliberately. The client talks to this service over HTTP. The deterministic layer — tiering, ranking, reconciliation, the fast gate — runs in-process with no database, no network, and no model in the retrieval path. Shipping both means a consumer can start against the service and later run the same logic locally without the behaviour changing underneath them. The SDK page is the long version.

runTurn is the recommended entry point, because the order is the part that is easy to get wrong: build context keyed on the message being answered, run the model, learn from the finished exchange, then record how the domain went.

import { createClient, runTurn } from "cogmemory"const memory = createClient({  apiKey: process.env.COGNITIVE_MEMORY_KEY!,  baseUrl: process.env.COGNITIVE_MEMORY_URL ?? "https://cogmem.astracollab.app"})const { context, learning, learningSkipped } = await runTurn(  memory,  { userMessage, run: (block) => callYourModel(block, userMessage) },  { domain: "database", sessionId })// context.text is the block: prepend it to your system prompt.// context.entries says which memory produced each line, and what it cost.

The last two steps never fail the turn. A memory outage cannot take down a model call that already succeeded, so the helper catches and reports instead of rethrowing — and learningSkipped is returned rather than left null, because a silent skip looks identical to a working one until the thing you taught it never comes back.

The API is a dozen JSON endpoints over bearer auth, so any HTTP client does it. Two calls are enough for memory to work: one before the model runs, one after it finishes.

# what the agent should know before it answerscurl -X POST $COGNITIVE_MEMORY_URL/api/v1/context \  -H "Authorization: Bearer $COGNITIVE_MEMORY_KEY" \  -H "content-type: application/json" \  -d '{"userMessage":"deploy ZQ7X4M2K to staging"}'# what it should remember from the finished turncurl -X POST $COGNITIVE_MEMORY_URL/api/v1/turns \  -H "Authorization: Bearer $COGNITIVE_MEMORY_KEY" \  -H "content-type: application/json" \  -d '{"userMessage":"...","assistantResponse":"..."}'

POST /v1/context returns the block to prepend plus the entries that produced it; POST /v1/turns returns what was stored, merged and rejected. The full surface is in the API reference.

Do not trust the first turn — verify the second one. Teach it a fact, then ask about it in a new session. If the fact is in the prompt, memory is working; if it is not, the context preview shows the exact block your agent would have been given, with the reason and cost of every line, which is the fastest way to find out why.

Analytics is the one to read when the numbers look wrong. It splits the token spend by the rule that caused each line, so “the whole budget went to index lines” is a diagnosis rather than a feeling.