Quickstart

Make your first authenticated memory call in under five minutes, from curl, the TypeScript SDK, or the CLI.

iCog is a persistent memory backbone for your agents and apps. You write facts, events, and skills with remember, read them back with recall, and let iCog ground its replies in everything it knows with talk. This page takes you from zero to a working round trip.

Every request goes to https://api.cognitivx.io and authenticates with an API key, passed as either Authorization: Bearer <key> or X-API-Key: <key>.

Create an API key

Go to developers.cognitivx.io/keys and create a new key. It is prefixed with icog_. Copy the value now, you only see it once.

Keep it server-side. Export it so the examples below can read it:

export ICOG_API_KEY="icog_..."

Make your first call

POST /api/talk is the fastest way to confirm your key works. iCog recalls any context it has and replies as a cognitive peer. With an empty store it still answers, just without grounding.

curl -X POST https://api.cognitivx.io/api/talk \
  -H "Authorization: Bearer $ICOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message":"Before I build this integration, what should I remember?"}'

pnpm add @cognitivx/sdk

import { configureApiClient, memory } from '@cognitivx/sdk';

// Authenticate once. Use a personal API key for server-side code.
configureApiClient({ apiKey: process.env.ICOG_API_KEY });

const reply = await memory.talk({
  message: 'Before I build this integration, what should I remember?',
});

console.log(reply.response);
console.log(`[${reply.context_used} memories recalled]`);

npm install -g @cognitivx/cli
cogx auth login          # or: export ICOG_API_KEY="icog_..."

cogx talk "Before I build this integration, what should I remember?"

{
  "response": "Nothing yet — your memory store is empty. Tell me a few durable facts and I'll ground future answers in them.",
  "context_used": 0,
  "identity_proposal": null
}

context_used is the number of memories iCog pulled in to write that reply. It is 0 on a fresh account and climbs as you store memories.

Store a memory

Write a durable fact with POST /api/remember. Set memory_type to classify it, or omit it and iCog classifies for you. The four types you may write are semantic, episodic, procedural, and foundational.

curl -X POST https://api.cognitivx.io/api/remember \
  -H "Authorization: Bearer $ICOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"content":"User prefers TypeScript examples and dark mode.","memory_type":"semantic"}'

import { configureApiClient, memory } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

const { memory_id } = await memory.remember({
  content: 'User prefers TypeScript examples and dark mode.',
  memory_type: 'semantic',
});

cogx remember "User prefers TypeScript examples and dark mode." --type semantic

{
  "memory_id": "a1f3c2d4-5b6e-4f78-9a01-2c3d4e5f6a7b"
}

For a personal (non-org) account, remember requires the awakened tier or higher and returns 403 tier_insufficient below that. Org members are entitled through their seat.

Recall it

Read memories back with POST /api/recall. It runs a semantic plus temporal search and returns the closest matches with a similarity score.

curl -X POST https://api.cognitivx.io/api/recall \
  -H "X-API-Key: $ICOG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"user preferences","limit":5}'

import { configureApiClient, memory } from '@cognitivx/sdk';

configureApiClient({ apiKey: process.env.ICOG_API_KEY });

const { memories, count } = await memory.recall({
  query: 'user preferences',
  limit: 5,
});

cogx recall "user preferences" --limit 5

{
  "memories": [
    {
      "id": "a1f3c2d4-5b6e-4f78-9a01-2c3d4e5f6a7b",
      "text": "User prefers TypeScript examples and dark mode.",
      "memory_type": "semantic",
      "age_days": 0,
      "created_at": "2026-06-16T18:04:22.512000+00:00",
      "similarity": 0.86
    }
  ],
  "count": 1
}

recall returns 200 with {"memories":[],"count":0} on an internal error rather than a 5xx. Check count, not just the status code.

That is the full loop: store, recall, and let iCog talk with that context in hand. Everything else in the API builds on these three verbs.

Create an API key

Make your first call

Store a memory

Recall it

What's next

Memory API

MCP server

Errors

On this page