cognetivy 0.1.0 → 0.1.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +57 -175
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,203 +1,85 @@
|
|
|
1
1
|
# cognetivy
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**Workflow and reasoning state for AI coding assistants.** Define workflows, track runs and events, store structured artifacts — no LLMs inside, just the state layer that Cursor, Claude Code, OpenClaw (and other MCP clients) can read and write.
|
|
4
4
|
|
|
5
|
-
- **
|
|
6
|
-
- **
|
|
7
|
-
- **
|
|
8
|
-
- **
|
|
5
|
+
- **Local workspace** — one `.cognetivy/` per project; config in `~/.config/cognetivy` or `.cognetivy/config.json`.
|
|
6
|
+
- **MCP server** — expose workflow, runs, artifacts, and skills to your editor/agent.
|
|
7
|
+
- **Studio** — read-only browser UI for workflow, runs, and artifacts.
|
|
8
|
+
- **Skills** — install and manage SKILL.md-based skills for **Cursor**, **Claude Code**, and **OpenClaw** from one place.
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
## Install
|
|
11
13
|
|
|
12
14
|
```bash
|
|
13
|
-
npm
|
|
14
|
-
cognetivy init
|
|
15
|
-
cognetivy workflow get
|
|
16
|
-
cognetivy run start --input sample_input.json
|
|
15
|
+
npm install -g cognetivy
|
|
17
16
|
```
|
|
18
17
|
|
|
19
|
-
|
|
18
|
+
---
|
|
20
19
|
|
|
20
|
+
## Quick start
|
|
21
|
+
|
|
22
|
+
```bash
|
|
23
|
+
cognetivy init
|
|
24
|
+
cognetivy studio
|
|
21
25
|
```
|
|
22
|
-
./.cognetivy/
|
|
23
|
-
workflow.json # pointer to current workflow version
|
|
24
|
-
artifact-schema.json # entity kinds and schema (agent-defined; empty by default)
|
|
25
|
-
workflow.versions/
|
|
26
|
-
wf_v1.json # immutable workflow version files
|
|
27
|
-
runs/
|
|
28
|
-
<run_id>.json # run metadata
|
|
29
|
-
events/
|
|
30
|
-
<run_id>.ndjson # append-only event log per run
|
|
31
|
-
mutations/
|
|
32
|
-
<mutation_id>.json # proposed mutation patches + status
|
|
33
|
-
artifacts/
|
|
34
|
-
<run_id>/
|
|
35
|
-
<kind>.json # per-run artifact data (when kind has global: false)
|
|
36
|
-
data/
|
|
37
|
-
<kind>.json # cross-run entity data (when kind has global: true)
|
|
38
|
-
```
|
|
39
26
|
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
| Command |
|
|
45
|
-
|
|
46
|
-
| `cognetivy init` | Create
|
|
47
|
-
| `cognetivy workflow get` |
|
|
48
|
-
| `cognetivy
|
|
49
|
-
| `cognetivy
|
|
50
|
-
| `cognetivy
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
| `cognetivy install claude \| openclaw \| workspace [--force]` | Install skills from current directory (SKILL.md or skills/*) into target |
|
|
64
|
-
| `cognetivy skills list [--source <agent\|openclaw\|workspace>] [--eligible]` | List skills from configured sources |
|
|
65
|
-
| `cognetivy skills info <name>` | Show one skill (path, frontmatter, body preview) |
|
|
66
|
-
| `cognetivy skills check [path]` | Validate SKILL.md (path = skill dir; omit to check all) |
|
|
67
|
-
| `cognetivy skills paths` | Print discovery and install target paths |
|
|
68
|
-
| `cognetivy skills install [source] [--target agent\|openclaw\|workspace] [--force]` | Install from local path or git URL (omit source = current directory) |
|
|
69
|
-
| `cognetivy skills update [name] [--target <target>] [--all] [--dry-run]` | Update skill(s) from recorded origin |
|
|
70
|
-
| `cognetivy mcp [--workspace <path>]` | Start MCP server over stdio for Cursor/agents |
|
|
71
|
-
| `cognetivy studio [--workspace <path>] [--port <port>]` | Start read-only Studio and open in browser |
|
|
72
|
-
| `cognetivy studio --api-only [--workspace <path>] [--port <port>]` | Serve only the Studio API (for dev with Vite; see Studio dev mode below) |
|
|
73
|
-
|
|
74
|
-
**Tip:** Collection payload for `node complete` can be piped from stdin when `--collection-file` is omitted (e.g. `echo '<json>' | cognetivy node complete --run <id> --node <id> --status completed --collection-kind <kind>`).
|
|
75
|
-
|
|
76
|
-
## Skills (Agent skills and OpenClaw skills)
|
|
77
|
-
|
|
78
|
-
cognetivy supports the **SKILL.md** format (Agent skills / OpenClaw skills): a directory containing `SKILL.md` with YAML frontmatter (`name`, `description`, optional `license`, `compatibility`, `metadata`, `allowed-tools`) and markdown instructions. You can manage skills **without using MCP** — install, update, list, and validate from the CLI so that agents (e.g. OpenClaw, Cursor, and other compatible tools) load them from disk.
|
|
79
|
-
|
|
80
|
-
- **Discovery sources**: `agent` (e.g. `~/.cursor/skills`, `.cursor/skills`), `openclaw` (`~/.openclaw/workspace/skills` and `skills.load.extraDirs` from `~/.openclaw/openclaw.json`), `workspace` (`.cognetivy/skills` and user config dir).
|
|
81
|
-
- **Install (target-specific)**: From the current directory, run `cognetivy install claude`, `cognetivy install openclaw`, or `cognetivy install workspace`. Supports two folder layouts: a single skill with `SKILL.md` in the current directory, or a pack with `skills/<skill-name>/SKILL.md` for each skill. Installs into the standard dirs for that target (e.g. claude → `~/.claude/skills` and `.claude/skills`; openclaw → `~/.openclaw/workspace/skills`).
|
|
82
|
-
- **Install (skills subcommand)**: `cognetivy skills install` (or with a path/git URL) installs from current directory or source; use `--target` or default `workspace`. Same folder layout (SKILL.md in cwd or `skills/*/SKILL.md`). Origin is recorded for `skills update`.
|
|
83
|
-
- **Config** (in `~/.config/cognetivy/config.json` or `.cognetivy/config.json`):
|
|
84
|
-
- `skills.sources` — which sources to scan when listing (default: all).
|
|
85
|
-
- `skills.extraDirs` — extra directories to scan.
|
|
86
|
-
- `skills.default_install_target` — default for `install` / `update` when `--target` is omitted.
|
|
87
|
-
|
|
88
|
-
When using the cognetivy MCP server (e.g. in Cursor), the tools **skills_list** and **skills_get** let the agent discover and load skill content on demand.
|
|
89
|
-
|
|
90
|
-
## MCP tools (1:1 with CLI)
|
|
91
|
-
|
|
92
|
-
- `workflow_get()` — get current workflow JSON
|
|
93
|
-
- `workflow_set(workflow_json)` — set workflow (new version)
|
|
94
|
-
- `run_start(input_json, name?, by?)` — start run; returns `run_id`
|
|
95
|
-
- `run_status(run_id)` — run status (nodes + collection counts)
|
|
96
|
-
- `event_append(run_id, event_json, by?)` — append event to run
|
|
97
|
-
- `node_start(run_id, node_id, by?)` — append step_started, create started node result; returns `{ node_result_id }`
|
|
98
|
-
- `node_complete(run_id, node_id, status, output?, collection_kind?, collection_items?|collection_payload?, ...)` — create node result, optional collection, append step_completed; returns `{ node_result_id }`
|
|
99
|
-
- `mutate_propose(patch_json, reason, by?)` — propose mutation; returns `mutation_id`
|
|
100
|
-
- `mutate_apply(mutation_id, by?)` — apply mutation
|
|
101
|
-
- `artifact_schema_get()` — get artifact schema (kinds and required fields)
|
|
102
|
-
- `artifact_schema_set(schema_json)` — set artifact schema (agent defines kinds; use `global: true` for cross-run kinds)
|
|
103
|
-
- `artifact_list(run_id)` — list artifact kinds with data for run
|
|
104
|
-
- `artifact_get(run_id, kind)` — get structured artifacts for a kind
|
|
105
|
-
- `artifact_set(run_id, kind, items)` — replace all items for a kind (schema-validated)
|
|
106
|
-
- `artifact_append(run_id, kind, payload, id?)` — append one item (schema-validated); returns item with `id`, `created_at`
|
|
107
|
-
- `skills_list(sources?)` — list Agent/OpenClaw skills (name, description, path, source)
|
|
108
|
-
- `skills_get(name)` — get full SKILL.md content for a skill by name
|
|
109
|
-
|
|
110
|
-
If the workspace is missing, the MCP server exits with a message to run `cognetivy init`.
|
|
111
|
-
|
|
112
|
-
## Connecting Cursor to cognetivy MCP
|
|
113
|
-
|
|
114
|
-
So Cursor (or another MCP client) can call cognetivy tools:
|
|
115
|
-
|
|
116
|
-
1. **Install cognetivy** (if not already):
|
|
117
|
-
`npm i -g cognetivy` or from this repo: `npm i -g ./cli`
|
|
118
|
-
|
|
119
|
-
2. **Add the MCP server** in Cursor:
|
|
120
|
-
|
|
121
|
-
- **Settings → Tools & MCP → Add new MCP server**, then:
|
|
122
|
-
- **Name**: `cognetivy`
|
|
123
|
-
- **Type**: `command`
|
|
124
|
-
- **Command**: `cognetivy` (or full path to the CLI)
|
|
125
|
-
- **Args**: `mcp` — or `mcp`, `--workspace`, `/path/to/your/project` if the project with `.cognetivy/` is not the current folder.
|
|
126
|
-
|
|
127
|
-
- **Or** put a config file in your project (the one that has `.cognetivy/`):
|
|
128
|
-
|
|
129
|
-
**Project-level** — in the project root (e.g. `example-usage/.cursor/mcp.json`):
|
|
130
|
-
|
|
131
|
-
```json
|
|
132
|
-
{
|
|
133
|
-
"mcpServers": {
|
|
134
|
-
"cognetivy": {
|
|
135
|
-
"command": "cognetivy",
|
|
136
|
-
"args": ["mcp"]
|
|
137
|
-
}
|
|
138
|
-
}
|
|
139
|
-
}
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
Cursor usually starts the server with the project root as cwd, so `cognetivy mcp` will use that project’s `.cognetivy/`.
|
|
143
|
-
|
|
144
|
-
- **Or** use a **global** config at `~/.cursor/mcp.json` with the same `mcpServers.cognetivy` entry. Then the workspace is the folder you have open in Cursor; if your repo root is not the folder with `.cognetivy/`, use:
|
|
145
|
-
|
|
146
|
-
```json
|
|
147
|
-
"args": ["mcp", "--workspace", "/absolute/path/to/folder/with/.cognetivy"]
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
3. **Restart Cursor** so it picks up the new MCP server.
|
|
151
|
-
|
|
152
|
-
4. In chat, the cognetivy tools (workflow, run, event, mutate, and **artifact** / **artifact_schema**) should appear and be callable by the agent.
|
|
153
|
-
|
|
154
|
-
In this repo, the root `.cursor/mcp.json` is set to `--workspace example-usage` so the agent uses the `example-usage` workspace when you have the cognetivy repo open.
|
|
155
|
-
|
|
156
|
-
## Studio (read-only visualization)
|
|
157
|
-
|
|
158
|
-
Run `cognetivy studio [--workspace <path>] [--port <port>]` to start a local HTTP server and open a browser to a read-only UI that shows the current workflow (DAG), runs, events, artifacts, mutations, and artifact schema. Default port is 3742. The server binds to 127.0.0.1. No write operations; the UI polls the API every few seconds for updates.
|
|
27
|
+
`init` creates `.cognetivy/` and can install skills into Cursor / Claude Code / OpenClaw. `studio` opens the read-only UI in your browser.
|
|
28
|
+
|
|
29
|
+
**Essential commands:**
|
|
30
|
+
|
|
31
|
+
| Command | What it does |
|
|
32
|
+
|--------|----------------|
|
|
33
|
+
| `cognetivy init` | Create workspace (and optionally install skills) |
|
|
34
|
+
| `cognetivy workflow get` | Show current workflow |
|
|
35
|
+
| `cognetivy run start --input <json>` | Start a run |
|
|
36
|
+
| `cognetivy studio` | Open Studio UI |
|
|
37
|
+
| `cognetivy mcp` | Start MCP server (for Cursor / Claude Code / OpenClaw) |
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## For Cursor, Claude Code, and OpenClaw
|
|
42
|
+
|
|
43
|
+
**MCP** — So the AI can read/write workflow, runs, and artifacts:
|
|
44
|
+
|
|
45
|
+
1. Install: `npm install -g cognetivy`
|
|
46
|
+
2. Add MCP server (Cursor: **Settings → Tools & MCP → Add new**):
|
|
47
|
+
- **Command:** `cognetivy`
|
|
48
|
+
- **Args:** `mcp` (or `mcp`, `--workspace`, `/path/to/project` if needed)
|
|
49
|
+
3. Restart the editor. Cognetivy tools will show up in chat.
|
|
159
50
|
|
|
160
|
-
|
|
51
|
+
**Skills** — Install SKILL.md skills into each environment:
|
|
161
52
|
|
|
162
|
-
|
|
53
|
+
- **Cursor:** `cognetivy install cursor` (installs to `.cursor/skills`)
|
|
54
|
+
- **Claude Code:** `cognetivy install claude`
|
|
55
|
+
- **OpenClaw:** `cognetivy install openclaw`
|
|
56
|
+
- **Project-only:** `cognetivy install workspace` (installs to `.cognetivy/skills`)
|
|
163
57
|
|
|
164
|
-
|
|
58
|
+
List and manage skills: `cognetivy skills list`, `cognetivy skills info <name>`, `cognetivy skills install`, `cognetivy skills update`.
|
|
165
59
|
|
|
166
|
-
|
|
167
|
-
```bash
|
|
168
|
-
cognetivy studio --api-only --workspace <path-to-workspace> [--port 3742]
|
|
169
|
-
```
|
|
170
|
-
Example: `cognetivy studio --api-only --workspace example-usage`
|
|
171
|
-
Leave this running. Default port is 3742; if you use a different `--port`, update the proxy in `studio/vite.config.ts` to match.
|
|
60
|
+
---
|
|
172
61
|
|
|
173
|
-
|
|
174
|
-
```bash
|
|
175
|
-
cd studio && npm run dev
|
|
176
|
-
```
|
|
177
|
-
Then open **http://localhost:5173** in your browser. The app proxies `/api` to the API server, so the UI uses the workspace you started in terminal 1.
|
|
62
|
+
## More commands
|
|
178
63
|
|
|
179
|
-
|
|
64
|
+
- **Workflow:** `workflow set --file <path>`
|
|
65
|
+
- **Runs:** `run status --run <id>`, `run set-name --run <id> --name "..."`
|
|
66
|
+
- **Events:** `event append --run <id> [--file <path>]`
|
|
67
|
+
- **Nodes:** `node start`, `node complete` (for step lifecycle)
|
|
68
|
+
- **Mutations:** `mutate propose --patch <path> --reason "..."`, `mutate apply <id>`
|
|
69
|
+
- **Artifacts:** `artifact-schema get/set`, `artifact list/get/set/append`
|
|
70
|
+
- **Studio API only:** `cognetivy studio --api-only` (for dev with Vite)
|
|
180
71
|
|
|
181
|
-
|
|
182
|
-
- **workflow.versions/wf_vN.json**: `{ "workflow_id", "version", "nodes", "edges" }` (nodes have `id`, `type`, `contract`, optional `description`)
|
|
183
|
-
- **artifact-schema.json**: `{ "kinds": { "<kind>": { "description", "required": [], "properties": {} } } }` — modifiable; default kinds: `sources`, `collected`, `ideas`
|
|
184
|
-
- **artifacts/<run_id>/<kind>.json**: `{ "run_id", "kind", "updated_at", "items": [ { "id?", "created_at?", ...payload } ] }` — items validated against schema
|
|
185
|
-
- **runs/<run_id>.json**: `{ "run_id", optional "name", "workflow_id", "workflow_version", "status", "input", "created_at" }`
|
|
186
|
-
- **events/<run_id>.ndjson**: one JSON object per line (`ts`, `type`, `by`, `data`)
|
|
187
|
-
- **mutations/<mutation_id>.json**: RFC 6902 JSON Patch + `target`, `reason`, `status`, `applied_to_version` when applied
|
|
72
|
+
---
|
|
188
73
|
|
|
189
74
|
## Development
|
|
190
75
|
|
|
191
76
|
```bash
|
|
192
|
-
cd cli
|
|
193
|
-
npm install
|
|
194
|
-
npm run build
|
|
195
|
-
npm test
|
|
77
|
+
cd cli && npm install && npm run build && npm test
|
|
196
78
|
```
|
|
197
79
|
|
|
198
|
-
|
|
80
|
+
Embed Studio in the CLI build: `npm run build:full`.
|
|
199
81
|
|
|
200
|
-
|
|
82
|
+
---
|
|
201
83
|
|
|
202
84
|
## License
|
|
203
85
|
|