# cognetivy is local by default and needs the cloud for identity and templates

> An open-source state layer for coding agents, built as durable workflows, runs, events and collections with a local studio that runs the executor on your machine. The page names those four nouns and never defines them, the documentation lives behind a command that opens a browser, and the default command starts a local server.

**meitarbe/cognetivy** — The open-source state layer for AI coding agents. Turn chaotic agent sessions into structured, traceable workflows with a local workspace for runs, events, and collections.

- Repository: https://github.com/meitarbe/cognetivy
- Website: https://cognetivy.com
- Stars: 783 · Forks: 65
- Language: TypeScript
- License: MIT
- Published: 2026-09-15 · Updated: 2026-09-15 · Language: en
- Canonical page: https://hysenlabs.com/projects/meitarbe-cognetivy

## Four nouns are named and none of them are defined

The pitch is one sentence: durable workflows, runs, events and collections. Every other section on the page reuses those four words without ever giving one of them a shape, a field list or a file layout.

What the page does attach to each is an intent. Explicit workflows define how the agent should work. Runs and events track what happened in a session. Collections keep reasoning artifacts organized. A persistent local workspace lets you re-run and compare outcomes.

A fifth noun then appears unannounced. The executor is described as advancing runs and nodes on your machine, so nodes are part of the vocabulary a few paragraphs after the four nouns were introduced and never mentioned again. Combined with the studio's graph editor and the workflow versioning story, that implies nodes and versions are first-class, but neither the node record nor the version boundary is described anywhere on the page.

The comparison the page offers is the useful part: treat the model as the brain, the editor as the workspace, and Cognetivy as the memory plus process manager, with the claim that important context otherwise lives in chat history and disappears.

## The studio is local, identity and templates are not

The default mode is honest about where things run. With no subcommand, the CLI starts the local studio: a small server speaking HTTP and WebSocket, the bundled UI in your browser, and the executor that advances runs and nodes on your machine. A minimal workspace appears under `.cognetivy/`, described as keeping state next to your repo, and the API key is stored on your machine.

The cloud is where identity lives. If you are not signed in, the CLI opens the app or the local studio so you can authorize once, and you can also use `cognetivy auth login` or `COGNETIVY_API_KEY`. The auth commands report the cloud API key and the resolved URLs, which is a hint that several endpoints are involved.

Templates are on the other side of that line too. You pick a template, apply it to your cloud workflow, or shape a graph in the studio, and the page says the CLI and UI stay in sync with the same workflow index and cloud workflow when you are authenticated. So a local workspace, a local executor and a local store are paired with a hosted identity and hosted templates, and the one-sentence summary, cloud sync when you sign in, is doing the work of a boundary condition.

## The bare command starts a server and may open a browser

Two of the three install shapes end with the same wordless invocation, and that word carries the whole default behavior.

```bash
npx cognetivy
```

or, for use from any directory:

```bash
npm install -g cognetivy

cognetivy
```

Running it with no subcommand starts the local studio, and the quick reference adds that it also runs guided sign-in on first interactive use if needed. In practice that means one command starts a long-lived HTTP and WebSocket server, serves a browser UI, launches the executor, and may open a browser window to authorize. The difference between the two install shapes is where the binary comes from, not what it does: `npx` resolves the package at run time, while a global install keeps whatever version you installed, and the page gives no guidance on keeping the two in step.

For scripts, that distinction matters more than usual, since the default command is interactive. The page's own hint is to use `cognetivy --help` for the full tree, which implies the subcommands are the non-interactive surface.

## The documentation is a website, and the command table ends in ellipses

`cognetivy docs` opens the CLI documentation in the browser. Nothing else on the page is a manual.

The quick reference is five rows, and two of them are truncated on the page itself. `cognetivy workflow …` is glossed as list, create, get, templates, apply-template, set current workflow, followed by an ellipsis. `cognetivy run …` is glossed as start and advance runs, status, step. The remaining rows are complete: bare `cognetivy` starts the studio, `cognetivy auth login` and `auth status` report the cloud API key and resolved URLs, and `cognetivy docs` opens the documentation.

So the command surface a reader can reconstruct from the repository is five entries with two of them elided, and the authoritative version is on a site that this repository does not contain. There is no docs directory in the tree either: the root holds `.github/`, `.gitignore`, `CHANGELOG.md`, `CONTRIBUTING.md`, `LICENSE`, `README.md`, `cli/` and `core/`.

The programmatic surface is equally brief. The package exposes a TypeScript and JavaScript API of workspace helpers, models, config, validation and related utilities, entered through `main` in `package.json` rather than through a named export map, and the sample import carries only a comment.

## core/ is the source and cognetivy is the artifact

The repository is two directories, and only one of them is what an npm user installs.

`@cognetivy/core` is a package in the repository, and the page states it is built and synced into the published package for release, with npm consumers typically installing `cognetivy` only. The CLI binary is named `cognetivy` as well, so the executable, the npm package and the command all share one name while the source of truth lives under `core/`.

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

That split has a practical consequence for anyone tracking a fix. A change in `core/` only reaches an existing installation after the build and sync step and a new publish, so the version reported by an installed `cognetivy` reflects the last sync rather than the last commit. It is also why the entry point is described by pointing at a field in `package.json` instead of a documented export name.

For a project whose argument is traceability, it is worth noting that the audit trail the product sells covers agent runs, while the release trail of the tool itself is a changelog and a set of unversioned tags.

## A native SQLite binding is the real install requirement

The requirements section has two lines. Node.js 18 or newer, and a note that `better-sqlite3` is bundled as a dependency, with native builds and prebuilds applying as they would for any project using it.

That second line is doing more work than it looks. A bundled native binding means the install either finds a working prebuild for your platform and Node version, or compiles one, which means a toolchain, Python and a build step on the machine. The phrasing acknowledges the case and delegates the details to the dependency's own documentation, which is fair for a build-system problem but leaves the failure mode unnamed.

It also tells you something about the storage layer. A synchronous SQLite binding is consistent with a local workspace directory that an executor on your machine writes to directly, with no service to run, which matches the studio description. It also means the local mode has a file format to back up and migrate, and the page says nothing about either.

## The heading says 2.0 and the repository has no tags

The page opens with the version in its title, Cognetivy 2.0, and the repository publishes no GitHub releases to match it. The only version trail in the tree is `CHANGELOG.md` beside `CONTRIBUTING.md` and `LICENSE`.

That combination is workable but awkward for a tool whose stated purpose is auditable process. `npx cognetivy` will fetch whatever is current on the registry at that moment, a global install freezes one version, and neither of those numbers is cross-checkable against a tag, because there is none to check.

The last commit on the default branch is dated 2026-05-09, so the 2.0 heading describes a state that the branch has not moved past in five months. Nothing on the page claims a release cadence or a support window, so if the version matters to you, the changelog is the only place to read it.

## Conclusion

Read cognetivy as an operational layer around an agent rather than as an agent itself, and the four nouns are a reasonable starting vocabulary even though the page leaves them undefined. It suits teams that want runs to be inspectable and repeatable on their own machines, with the state directory sitting next to the repository. Check four things first. Authentication and built-in templates both go through the cloud, so the local mode is not an offline mode, and if the cloud is unreachable the honest question is what the studio still does. The default command starts an HTTP and WebSocket server and may open a browser for sign-in, so it is not something to put in a CI step without reading `cognetivy --help` first. `better-sqlite3` is a native dependency, so Node 18 or newer is not the whole install requirement. And the repository publishes no tags while the README heading reads Cognetivy 2.0, so pin a version from the changelog rather than from a release page.

## FAQ

### What are workflows, runs, events and collections in cognetivy?

The page names them as the state layer for agent sessions and attaches one intent to each: explicit workflows define how the agent should work, runs and events track what happened, and collections keep reasoning artifacts organized. It gives no schema, field list or file layout for any of them, and nodes appear only once, in the description of the executor.

### What happens when I run cognetivy with no subcommand?

It starts the local studio: a small HTTP and WebSocket server, the bundled UI in your browser, and the executor that advances runs and nodes on your machine. On first interactive use it also runs guided sign-in if you are not authenticated, and a minimal workspace is created under .cognetivy/ next to your repo.

### What does cognetivy need installed before it runs?

Node.js 18 or newer, and better-sqlite3 is bundled as a dependency where native builds or prebuilds apply. You can run npx cognetivy once, or npm install -g cognetivy and then run cognetivy from any directory.

### Does cognetivy require a cloud account to store agent runs?

The local studio is the default mode and a minimal workspace appears under .cognetivy/ next to your repo, with the API key stored on your machine. Authentication uses cognetivy auth login or COGNETIVY_API_KEY, built-in templates are applied to your cloud workflow, and the CLI and UI sync with the workflow index and cloud workflow once you are signed in.

### Which package do npm users install for cognetivy?

The cognetivy package. The @cognetivy/core package in the repository is built and synced into it for release, the CLI binary is named cognetivy, and the programmatic TypeScript and JavaScript API is entered through the main field in package.json.

## Sources

- [Issues](https://github.com/meitarbe/cognetivy/issues)
- [License: MIT](https://github.com/meitarbe/cognetivy/blob/main/LICENSE)
- [meitarbe/cognetivy on GitHub](https://github.com/meitarbe/cognetivy)
- [Project website](https://cognetivy.com)
- [README](https://github.com/meitarbe/cognetivy/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/meitarbe-cognetivy