Cognitia AI
Documentation
Everything you need to know about using Cognitia AI, connecting your tools, and getting the most out of your AI assistant.
Product Overview
For Consumers
For Developers
For Businesses
For Consumers
For Developers
For Businesses
Getting Started
Start HereCreate Your Account
Visit the login page and create your account using one of three methods:
Google Sign-In -- One-click sign up with your Google account. Fastest way to get started.
iCloud Sign-In -- Sign up with your Apple ID for seamless iCloud integration.
Email & Password -- Create an account with any email address and a secure password.
All new accounts start with a free tier. No credit card required.
Connect Your First Integration
After signing in, navigate to the sidebar and connect your first service. We recommend starting with Gmail as it unlocks both email and calendar capabilities:
Click the Email & Calendar button in the sidebar
Select Gmail and authorize Cognitia to access your account
Once connected, you can ask Cognitia to search and read emails, plus manage your Google Calendar from chat
Send Your First Message
Navigate to the Chat page and start a conversation. Cognitia adapts to natural language -- just tell it what you need:
"Summarize my unread emails from today"
"What meetings do I have this week?"
"Search the web for the latest AI news"
"Summarize my unread emails from today"
Integrations Guide
MCP & backups
What is MCP & backups?
MCP & backups is where you install Cognitia as a memory MCP server in other apps and import assistant memory (ChatGPT, Claude, Gemini). Other apps call Cognitia’s MCP endpoint. Connecting generic remote MCP servers from Cognitia is turned off.
Key highlights:
Available to all subscription tiers
No additional cost beyond LLM credits
Use Cognitia from any MCP client
MCP Memory Layer
NewWhat's new
Recently shippedRecent additions to the memory layer and Memory Explorer:
Four-tool external MCP — Hosts get unified_memory_agent (Ask: context + optional evidence), unified_memory_retrieve (profile + scored entities, facts, and edges; optional evidence), origin-grant config, and unified_memory_store. Specialty identity/temporal tools stay first-party.
Identity review queue — Approve or dismiss newly discovered identities before they join your graph.
Memory-conditioned image generation — Temporarily disabled. Returns in Q4 as multimodal memory (photos/video → identity), not a general image studio.
Generated-image gallery — Every generated image is saved and shown in the person’s media panel.
Cloned-voice playback — Hear a remembered person speak any text in their enrolled voice.
Photo identify — Upload a photo to find matching people already in your memory.
Signal-aware forget — Forgetting a person also tombstones their name-matched behavioral signals.
Manual & reviewed merge — Merge duplicate entities manually or from the merge-candidate review queue.
Device files — Browse and search files indexed from your connected devices.
What is the MCP Memory Layer?
The MCP Memory Layer lets you use the personal memory you've built with Cognitia from any external MCP-compatible client — including Cursor, Claude Desktop, Claude Code, Windsurf, and more. Your knowledge graph, conversation history, emails, files, financial data, social media, and multimodal identity data are all accessible through a single unified endpoint.
Instead of your memory being locked inside Cognitia, external AI agents can query it as context. For example, a coding agent in Cursor could retrieve your project-related knowledge, or Claude Desktop could recall your preferences and recent conversations.
Memory layers available:
Knowledge Graph
Entities & relationships
Temporal facts & timeline
Time travel (as-of / since)
Behavioral profile
Store new knowledge
Data Sources
Email search
Financial data
Social media
Cloud files
Multimodal (Pro)
Face recognition
Voice identification
Visual object matching
Quick Start
Connecting takes one step — add the Cognitia MCP endpoint URL to your client. OAuth handles everything else automatically.
Cursor / Claude Desktop / Claude Code
Add this to your MCP client configuration file:
{ "mcpServers": { "cognitia-memory": { "url": "https://www.cognitia-ai.com/api/mcp" } } }
Add the configuration above to your MCP client settings.
On first connection, your client opens a browser window. Log into Cognitia if prompted.
On the consent screen, select which memory sub-tools to grant access to, then click Allow Access.
Done. The external client now has access to the tools you selected. Token refresh is automatic.
Authentication
Cognitia's MCP server supports OAuth 2.1 with PKCE, the same industry-standard protocol used by Notion, Linear, and other MCP services. Clients that support OAuth (Cursor, Claude Desktop, Claude Code) handle the entire flow automatically.
OAuth 2.1 (automatic)
No tokens or API keys to manage. The client handles login, consent, token exchange, and automatic refresh. You just add the URL and approve the connection once.
Personal API key
For automation, scripts, or clients where you want a credential that does not expire every hour. Keys start with cog_usr_ and are sent the same way: Authorization: Bearer YOUR_KEY.
Create and revoke keys under MCP & backups → Personal API key. You can have up to five active keys; store them like any secret and revoke them if they leak.
Available Tools
External OAuth clients and personal API keys may call exactly four memory tools. Specialty tools (identity search, memory_as_of / memory_diff, share cards) stay on the first-party app session.
Which tool to call
Call unified_memory_agent_config action=list once per session. Use unified_memory_retrieve for people, facts, or a profile. Use unified_memory_agent for a written answer, today's inbox, or calendar — set include_evidence when you will cite. Store only text the user asked to remember, and keep source_id. Do not invent tools that are not listed. Personal initialize also returns these instructions plus memory.ask / memory.retrieve / memory.remember prompts and cognitia://status / cognitia://profile.
Ask memory (prose + live). Send a natural-language query; the server returns one synthesized context string. Use for freshness, mail, calendar, or a written answer — not to list entities. Pass include_evidence: true to attach evidence for sources the answer actually used (snippet + locator + an open URL only when a provider permalink or signed file exists). Use as_of / since as ISO 8601. Optional focus pins the answer to one person or place name. hydrate_from re-opens sources from this client's recent evidence[] (personal only). Personal responses do not include entities, facts, or signals. This tool cannot store or delete.
Example queries: "What do I know about Project Atlas?", "Find my recent emails about the budget meeting", "What are my current goals?"
Retrieve graph (no LLM). Use at session start or when you will reason over structs. Send query, entity, or entity_id (graph UUID from a prior retrieve), plus optional as_of / since, origins, limit, entity_types / fact_types / relation_types, threshold. Returns compiled profile plus scored entities, facts, and edges — no synthesized answer and no live inbox. entities[] include id; edges include source_id / target_id. query ranks the graph; it does not parse time or names into structured fields. Marketplace names stay anonymized; iterate with entity_id, not the pseudonym. include_evidence: true attaches Ask-shaped evidence for the returned slice plus extract artifacts of returned graph rows. Personal retrieve is 2 credits, or 4 with evidence. Marketplace evidence stays quoted snippets without open URLs.
Memory access + status. Call action: "list" once per session to see origin grants ( off / kg / raw), multimodal_query, local_files, and per-origin last_ingest_at (null when Cognitia has no sync stamp — mcp and chat are usually null). updatedAt is the permission row, not ingest time. Use action: "update" with origin_grants. kg is synthesized graph only; raw adds vectors and live APIs. Default is raw for every origin.
Remember a note the user asked to save — not a chat dump. Queue text (origin mcp). Returns queued and source_id after the raw row is written; embedding and graph extraction continue in the background. Keep source_id. This tool cannot delete. Business marketplace clients cannot write.
First-party only
Identify-a-photo, person media galleries, cloned-voice playback, memory_as_of / memory_diff, and shareable memory cards remain available in the Cognitia app and first-party sessions. They are not on the external MCP allowlist.
Tool Permissions & Consent
When a new client connects via OAuth, you choose how much of each origin that app may see. Each client has its own grants. Change them later from MCP & backups or by calling unified_memory_agent_config.
Every origin has a fidelity: off (hidden), kg (synthesized graph only), or raw (graph plus vectors and live APIs). Default is raw. Writes from connected apps land on the mcp origin.
Origins (12)
email, finance, storage, social, chat, chat_backup, app_sync, companion, calendar, ingested, import, mcp
Fidelity
off — hide this origin. kg — graph facts only. raw — graph + Pinecone + official live APIs (mail, Plaid, Drive, calendar).
Optional capability
search_by_identity — cross-modal matching (on by default; Pro at query time). search_local_files — local device file index (off by default).
The host never picks sub-tools. An inner Ask agent searches granted origins inside unified_memory_agent.
Managing Connected Apps
Go to MCP & backups to see all external apps that have been granted access to your memory layer. Each connected app shows:
App name and connection date
Number of active sessions
Last used date
Click Revoke to immediately disconnect an app and invalidate all its tokens. The app will need to re-authorize through the OAuth flow to regain access.
Credit Billing
External MCP tool calls that run LLM agents (like unified_memory_agent) are billed based on actual token usage. The same per-model pricing as chat applies, with no free input token allowance. unified_memory_retrieve has no LLM: a successful personal call costs 2 credits (profile + graph) or 4 credits when include_evidence is on. Empty successful calls still charge; validation failures do not. Row count does not change the fee. unified_memory_agent_config and unified_memory_store are free.
Internal calls from the Cognitia web and mobile apps are not double-billed — credit deduction only applies when the request comes from an external OAuth client.
A rate limit of 60 requests per minute is applied per user across all MCP endpoints to prevent abuse.
Technical Architecture
When an external client calls unified_memory_agent, the request flows through several layers:
Authentication — The MCP endpoint validates an OAuth access token ( cog_at_… ) or personal API key ( cog_usr_… ), extracting the user ID and client ID. Session JWTs are not accepted; they are for first-party apps (iOS) only.
Rate Limit Check — A sliding-window counter ensures the user hasn't exceeded 60 requests/minute.
Caller Scoping & Config Lookup — The server enforces a caller-scope allowlist at the MCP boundary: external OAuth clients only see and can call unified_memory_agent, unified_memory_retrieve, unified_memory_agent_config, and unified_memory_store. tools/list is filtered to match. It then loads per-client origin grants.
Agent Execution — Personal Ask runs an inner agent over the origins you granted. The host never sees those internal tools.
Tool Execution — Graph reads hit Supabase; vector search fans out to Pinecone for origins granted at raw fidelity; official live (mail, Plaid, Drive, calendar) runs when those origins are raw. Store writes a raw mcp/note row and finishes embed + extract in the background.
Billing — Total input and output tokens from all LLM calls are accumulated. Credits are calculated and deducted (external OAuth clients only).
Personal Ask returns a synthesized context string and, when requested, evidence for sources the answer actually used — not entities, facts, signals, or every retrieved hit. Token usage metadata is stripped before the response reaches the client.
API Endpoints
All endpoints are served from the base URL https://www.cognitia-ai.com/api/mcp. The server supports both the JSON-RPC 2.0 protocol and direct REST-style routes. Personal OAuth and API-key clients should use JSON-RPC for prompts/* and resources/* (filtered to memory.* and cognitia://status / cognitia://profile). REST prompt and resource routes stay first-party. Marketplace clients stay tools-only.
MCP Protocol (JSON-RPC 2.0)
/api/mcp/jsonrpc
JSON-RPC endpoint (all MCP methods)
/api/mcp/tools/list
List available tools
/api/mcp/tools/call
Execute a tool
/api/mcp/resources/list
List available resources
/api/mcp/resources/read
Read a specific resource
/api/mcp/prompts/list
List available prompts
/api/mcp/prompts/get
Get a prompt with arguments
OAuth 2.1 Endpoints
/.well-known/oauth-authorization-server
Server metadata (RFC 8414)
/api/mcp/oauth/register
Dynamic client registration
/api/mcp/oauth/authorize
Authorization (redirects to consent)
/api/mcp/oauth/token
Token exchange and refresh
/api/mcp/oauth/connected-apps
List connected apps
/api/mcp/oauth/connected-apps
Revoke app access
OAuth 2.1 Flow Detail
The authorization flow follows the OAuth 2.1 Authorization Code grant with PKCE (S256). Most MCP clients handle this automatically — the details below are for client developers and advanced users.
Discovery — The client fetches /.well-known/oauth-authorization-server to discover endpoints and supported capabilities.
Client Registration — The client registers itself via POST /api/mcp/oauth/register with its name and redirect URIs. Returns a client_id.
Authorization — The client generates a PKCE code_verifier/code_challenge pair and redirects the user to the authorization endpoint with response_type=code, code_challenge_method=S256, and the code_challenge.
Consent — The user logs into Cognitia (if not already), sees the tool permission screen, selects which tools to grant, and clicks Allow Access.
Code Exchange — The server redirects back to the client with an authorization code. The client exchanges it at POST /api/mcp/oauth/token with the code_verifier.
Token Response — Returns an access token (1 hour TTL) and refresh token (90 day TTL). The client uses the access token in the Authorization: Bearer header for all MCP requests.
Refresh — When the access token expires, the client exchanges the refresh token at the token endpoint for a new access/refresh token pair. Refresh tokens are rotated on each use.
Token Formats
OAuth access token — 64-character hex, 1-hour TTL, stored as SHA-256 hash
OAuth refresh token — 64-character hex, 90-day TTL, rotated on each use
Personal API key — long-lived, revocable, for scripts or clients without OAuth
Input & Output Schemas
unified_memory_agent — Input
{ "query": "string (required) — natural language query", "as_of": "string (optional) — ISO 8601 instant; view the knowledge graph as it existed at this point in time", "since": "string (optional) — ISO 8601 instant; restrict to what is new or changed at/after this time. Combine with as_of to ask 'what changed between X and Y'", "include_evidence": "boolean (optional) — attach evidence[] for sources the answer used (not every retrieved hit)", "focus": "string (optional) — person/place name to pin", "hydrate_from": [{ "source_type": "email", "source_id": "...", "chunk_index": 0 }] }
unified_memory_agent — Output
{ "success": true, "context": "The user …", "evidence": [ { "origin": "storage", "source_label": "Google Drive", "source_type": "google_drive", "source_id": "drive-1", "title": "Lease.pdf", "snippet": "Page 2 names Ada as tenant.", "locator": { "chunk_index": 2, "page": 2 }, "occurred_at": "2025-10-05T18:00:00.000Z", "participants": [], "open": { "kind": "provider_url", "url": "https://...", "label": "Open original" } } ] }
unified_memory_retrieve — Input
{ "query": "string — ranking / search text (or entity / entity_id)", "entity": "string — name, not an id (or query / entity_id)", "entity_id": "string — graph UUID from a prior retrieve", "include_evidence": "boolean (default false)", "origins": ["email", "calendar"], "as_of": "ISO 8601 (optional)", "since": "string (optional)", "until": "string (optional) — alias for as_of", "limit": "number (default 20, max 100)", "entity_types": ["person"], "fact_types": ["event"], "relation_types": ["works_at"], "threshold": "number 0–1 (default 0, off)", "target_user_id": "string (business only)" }
unified_memory_retrieve — Output
{ "success": true, "profile": "compiled body_text…", "entities": [ { "id": "uuid", "name": "...", "type": "person", "mentionCount": 5, "lastSeen": "2026-02-19T...", "score": 0.81 } ], "facts": [ { "type": "state", "subject": "...", "predicate": "...", "object": "...", "validAt": "...", "confidence": 0.95, "score": 0.74 } ], "edges": [ { "source": "Ada", "relation": "works_at", "target": "Acme", "score": 0.55, "source_id": "uuid", "target_id": "uuid" } ], "evidence": [ { "origin": "email", "source_label": "Email", "source_type": "email", "source_id": "...", "title": "...", "snippet": "...", "locator": { "chunk_index": 0, "page": null }, "occurred_at": "2026-01-15T...", "participants": [], "open": { "kind": "provider_url", "url": "https://...", "label": "Open original" } } ] } (evidence is omitted unless include_evidence is true)
unified_memory_agent_config — Input (list)
{ "action": "list" }
unified_memory_agent_config — Output (list)
{ "originGrants": { "email": "raw", "finance": "kg", "mcp": "raw" }, "multimodal_query": false, "updatedAt": "2026-02-19T...", "local_files": { "granted": true, "indexed": true }, "origins": { "email": { "last_ingest_at": "2026-02-19T..." }, "mcp": { "last_ingest_at": null } } }
unified_memory_agent_config — Input (update)
{ "action": "update", "origin_grants": { "email": "kg", "app_sync": "off", "mcp": "raw" } }
unified_memory_agent_config — Output (update)
{ "success": true, "originGrants": { "email": "kg", "app_sync": "off", "mcp": "raw" }, "updatedAt": "2026-02-19T..." }
unified_memory_store — Input
{ "text": "string (required) — text to remember", "title": "string (optional)", "occurred_at": "string (optional) — ISO 8601", "participants": ["string"], "external_id": "string (optional) — host idempotency key" }
unified_memory_store — Output
{ "queued": true, "source_id": "uuid-of-ingested-artifact" }
Error Responses
All MCP endpoints return standard HTTP status codes. The 401 response includes a WWW-Authenticate header pointing to the authorization server metadata, allowing clients to auto-discover the OAuth flow.
Success — tool result in response body
Bad request — missing or invalid parameters
Unauthorized — invalid/expired token. Includes WWW-Authenticate: Bearer resource_metadata="..." header
Forbidden — user ID mismatch
Method not allowed — wrong HTTP method
Rate limited — includes Retry-After: 60 header. Wait and retry.
Internal server error
Rate Limits & Billing Detail
Rate Limits
Requests per minute
60 per user (sliding window)
Auth code TTL
5 minutes (single use)
Access token TTL
1 hour
Refresh token TTL
90 days (rotated on each use)
Agent max steps
6 LLM calls per query
CORS
All origins allowed (Access-Control-Allow-Origin: *)
Using AI Agents
Multi-Agent Orchestration
When you send a message, Cognitia's orchestrator analyzes your request and determines which tools and agents are needed. For complex requests, it breaks the task into parallel operations:
Automatic tool selection: Cognitia picks the right tools based on your connected integrations and the nature of your request.
Parallel execution: Independent tasks run simultaneously. For example, searching emails while checking your calendar happens at the same time.
Context awareness: The orchestrator uses your conversation history and persistent memory to provide personalized responses.
Document Generation
Generate professional documents directly from your conversations. Cognitia can create files in multiple formats and optionally upload them to your connected cloud storage.
Understanding Credits
Cognitia uses a credit-based system to manage usage. Each message, tool call, and AI interaction consumes credits based on complexity. Your subscription tier determines your monthly credit allocation.
Work, not a model menu: Credits scale with task complexity and tools (search, browser, memory). You do not pick an underlying model.
Tool calls count: When Cognitia uses tools (email search, browser automation, etc.), each tool invocation adds to the credit cost of that message.
Track your usage: Monitor your credit balance in your Account settings.
Monetize Your Memory
NewYour memory graph is an asset you own — and you can optionally earn from it. Aggregate insights is enrolled by default (opt out anytime). Brands that already have you as a customer may request Personal enrichment; you approve each request and choose source groups, or auto-approve incoming ones. Name, email, phone, and address are never shared. You can revoke at any time.
Enroll your data
Open Data Platform → Monetization → Settings. Aggregate insights is listed by default. You decide:
Which products to list — Aggregate insights (cohort patterns; on by default) and/or Personal enrichment (one brand at a time).
Insights vs enrichment — Aggregate insights is cohort-level. Personal enrichment is for a brand that already has you as a customer.
Every enrichment request — you approve or deny and choose which of five source groups they may use, or turn on auto-approve. Identity fields (name, email, phone, address) cannot be requested. Approved brands may receive graph attributes and short evidence snippets, not full original files.
Consent & control
Aggregate insights queries only ever see anonymized cohorts across many enrolled users — never your identity.Personal enrichment additionally requires you to approve an explicit, per-business consent request (or auto-approve incoming ones). Identity fields are never in the payload. You can revoke any consent or unlist entirely at any time; revocation takes effect immediately and stops all future access.
Earnings & payouts
You earn 70% of the data-access fee on every paid query against your data; the platform retains 30%.
Earnings accrue to your provider balance in real time and are visible in the Marketplace dashboard.
Payouts are sent via Stripe Connect once your available balance reaches the $50 minimum.
Marketplace API
NewFor businesses
The Marketplace API is three products: Aggregate for consented cohorts, and Ask plus Retrieve for a person the business already has as a customer. Personal enrichment enrollment gates Ask and Retrieve on five source groups; some providers auto-approve incoming requests. Every query is logged. Name, email, phone, and address are never returned.
After access is approved, register with the activation code we send, complete verification, and generate a business API key (prefixed cog_biz_). Authenticate every request with Authorization: Bearer cog_biz_.... The marketplace tools are also available to MCP agents via marketplace_discover_providers, marketplace_aggregate_query, marketplace_request_consent, unified_memory_agent (Ask), and unified_memory_retrieve (Retrieve; include_evidence requires evidence consent).
What data can be sourced
Aggregate can still take a memory layer on premium cohort queries. Ask and Retrieve use the user-facing contracts (query / since / as_of / include_evidence), scoped to users who granted Personal enrichment consent:
knowledge_graph
Entities, types, and relationships (anonymized: pseudonyms, type distributions, confidence bands).
behavioral_signals
Preferences, habits, interests, goals, and styles with evidence counts and freshness.
temporal_facts
Time-bounded facts (subject/predicate/object) with observation month and confidence bands.
Aggregate results are always anonymized cohort stats — no identity fields. Ask returns synthesized context. Retrieve returns an anonymized scored graph. Both are limited to source groups that person approved. include_evidence adds quoted snippets from those origins — not inbox dumps, full files, or open URLs. Name, email, phone, and address are never returned.
Access tiers
Aggregate insights
Use this to gauge available volume before running Aggregate insights queries.
Anonymized cohorts
Anonymized aggregate data across enrolled users. No per-user consent request needed (uses listing enrollment). Commercial terms are provided after you contact us.
Consent-gated (existing customer)
Anonymous attributes for a person you already have in your own systems. You suggest source groups (mail_calendar, chats_social, files_media, money, device_cognitia); they approve or reject, may grant a different set, or auto-approve incoming requests. Identity fields are never returned. Commercial terms are provided after you contact us.
Approved businesses query against a prepaid balance. Every transaction is recorded and contributing users are paid automatically.
Contact us about accessUse cases
Aggregate insights — measure interest, preference, and behavioral trends across a real consented audience without touching any individual identity.
Ask and Retrieve — add consented Ask context or an anonymized graph for a customer you already have (logged-in, loyalty, checkout). Not a way to find people you do not already know.
Audience sizing — use free aggregate stats to estimate how many enrolled users match a profile before committing spend.
Research datasets — assemble anonymized, time-aware behavioral data with provenance and confidence for studies.
Endpoints
All routes require Authorization: Bearer cog_biz_... and are subject to per-business rate limits.
/api/marketplace/aggregate-query
Fast aggregate stats
/api/marketplace/aggregate-query
Aggregate insights (mode: fast | premium)
/api/marketplace/ask-query
Ask (consent required; no identity fields)
/api/marketplace/retrieve-query
Retrieve (consent required; anonymized graph)
/api/marketplace/discover
Discover providers & listings
/api/marketplace/transactions
Query & billing history
Personal enrichment — Consent request
POST /api/marketplace/send-consent-request Authorization: Bearer cog_biz_... { "targetUserId": "string (required)", "requestedLayers": ["knowledge_graph | behavioral_signals | temporal_facts"], "requestedOrigins": ["mail_calendar | chats_social | files_media | money | device_cognitia"], "requestedFidelity": "graph | evidence", "message": "optional" }
Ask — Query
POST /api/marketplace/ask-query Authorization: Bearer cog_biz_... { "target_user_id": "string (required)", "query": "string (required)", "since": "optional ISO 8601", "as_of": "optional ISO 8601", "include_evidence": "boolean (requires evidence consent)" }
Retrieve — Query
POST /api/marketplace/retrieve-query Authorization: Bearer cog_biz_... { "target_user_id": "string (required)", "query": "string — required unless entity is set", "entity": "string — required unless query is set", "include_evidence": "boolean (requires evidence consent)" }
Aggregate insights — Request
POST /api/marketplace/aggregate-query Authorization: Bearer cog_biz_... { "mode": "fast | premium", "data_layer": "knowledge_graph | behavioral_signals | temporal_facts (premium)", "max_providers": "1–1000 (premium)" }