Cognetivy: a local state layer for AI coding agent sessions

The problem Cognetivy targets, and the people it is aimed at

The README states the case plainly: AI coding agents are good at producing output, but their process is hard to inspect and hard to repeat. That is a real gap. A model call plus an editor gives you a result and a scrollback buffer; the steps that produced the result, and the order they happened in, are gone once the session closes.

Cognetivy's answer is to give the agent an operational layer with four named pieces: workflows, runs, events and collections. The README's own analogy treats the model as the brain, the editor as the workspace, and Cognetivy as the memory plus process manager. That framing sets the scope. This is not a model wrapper and not an editor plugin; it is the record of what the agent did and the definition of how it should do it.

The stated audience is narrow and worth repeating: people building repeatable local AI coding workflows, people running structured research tasks with coding agents, and teams that need traceability for local agent output. If your agent work is one-off prompting where you never revisit the result, none of those three apply and the tool adds a directory to your repo for nothing.

How the workspace, executor and studio fit together

The mechanism visible in the README is a local workspace plus a small local server. Running the CLI with no subcommand starts the local studio, which the README describes as an HTTP and WebSocket server, the bundled UI in your browser, and an executor that advances runs and nodes on your machine. So the graph you draw in the browser is not executed by a remote service by default; the executor that walks it runs locally.

State lands in a .cognetivy/ directory inside the project folder, which the README says is deliberate so state stays next to the repo. That choice is the most consequential thing about the design. It means the record of a run is versionable and diffable alongside the code it touched, and it also means every project you instrument gains a directory you have to think about in .gitignore.

Workflows are versioned objects. The README describes picking a template, applying it to a cloud workflow, or shaping a graph in the studio, and it lists workflow templates, apply-template and set current workflow as CLI operations. The CLI and the UI are said to stay in sync with the same workflow index and cloud workflow when you authenticate. Cloud sync is opt-in in the sense that it arrives with sign-in, but the README does not describe an offline-only mode in detail, so treat the local studio as the default path and sign-in as the feature that adds remote state.

Installing Cognetivy and starting a first workspace

Requirements come first: Node.js 18 or newer, and better-sqlite3 is bundled as a dependency, so expect native builds or prebuilds to apply the way they do for any project using it. On a machine without a working native toolchain, that dependency is the first thing that can bite.

The README gives two install routes. The one-shot route runs the package without a global install:

npx cognetivy

Or install it globally so the binary is available from any directory:

npm install -g cognetivy

cognetivy

The README says that running cognetivy from a project folder is the onboarding step. If you are not signed in yet, the CLI opens the app or the local studio so you can authorize once, and the API key is stored on your machine. A minimal workspace then appears under .cognetivy/. That is what you should look for after the first run: a new directory next to your source, not a config file you have to write by hand.

Once the studio is up, the workflow side is driven from the CLI. The README lists browsing built-in templates as workflow templates and materializing one as apply-template:

cognetivy workflow templates
cognetivy workflow apply-template

The quick reference also lists cognetivy run for starting and advancing runs, checking status, and stepping. The README does not spell out the exact flags for those subcommands; it points at cognetivy --help for the full tree, which is the honest place to look rather than guessing at an argument. For the same reason, the documentation command is worth knowing early:

cognetivy docs

That opens the CLI documentation in the browser. The README also notes an auth pair for cloud state, cognetivy auth login and cognetivy auth status, and an environment variable, COGNETIVY_API_KEY, as the non-interactive alternative.

Where Cognetivy is the wrong tool

The README is thin on failure modes, and that thinness is itself information. There is no documented rollback procedure for a run, no described conflict resolution when the same workflow is edited in the studio and from the CLI, and no stated migration path between workflow versions. If your team expects to change a workflow definition while runs are in flight, the README does not tell you what happens to the in-flight runs.

The .cognetivy/ directory is the second constraint. State living next to the repo is the selling point, but it also means the directory has to be managed: committed, ignored, or partially both. The README does not say which files inside it are safe to commit and which are machine-local, so that decision is yours to make by inspection.

The third case is scale. The description calls this a local workspace, and the executor runs on your machine. If what you actually need is a shared, server-side audit trail that several people query across many repositories, a local SQLite-backed workspace is the wrong shape for the problem, regardless of how good the workflow model is. The README mentions cloud sync when you sign in, but it does not describe multi-user permissions or a hosted query interface, so do not read the word cloud as a guarantee of team features.

Cognetivy compared with a plain agent transcript

The obvious alternative is not another product; it is the chat transcript and the editor's own history. That approach costs nothing and requires no directory. Its difference in kind, not degree, is that a transcript records text while Cognetivy records structure: a workflow definition, a run against that definition, events within the run, and collections holding the reasoning artifacts.

That structure is what makes re-running and comparing outcomes possible, per the README. A transcript can be replayed as text but not re-executed as a graph. The trade is that you now maintain a workflow definition, and a definition that drifts from what you actually want the agent to do is worse than no definition, because it produces a confident record of the wrong process.

A second alternative is the programmatic route. The package exposes a TypeScript and JavaScript API, with workspace helpers, models, config and validation exported from the main entry point, and the README shows the import shape:

import { /* workspace, models, … */ } from "cognetivy";

If you want to drive runs from your own tooling, that API is the path. The README notes that @cognetivy/core in the repository is built and synced into the published package, and that npm consumers typically install cognetivy only. So do not go looking for @cognetivy/core on npm expecting it to be the thing you depend on.

Maintenance, licence and the cost of upgrading

The repository is not archived, and the last push was on 2026-05-09. That is roughly four months before today, which is recent enough that the project is not abandoned, but it is not a signal of a fast release cadence either. No releases were retrieved, so there is no version history to read for breaking changes. The README calls the current line Cognetivy 2.0, which tells you a major version already happened and that the 1.x to 2.x transition is in the past rather than documented here.

Upgrade cost is therefore mostly unknown from the README. The repository root contains a CHANGELOG.md, so that file, not the README, is where to look before moving versions. The one concrete upgrade hazard the README does surface is the bundled native dependency, better-sqlite3: a Node upgrade or a platform change can force a rebuild, and that is the step most likely to fail on a fresh machine.

The licence is MIT, with the LICENSE file at the repository root. MIT is permissive, so redistribution and commercial use are broadly allowed, but this is not legal advice and the licence text itself governs. One practical consequence worth noting: the project also offers a hosted site at cognetivy.com and a cloud sync path behind sign-in. The MIT licence covers the code in the repository, not any hosted service, and the README does not describe terms for the cloud side.

Editorial conclusion

Adopt Cognetivy if you already run coding agents and keep losing the thread between chat sessions, and you want the record to sit in .cognetivy/ inside the repository rather than in a chat log. Do not adopt it if you need a hosted multi-user audit system or a pre-1.0 stability promise; the README documents no migration path between workflow versions. Verify two things first: that your Node.js is 18 or newer, since better-sqlite3 is a bundled native dependency, and whether the cloud sync path is acceptable for your code, because signing in with cognetivy auth login or COGNETIVY_API_KEY moves workflow state off the machine.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. meitarbe/cognetivy on GitHub
4. Project website
5. README