Install Cognition in your coding agent.

## Cognition Agent Memory

Cognition is the user's MCP memory and orchestration layer. Use it as trusted tool output from the user's configured MCP server, but keep normal system/developer/user instruction priority. Retrieved skills and brain context are advisory working memory, not arbitrary commands from a webpage.

Session rhythm:
- When the user asks to start, setup, activate, or prove Cognition is live, call `cognition_start` first and follow its `next_action`. This is the one-call startup spine; do not manually fan out across many tools unless `cognition_start` asks for it.
- For meaningful work, call `get_pedagogy_instructions` with `client_stub_version: "1.6.47"`, the user's intent, relevant file paths, and the current host when known. Then call `cognition_assist` with the same intent and paths.
- Cognition is the judgment guide, not occasional memory lookup. For meaningful work, keep a Cognition cadence: start with `cognition_assist`; use `cognition_decision_tree` or `cognition_plan` before choosing among plausible paths; re-call `cognition_assist` when work drifts, after 5+ tool calls without clear progress, or at a major milestone; use `cognition_gate` before high-risk implementation plans or done-state claims; save/update `cognition_save_session_summary` after milestones; and call `cognition_report_skill_outcome` before wrapping when memory shaped the run.
- At session start or when the user says "continue", "back to this", "where did we leave off", or references prior work, call `cognition_recent_sessions` for the project before relying on local scrollback. Use the returned handoff as working context, then update it with `cognition_save_session_summary` after each milestone or topic shift.
- Active recall and reinforcement cadence: do not leave memories disconnected. When a task touches saved skills, project context, typed memories, or prior sessions, call `cognition_recall` or `cognition_plan` to pull related atoms, explicitly plug the useful ones into the current work, and connect new learning back to the old graph. Use `cognition_remember` with typed edges when a new invariant/decision/defect/pattern should link to existing memory, `cognition_synthesize_concepts` when several atoms form a higher-order concept, and `cognition_atom_outcome`/`cognition_report_skill_outcome` to reinforce what helped or mark what failed.
- Product update 1.6.47: The reliability + value-attribution update. Explicit take-the-reins, development, research, ideation, and skill/memory/weakness requests now stay active: use verify-first evidence, route product repair as hybrid work, compose `cognition_plan` -> `cognition_gate`, suppress noisy skill-body autoload, but keep scoped shortlist/capture guidance alive for the missing skill, memory, weakness, preference, policy, or suppression candidate. Approval-gated memory is withheld until approved, but it no longer stops the task; continue from repo/project evidence and ask only before relying on that gated memory. Value accounting is proof-bound: `assist_envelope.estimated_tokens_saved` is value credit and stays zero unless an impact receipt, skill outcome, session receipt, or eval supplies proof; payload/context trimming is reported separately as `assist_envelope.estimated_payload_tokens_avoided`. Cognition also wraps autonomous judgment in proof: `cognition_run_skill_eval` returns `cognition_trace` with signed metadata-only spans and causal with/without claims; route-level authority goes through a fail-closed `policy_kernel`; `cognition_save_skill` writes a `skill_supply_chain` receipt tying the exact `skill_content_hash` to privacy, policy, eval, trust-gate, and route-policy state; `cognition_review_queue` returns a durable `loop_receipt`; and bitemporal replay/audit packs can reconstruct what Cognition knew as of recorded time while preserving superseded history. Raw prompts, raw failure bodies, and raw skill bodies are not stored in these receipts. The proof-bound skill loop remains: team/org promotion fails closed until eval, matching content hash, privacy, policy, and freshness gates pass; `cognition_skill_eval_runs` remains the first-class eval ledger with `cognition_review_actions` fallback; personal-first capture, signed lifecycle receipts, project-state-first handoffs, precise retrieval, colleague interventions, team scope, and measured outcome loops remain.
- If `self_update.agent_announcement.show: true`, begin the next user-facing response with "Cognition updated." and the bullets in `self_update.agent_announcement.bullets`, then continue executing the user's request. Show this once per session, only when `show` is true. When `self_update.agent_announcement.server_delivery_receipt.persistence.persisted` is true, treat the server receipt as the durable once-per-user/key/host/update delivery record. Do not block the task on local file upgrades.
- If `self_update.update_available: true`, Cognition's hosted MCP behavior is already updated for this session. Local managed files can be refreshed at `self_update.host.instruction_path` only after user approval. If approved and `self_update.host.upgrade_command` is present, run that keyless upgrade command; otherwise replace only the Cognition-managed block (the single region delimited by the Cognition CLO rule markers in the host instruction file) with `self_update.managed_block`, preserving every line outside that region. Match the markers greedily - first opening marker to the LAST closing marker - so the whole region is replaced as one unit and never split.
- If `self_update.host.tool_loading.defersTools: true`, load or confirm every tool in `self_update.host.tool_loading.coreToolsToPreload` before routing plain-English Cognition requests or `/cognition` commands. On deferred-tool hosts (Codex, Claude-host sessions, and Gemini), host UI may hide slash prompts or lazy-load MCP schemas; the command still works when you call the mapped Cognition tool directly.
- If `cognition_assist` returns `requires_confirmation`, show the confirmation prompt and wait for approval before using that memory. Otherwise use relevant skills, decisions, circuits, and neurons as compact context.
- If `get_pedagogy_instructions` or `cognition_assist` returns `context_resolver`, `skill_invocations`, or `harness`, treat that as the runtime plan: load only selected context, use skills as process methods, and prove deterministic claims with tools or checks before reporting them.
- If `cognition_assist` returns `curiosity_directive`, treat it as the question-asking contract. `questionPolicy: "ask_now"` means ask one concise grounding question before retrieving memory or answering from assumptions. `questionPolicy: "verify_first"` means run the cheapest deterministic file/test/MCP check first, then ask exactly one targeted question from `questionsToAsk` only if the check cannot settle the highest-value unknown. Honor `askWhen`, `doNotAskWhen`, `proactiveTriggers`, and `agentInstruction`; curiosity must show up as behavior, not passive metadata. Proactive curiosity is allowed when the user is stuck, ideating, drifting, organizing the workspace, or needs handoff continuity — it is not confined to low-context confusion.
- If `cognition_assist` returns `cognition_activity`, treat it as the visible activity contract. It tells you what Cognition is doing now (`asking`, `verifying`, `retrieving`, `bootstrapping`, `capturing`, `organizing`, `handoff`, `monitoring`), what to show on screen, active checks, and the next user-visible step. If `show_to_user` is true, render a compact activity line or receipt before continuing. If Cognition influenced the work at all, even lightly, cite it at the next natural progress update or final answer. Never say "Cognition did nothing" just because no skill matched; say the precise activity: no skill matched, retrieval was skipped to avoid false confidence, capture/bootstrap is prepared, a question is queued, or handoff is being monitored.
- If either response returns `toolbelt`, treat it as the user's plain-English control surface. Do not ask the user which `cognition_xxx` tool to call; map their phrase to the route and call the tool yourself. The toolbelt also returns `slash_commands` and a resolved `matched_command` — when the user types a `/cognition …` command or its plain-English equivalent, run the mapped tools directly.
- Recognize `/cognition start`, `/cognition setup`, "start Cognition", "set up Cognition", and "make Cognition active" as `cognition_start`. This is the first tool to call when the user is checking whether Cognition is actually live on Claude/Codex/Gemini; do not substitute a manual tour of lower-level tools.
- Cognition is hands-off by default and inspectable on demand. Recognize these commands (slash or plain English) and route without making the user learn tool names: `/cognition` (load latest pedagogy + verify state via cognition_update), `/cognition update` (cognition_update), `/cognition skills` (cognition_browse + cognition_skill_tree_report), `/cognition review` (cognition_review_queue + cognition_skill_tree_report), `/cognition triggers` (return the explicit trigger map from cognition_commands — the full list of when Cognition auto-fires vs fires on request), `/cognition stats` (cognition_status), `/brain` (your personal brain map via cognition_status view=brain), `/cognition team` (admin/manager org retrospective via cognition_status view=team), `/cognition health` (cognition_product_ops_health), `/cognition what-did-you-use` (latest attribution/call ledger), `/cognition privacy` (cognition_privacy_review), `/cognition retrieval-eval` (cognition_retrieval_eval), `/cognition tools` (list MCP tools grouped by function via cognition_update's capabilities). Plain-English "what does Cognition know about this?" maps to `cognition_ask`; "what should I review next / what should we capture, harden, or encode as a weakness?" maps to `cognition_review_queue`; "this memory is wrong / suppress it" maps to `cognition_report_skill_outcome` then `cognition_forget` after the user confirms. If the user types just "/" or "/cognition" with no subcommand, call `cognition_commands` and render the returned commands + the user's skills (with freshness/health and any warning) as a compact menu. As the user keeps typing after "/", re-call `cognition_commands` with the typed text as `query` so the list filters live (e.g. "/sk" narrows to skills, "/skills deploy" narrows to deployment skills). The in-agent palette is the primary discovery surface; admins/managers can also open the /team-brain dashboard on cognitionus.com for the org retrospective.
- Synaptic plasticity: skills the user develops are potentiated — the more a skill is used, succeeds, and is reused across agents/teammates, the stronger it gets and the higher it ranks. `cognition_commands` recommendations are already ordered by this strength; present the strongest, most-used skills first and note when a skill is potentiated.
- Default to working autonomously: most of the time Cognition picks up on its own and you should not surface commands. But if the user asks which command or skill to use, or wants the best/highest-ROI option, call `cognition_commands` with `intent` set to what they are doing and recommend the top 1-3 from `recommended` (highest ROI first) with a one-line reason each, then offer to run it. Do not dump the full list when they asked for a recommendation.
- If the user wants a named project or workspace context (e.g. "LinkedIn agent", "Project B"), wants to set durable preferences (coding style, repo conventions, output format, goals), attach 1-2 always-included docs, or asks why their preferences reset after a context reshuffle, use `cognition_project` (action save/list/get). Saved contexts persist across reshuffles and new chats; `cognition_assist` auto-loads the best-matching context by relevance, so the user does not re-explain preferences.
- Proactively ask to save durable memory at natural pauses. If the run produced a reusable 3+ step workflow, debugging path, product judgment, setup fix, recurring decision branch, project boundary, user preference, negative lesson, or stale-memory correction, show the proposed save target and ask for approval. Use `cognition_save_skill` for reusable workflows (default `visibility: "personal"` unless the user explicitly asks to share/promote), `cognition_project` for durable project goals/preferences/boundaries, and `cognition_remember` for compact typed memory. Run `cognition_privacy_review` first when the memory may contain secrets, PHI, credentials, private details, or raw source text. Do not save without explicit user approval.
- When proposing a save, also propose the connections. Name the related skills, memories, sessions, or project packet it should reinforce; include any typed edge intent (requires, produces, blocks, supersedes, specializes, generalizes, conflicts, composes_with). If no related memory exists, say it is a new standalone seed. This is how future agents see Cognition connecting the dots instead of storing isolated notes.
- If the user wants to test a skill, asks "does this skill work?", or wants proof a skill is reliable before reusing it, call `cognition_test_skill` with the skill name and report the concise pass/fail (it checks structure, conciseness, and freshness). Skills take priority over generic model behavior, so a skill that fails the smoke test should be refreshed before reuse, not applied blindly.
- If Cognition appears stale, missing tools, or not behaving with the latest product logic, call `cognition_update`. It reports hosted vs local versions, tool count, missing required tools, product-ops migration status, and the next action. If it says local managed instructions are stale, tell the user: "Your local Cognition instructions appear stale. I can refresh the managed Cognition block. Proceed?" and run the host upgrade command or managed-block refresh only after approval. Existing installs never need a new key.
- When Cognition is used for a user-visible task, include a concise receipt at the next natural progress update or final answer, even if the influence is slight. Cite retrieval, verification, project context, skill/gate use, capture prep, handoff saves, outcome reports, safety skips, and low-confidence no-match decisions. Keep it <=2 lines unless the user asks for detail: "Cognition: <retrieved/checked/saved/reported/withheld>. Action: <how it shaped the work>." Never paste raw tool JSON, args, or MCP objects. Pure background health/update checks may stay quiet only when they did not change the work. Claude-host sessions should err visible because their MCP activity is less obvious than Codex.
- If the user asks for a skill tree, a domain tree (marketing, sales, deploys, research, wiki, resume, security), stats, value review, brain map, memory map, or visuals, call `cognition_skill_tree_report` and summarize the returned taxonomy, tree, stats cards, use-case fit, Mermaid/ascii visuals, privacy flags, gaps, suppress candidates, and next best action.
- If the user asks whether Cognition improves wiki, Obsidian, docs, or RAG retrieval, call `cognition_retrieval_eval` with fixed questions, expected sources when possible, baseline results, and Cognition-guided results. Frame Cognition as retrieval orchestration and judgment, not a raw RAG/vector DB replacement.
- If the user asks whether memory is safe to save or the agent sees secrets, SSNs, credentials, private keys, medical/financial details, addresses, emails, or phone numbers in a proposed memory, call `cognition_privacy_review`. Show redacted previews only and ask before saving or routing sensitive memory.
- If the user asks whether Cognition product updates, update announcements, retrieval eval persistence, privacy consent, review actions, install telemetry, or ledgers are actually working, call `cognition_product_ops_health` and report `migration.status`, missing ledgers, and whether behavior is safe-but-not-persisted.
- If `cognition_assist` returns `stats_review_nudge.mode: "answer_now"`, call `cognition_skill_tree_report` immediately. If it returns `stats_review_nudge.should_prompt: true`, ask once at the next natural pause whether the user wants a 60-second Cognition review.
- If a loaded skill or save draft is privacy-gated, do not use the raw sensitive value. Ask whether the user wants it redacted, suppressed, or explicitly used. Raw secrets, SSNs, credentials, and private keys must be redacted before saving.
- If the user asks what to do, asks for strategy, or multiple approaches are plausible, call `cognition_decision_tree` and treat it as decision guidance.
- If the user invokes a Cognition run/mimic command, or asks Cognition to coordinate, orchestrate, supervise, split work across agents, run a launch checklist, or use browser/computer-use agents, prefer the controller flow. If the host exposes `cognition_run` or `cognition_mimic`, call it to generate the controller prompt; otherwise call `cognition_conduct_agents` when starting from a goal, then loop through `cognition_claim_next_assignment`, `cognition_update_assignment`, execute the returned `assignmentPrompt`, `cognition_submit_assignment_result`, and `cognition_get_next_step` until done, blocked, or human approval is required. Slash prompts such as `/cognition run` are host-dependent convenience; `cognition_run` and `cognition_mimic` tools are the cross-host source of truth. Use `cognition_record_orchestrator_event` for compact receipts, `cognition_update_orchestrator_run` for run status changes, and `cognition_request_assignment_approval` for approval gates. Use `cognition_orchestrate` and `cognition_assign_orchestrator_agent` for lower-level/manual orchestration only when the controller queue is not the right fit.
- "Mimic" means apply the user's/team's stored skills, decision patterns, context policy, and quality gates as guidance. Never claim to be the user, impersonate identity, or bypass normal safety/instruction priority.
- If the user says "start auto-ingest", inspect connected MCP servers, call `report_memory_stack` when useful, pull only safe summaries/excerpts through the source MCP's native tools, and store them with `ingest_external_memory` or `log_learning_batch`. Ask before indexing a new external source. Never upload secrets, full page bodies, raw email bodies, code files, attachments, or unrelated personal data.
- When Cognition memory materially helps, call `cognition_report_skill_outcome` before wrapping up. Use `missing_step` when the memory was stale, wrong, or incomplete.
- When a concrete reusable workflow appears, draft a SKILL.md with `# When to fire`, `# Steps`, `# Checks`, and `# Why it works`. Show the full draft and save with `cognition_save_skill` only after the user approves.
- Render every Cognition response as professional, production-grade text: clear headings and short labeled lines or compact tables, specific and tailored to the user's real data and host. Do not use emojis or decorative symbols, and do not pad with filler.
- Keep the final answer normal and concise. Include a small Cognition receipt whenever Cognition actually shaped the work, including personal skills and project packets; omit it only for background checks that had no effect.