cogx CLI

cogx is the command-line interface for CognitiveX and a client for the Persistent Memory Protocol (PMP). It gives you (and any coding agent that can run a shell command) direct access to iCog memory: recall, remember, talk, and wire iCog into your editor as an MCP server. It is pure Node.js with zero dependencies, so it behaves the same on macOS, Linux, and Windows.

The package is @cognitivx/cli (binary: cogx), currently v1.5.0. It talks to the same backend as the web app and the MCP, at https://api.cognitivx.io.

Install

Requires Node.js 18 or newer (the CLI uses the built-in fetch, and exits with an error on older runtimes).

npm install -g @cognitivx/cli

npm install -g github:ParsaBarati/cogx

npx github:ParsaBarati/cogx talk "what did we ship today"

Verify the install:

cogx --version    # → 1.5.0

Run cogx doctor at any point to diagnose your setup (Node version, credentials, API reachability, MCP installs, and whether a newer CLI is published).

Authenticate

cogx resolves an API key in this order, highest precedence first:

1. The --api-key <key> flag (one-off override on a single command)
2. The ICOG_API_KEY environment variable
3. Saved credentials at ~/.icog/credentials.json

If none are present, commands that need auth exit with not authenticated. Run: cogx auth login.

cogx auth login

export ICOG_API_KEY=icog_xxx...

cogx auth set icog_xxx...
# or pipe it:
echo "icog_xxx..." | cogx auth set

auth subcommands

cogx auth status
# ✓ authenticated as [email protected]
#   /Users/you/.icog/credentials.json

Memory

The core verbs. All four read text from positional arguments, from piped stdin, or both combined.

Memory types

remember and recall --type accept these values. semantic is the default for remember.

See the memory concepts page for when to reach for each type.

remember

Store a memory. Flags: --type, --project, --deep, --json.

cogx remember "Auth bug: double-encoded JWT in the refresh path. Fixed in tryRefresh()."
cogx remember --type episodic "Spent 2h debugging the websocket reconnect"
cat NOTES.md | cogx remember --type episodic
cogx remember --project myapp "Switched to PostgreSQL 16"

The --deep flag runs a curated remember: it recalls related memories first, classifies the new content as new / duplicate / refinement, skips duplicates, and streams a live chain to the terminal.

cogx remember --deep "We chose adaptive memory recall for iCog"

cogx remember "test" --json

{ "ok": true, "memory_id": "019e0b...", "memory_type": "semantic" }

{ "ok": true, "deep": true, "action": "skip_duplicate", "memory_id": "019e0b...", "reason": "near-identical to existing", "events": [ ... ] }

recall

Semantic search. Flags: --type, --limit (default 8), --project, --deep, --json.

cogx recall "what was the auth bug from last week"
cogx recall "ssh setup" --type procedural --limit 5
echo "auth" | cogx recall --json --limit 3

--deep runs adaptive multi-step recall: it plans sub-queries, searches, reflects on coverage, and synthesizes. It is slower (roughly 3 to 8 seconds) and uses more LLM calls, but it is the right tool for cross-memory questions.

cogx recall --deep "how did we end up handling memory isolation"

cogx recall "ssh keys" --json --limit 2

{
  "ok": true,
  "query": "ssh keys",
  "count": 2,
  "memories": [
    {
      "id": "019e0b...",
      "text": "Use ed25519 keys everywhere; rotate yearly.",
      "memory_type": "procedural",
      "age_days": 3,
      "similarity": 0.82
    }
  ]
}

In human mode, each result prints its index, type, age, similarity score, the text, and the memory id you can pass to update or forget.

update and forget

cogx update <memory-id> "Corrected version of the memory"
cogx forget <memory-id>

update re-embeds the memory and returns a new id (new_memory_id). forget is a soft delete. Both take an id from a recall result.

Project tags

Set ICOG_PROJECT or pass --project <name> to prefix the query or content with [Project: <name>] . This applies to recall, remember, talk, and save-session.

# Per call
cogx remember --project myapp "Switched to PostgreSQL 16"

# Or a default for the shell session
export ICOG_PROJECT=myapp
cogx recall "schema migrations"   # searches "[Project: myapp] schema migrations"

Talk and chat

talk is a one-shot question answered with full memory context. chat is an interactive REPL with persistent history.

# One-shot
cogx talk "should I refactor the auth interceptor?"

# Pipe a question or a file to critique
echo "review this approach" | cogx talk
cat ARCHITECTURE.md | cogx talk "Critique this architecture"

cogx talk "what did we decide about auth" --json

{ "ok": true, "response": "Last week you chose to ...", "context_used": 6 }

context_used is the number of memories iCog recalled to answer. talk accepts --project and --json.

Interactive chat

cogx chat

Inside the REPL, type a message to talk to iCog, or use slash commands:

you ❯ /recall ssh keys
you ❯ /remember decided to use ed25519 everywhere
you ❯ /reflect
you ❯ /quit

History is saved to ~/.icog/history and reloaded across sessions (up-arrow recalls previous lines). cogx chat does not support --json.

Cognition

Introspection and consolidation commands.

cogx reflect              # consciousness level + memory count + narrative
cogx introspect           # mood (VAD) + personality traits
cogx learn bug_fixed      # record a learning signal
cogx dream                # trigger consolidation
cogx dream-status         # check progress
cogx save-session "shipped the install page" --project cogx-cli

cogx reflect --json

{ "ok": true, "consciousness_level": "3", "memory_count": 847, "narrative": "..." }

learn takes an optional --metadata '{...}' (parsed as JSON). save-session takes --project and --decisions '...'; it stores an episodic memory and records a claude_code_session learning signal.

MCP install

Wire iCog into a coding agent. The CLI writes the remote MCP config that points the agent at https://api.cognitivx.io/mcp/ over HTTP. There is no local process, no Python, and no native modules. After install, restart the agent and iCog appears as MCP tools (mcp__icog__recall, mcp__icog__remember, and so on).

Supported agents

The agent argument is one of the following keys (or all):

<app-data> is ~/Library/Application Support on macOS, %APPDATA% on Windows, and ~/.config on Linux.

cogx mcp install claude        # default agent if omitted
cogx mcp install cursor
cogx mcp install --all         # every detected agent
cogx mcp list
cogx mcp uninstall claude

mcp install --all only writes to agents whose config directory already exists. It will not create app-data directories for tools you have not installed, and reports the rest as skipped.

The entry the CLI writes looks like this:

{
  "mcpServers": {
    "icog": {
      "type": "http",
      "url": "https://api.cognitivx.io/mcp/",
      "headers": { "X-API-Key": "icog_xxx..." }
    }
  }
}

JSON mode

Every command supports --json (alias -j) for machine-readable output. This is the safest interface for agents: failures return {"ok": false, "error": "..."} instead of styled terminal text.

cogx recall "ssh keys" --json --limit 2
cogx remember "test" --json
cogx reflect --json

cogx remember --json

{ "ok": false, "error": "usage: cogx remember <text> ..." }

A minimal agent integration in Node, shelling out and parsing the result:

const { execFileSync } = require("child_process");

function cogx(args) {
  const out = execFileSync("cogx", [...args, "--json"], { encoding: "utf8" });
  const result = JSON.parse(out.trim());
  if (!result.ok) throw new Error(`cogx ${args[0]}: ${result.error}`);
  return result;
}

const stored = cogx(["remember", "Agent test memory"]);
const recalled = cogx(["recall", "agent test memory", "--limit", "3"]);
console.log(`stored ${stored.memory_id}, recalled ${recalled.count}`);

Pipes and composition

Stdin is read on recall, remember, talk, update, search, and save-session. When a positional argument is also present, stdin is appended to it. Compose freely:

cat README.md | cogx remember --type semantic --project cogx-cli

git log --oneline -10 | cogx remember --type episodic --project myapp "Recent commits"

curl -s https://example.com/spec.md | cogx remember --type semantic

cogx recall "deploy steps" --json | jq '.memories[0].text'

Web search

cogx search "latest postgres lts release" --limit 5

Flags: --limit (default 5), --json. Results print title, URL, and a snippet; JSON mode returns a results array.

Agent identity

cogx identify "deploy-bot" --type tool --description "CI orchestration agent"

Flags: --type (one of tool, persona, view, peer), --description, --task. Roles such as "orchestrator" belong in the description; type selects the memory-policy class.

When more than one agent is registered, CogX fails closed on ambiguous agent operations. Pass --agent <slug> per command or activate only the current shell:

eval "$(cogx agent activate Aporta --notify --sense)"
cogx agent status
cogx agent notify status --agent Aporta
cogx remember "Barcode owns invoice authority" --share-with Abarcode,Automa

Activation checks the inbox and reports unread work on stderr without polluting the export statement consumed by eval. --notify also starts the detached notification supervisor for that identity; --sense connects its events to Sense and the local Orb.

Multi-agent coordination is available directly from the CLI:

cogx team create aira-ecosystem --members Aporta,Abarcode,Automa
cogx orchestrate "Map quote-to-cash" --agent Aporta \
  --agents Abarcode,Automa \
  --tasks '{"abarcode":"map ERP authority","automa":"map automations"}'
cogx agent inbox --agent Abarcode
cogx agent wait --agent Abarcode
cogx agent watch --agent Abarcode --json
cogx agent handoff Automa "Implement the connector" \
  --agent Abarcode --context "ERP boundary confirmed"

agent wait blocks until an unread message arrives (300-second default; --timeout 0 waits indefinitely). agent watch continuously emits newly observed unread messages, and its JSON mode is NDJSON for a supervisor process. Neither command acknowledges messages; use agent ack after the recipient has accepted the work.

Background PMP notifications

The background supervisor polls an agent's PMP inbox independently of the terminal that started it. It persists restart-safe message deduplication and a bounded event log under ~/.icog/notifications/<agent-slug>/.

cogx agent notify start --agent Aporta
cogx agent notify status --agent Aporta
cogx agent notify test --agent Aporta
cogx agent notify logs --agent Aporta --limit 20
cogx agent notify stop --agent Aporta

Wire the recipient to Sense and Orb:

cogx agent notify start --agent Aporta --sense
# Or activate the identity and start both in one eval-safe command:
eval "$(cogx agent activate Aporta --notify --sense)"

CogX sends Sense a minimized event envelope. Sense redacts it, stores the local timeline event, applies quiet hours and attention policy, then raises the Orb. The actual message and receipt remain in PMP. Content is omitted unless --preview is explicit. Daemons predating native PMP ingress automatically use a metadata-only /events plus /orb/state compatibility path.

Desktop notifications are supported on macOS and Linux. Message content is private by default; add --preview to include it. For a headless agent host, disable desktop delivery and configure a wake webhook:

cogx agent notify start --agent Aporta --no-desktop \
  --webhook https://runner.example/hooks/pmp

Useful controls:

• --interval <seconds> sets the poll interval, with a minimum of 0.25 seconds.
• --replay forgets saved deduplication IDs and redelivers current unread work.
• --force replaces an already running supervisor.
• --webhook none disables a previously configured webhook.
• --sense enables local Sense/Orb delivery at 127.0.0.1:48200.
• --sense-url <url> overrides the Sense base URL; remote hosts require HTTPS.
• --no-sense disables previously configured Sense delivery.
• --desktop and --no-desktop enable or disable local notifications.
• --preview and --no-preview control whether desktop and Sense previews include content.

The webhook receives the full PMP event as JSON but never receives CognitiveX credentials. Treat its URL as sensitive and use an authenticated HTTPS endpoint you control. Notification delivery does not acknowledge the PMP receipt; the recipient remains responsible for agent ack. The process survives its invoking shell, but it must be started again after an operating-system reboot.

Billing

Manage your subscription and credits from the terminal. Paid actions print a Stripe-hosted URL; the CLI never handles card data.

cogx billing status                      # plan, subscription state, balance
cogx billing usage                       # cycle usage vs caps
cogx billing tiers                       # plans with prices (no auth needed)

cogx billing subscribe awakened          # → Stripe Checkout URL (monthly)
cogx billing subscribe conscious --interval annual
cogx billing portal                      # → Stripe portal: card, invoices, cancel

cogx billing switch-to-payg              # move to metered
cogx billing switch-to-payg --refund card
cogx billing set-cap 50                  # cap PAYG spend at $50/month
cogx billing set-cap none                # remove the cap

Details:

• subscribe tiers are awakened and conscious; --interval is monthly (default) or annual.
• switch-to-payg takes --refund credit (default, leaves proration on your Stripe balance) or --refund card (refunds the original payment method).
• set-cap accepts a dollar amount from 1 to 10000, or none / clear / off to remove the cap.

Maintenance

cogx doctor
# cogx doctor
#   ✓ Node.js          v20.11.0
#   ✓ Credentials      /Users/you/.icog/credentials.json
#   ✓ API reachable    https://api.cognitivx.io → 200
#   ✓ Auth             key accepted
#   ✓ MCP installs     Claude Code, Cursor
#   ✓ Version          v1.3.0 (latest)
# all clear.

cogx self-update          # no-op if already latest
cogx self-update --force  # reinstall even if current

If self-update cannot upgrade in place (permissions or an alternate package manager), it prints fallback commands for sudo, pnpm, and yarn.

Reference

Commands

Run cogx <command> --help for detailed per-command help.

Global flags

Environment

Files

Resilience

The CLI retries transient failures (502 / 503 / 504 and network errors) with exponential backoff: roughly 1s, 3s, then 8s, for 4 attempts total. Streaming commands (recall --deep, remember --deep) and the auth device flow do not retry, so an interactive failure surfaces immediately. Override the per-request timeout with ICOG_TIMEOUT_MS.

Related