cognitive-ai-cli

Memory + discipline for AI coding agents. Cross-session memory backed by GitHub, and harness-enforced capture hooks so agents actually persist their work — not just promise to.

Works with Claude Code, Cursor, Codex, Aider, Cline, Windsurf. GitHub is the primary memory store; local disk is the working cache + offline fallback.

npm install -g cognitive-ai-cli
cognitive-ai setup        # guided one-time: pick store path, GitHub repo, license

The CLI binary is cognitive-ai. Short wrappers cogboot, cogcap, cogscout are installed into ~/.local/bin.

What problem this solves

AI coding agents (Claude Code, Cursor, Codex, etc.) lose all context between sessions. The standard "fix" is CLAUDE.md / AGENTS.md text that asks the model to capture its work — and it almost never does, because nothing enforces it.

cognitive-ai-cli plants two layers:

1. Local memory store — ~/.local/share/cognitive-ai/, backed by a private GitHub repo, with a daily session file, an INDEX.md, project files, decisions, and learnings.
2. Harness-enforced hooks — Claude Code settings.json is updated with:
   • SessionStart → cogboot (loads memory before the model starts working)
   • PostToolUse on Edit|Write|MultiEdit → cogcap-counter (after N edits without an intervening capture, emits a COGAI_CAPTURE_REMINDER system-reminder that the model cannot silently ignore)
   • Stop → cogcap-auto-stop (auto-captures any uncaptured edits before the turn ends)
   • Stop → cogjars-push (auto-commits and pushes a configured jars repo)

Discipline lives in the harness, not the model.

Install

npm install -g cognitive-ai-cli

The global install runs a non-interactive bootstrap that plants steering files and hooks immediately. Then run guided setup:

cognitive-ai setup

It asks where to store memory and offers three explicit modes:

1. Local + private GitHub sync (recommended)
2. Local offline only
3. Bring-your-own Git remote

For GitHub sync, it asks which private repo to use or create, manages an SSH key, and tries to add it to GitHub automatically through gh api. If GitHub CLI is missing the required scope, it falls back to showing the public key and opening the SSH-key approval page.

GitHub sync is privacy-gated: cognitive-ai refuses to push memory to a GitHub remote unless gh repo view <owner>/<repo> --json isPrivate proves the target is private.

Commands

| Command | Purpose | |---|---| | cognitive-ai init | Scaffold the memory store, init git, optionally configure GitHub remote, commit, push if private remote verified | | cognitive-ai setup | Guided GitHub-backed setup | | cognitive-ai install | Re-run only the agent integration (repair Claude, Cursor, Codex, wrappers, hooks) without reinitializing memory | | cognitive-ai boot (or cogboot) | Pull GitHub-backed store, ensure today's session exists, regenerate INDEX.md | | cognitive-ai capture "summary" (or cogcap "...") | Write a work summary, regenerate INDEX.md, commit, push if verified-private remote | | cognitive-ai scout search "..." (or cogscout search "...") | Transparent GitHub Code Scout — finds production-ready references, license-filtered, writes reports to .scout/reports/ | | cognitive-ai auth github | Open the GitHub sync authorization flow | | cognitive-ai doctor | Diagnose installation health | | cognitive-ai uninstall | Remove agent integration + wrappers |

Forcing-function hooks (the discipline part)

Installed automatically into ~/.claude/settings.json. Three new shell wrappers land in ~/.local/bin/:

cogcap-counter (PostToolUse, Edit|Write|MultiEdit)

Increments an edit counter at ~/.local/share/cognitive-ai/.state/edit-counter. When it hits the threshold (default 8, override with COGAI_CAPTURE_THRESHOLD) and no cogcap has happened recently, the script writes to stdout:

COGAI_CAPTURE_REMINDER: 8 edits since the last cogcap. Run `cogcap "<short summary>"`
to persist this work block before continuing. Recent files: foo.py,bar.py,...

That message lands in the conversation as a system-reminder. The model has to acknowledge it. Half-resets so it nudges again if ignored.

cogcap-auto-stop (Stop)

Reads the recent-edits log. If unrecorded edits exist and no manual cogcap has happened in the last 60s, fires cogcap "auto-capture on session stop: edited N files (...)". No work block disappears between sessions.

cogjars-push (Stop)

If $COGAI_JARS_REPO (default ~/jars) is a git repo with uncommitted changes, commits with an auto message and pushes. Silent no-op if no jars repo configured.

cogcap (stamping variant)

The cogcap wrapper installed by cognitive-ai install records the last-capture timestamp + clears the recent-edits state, so the counter knows when a manual capture has happened.

Configuration

| Env var | Purpose | Default | |---|---|---| | COGAI_CAPTURE_THRESHOLD | Edits before counter trips | 8 | | COGAI_JARS_REPO | Path to jars repo for auto-push | ~/jars | | COGAI_BIN_DIR | Where short wrappers are installed | ~/.local/bin | | CLAUDE_CONFIG_DIR | Where settings.json lives | ~/.claude | | COGAI_PROJECT_ROOT | Project root for CLAUDE.md/AGENTS.md injection | $PWD | | COGAI_NO_AUTO_HOOK=1 | Skip the postinstall bootstrap | unset | | COGAI_DEV=1 | Local-dev mode (bypass licensing checks) | unset |

Local smoke test (dev workflow)

COGAI_DEV=1 node dist/cli.js init --store /tmp/cogai-demo --local --no-inject
COGAI_DEV=1 node dist/cli.js boot --store /tmp/cogai-demo
COGAI_DEV=1 node dist/cli.js capture "first local proof" --store /tmp/cogai-demo

What ships in the store

• BOOT.md, INDEX.md, CHARACTER.md
• sessions/YYYY-MM-DD.md (one per day)
• projects/<name>.md
• decisions/<slug>.md
• learnings/<slug>.md
• Backed by a private GitHub repo when sync is on

Status

v0.2.x — adds forcing-function hooks for capture-during-work. Earlier v0.1.x shipped the storage + CLI + multi-agent injection layer. License verification is API-shaped and supports development mode via COGAI_DEV=1 until the Cognitive AI API + Lemon Squeezy integration are live.

License

BSL 1.1 — see LICENSE.