intentional-cognition-os 1.0.5 → 1.2.0
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/CHANGELOG.md +32 -0
- package/README.md +134 -133
- package/dist/index.js +334 -457
- package/dist/index.js.map +1 -1
- package/package.json +15 -16
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,37 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## [v1.2.0] - 2026-05-21
|
|
4
|
+
|
|
5
|
+
- feat(dogfood,plugin): scaffold dog-food trail + /ico-your-internals skill (#77) (1b32149)
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
## [v1.1.2] - 2026-05-20
|
|
9
|
+
|
|
10
|
+
- chore(blame): ignore prettier-formatting sweep commit in git blame (ba9e012)
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
## [v1.1.1] - 2026-05-20
|
|
14
|
+
|
|
15
|
+
- fix(release): build before tests, sync all workspace versions, publish to npm (OC5) (#76) (e1b7bed)
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
## [v1.1.0] - 2026-05-20
|
|
19
|
+
|
|
20
|
+
- docs(readme): rewrite for new readers — concrete intro + alternatives table (670405a)
|
|
21
|
+
- feat(test-infra): install Intent Solutions Testing SOP layers L0-L7 (e0efdee)
|
|
22
|
+
- chore(style): apply prettier formatting to existing files (26de1d7)
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## [v1.0.7] - 2026-05-20
|
|
26
|
+
|
|
27
|
+
- docs(gate): reconcile lint perf metrics with E10-B06 bead (PR #73 follow-up) (#75) (c181452)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
## [v1.0.6] - 2026-05-20
|
|
31
|
+
|
|
32
|
+
- chore(beads): file oc5 — auto-release workspace-lockstep fix (9635f52)
|
|
33
|
+
|
|
34
|
+
|
|
3
35
|
All notable changes to this project will be documented in this file.
|
|
4
36
|
|
|
5
37
|
The format is based on [Keep a Changelog 1.1.0](https://keepachangelog.com/en/1.1.0/),
|
package/README.md
CHANGED
|
@@ -1,173 +1,174 @@
|
|
|
1
1
|
# intentional-cognition-os
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> **A local-first knowledge OS.** Point `ico` at a folder of PDFs, markdown notes, and web clips. It compiles them into a queryable wiki you can read, runs grounded Q&A with inline citations, spins up multi-agent research tasks for hard questions, generates spaced-repetition flashcards from what landed, and writes every step to an append-only audit trail. Single CLI. Your data never leaves disk except for the Claude API calls you opt into.
|
|
4
4
|
|
|
5
5
|
[](LICENSE)
|
|
6
|
+
[](https://www.npmjs.com/package/intentional-cognition-os)
|
|
6
7
|
[](https://github.com/jeremylongshore/intentional-cognition-os/actions/workflows/ci.yml)
|
|
7
8
|
[](https://github.com/jeremylongshore/intentional-cognition-os/releases)
|
|
8
9
|
|
|
9
|
-
|
|
10
|
+
---
|
|
10
11
|
|
|
11
|
-
|
|
12
|
+
## What it actually does
|
|
12
13
|
|
|
13
|
-
|
|
14
|
-
- Answers grounded questions with inline source citations
|
|
15
|
-
- Spins up scoped episodic workspaces for hard research questions
|
|
16
|
-
- Renders durable artifacts (reports, slides) that you can promote back into the wiki
|
|
17
|
-
- Generates flashcards and quizzes to help you retain what you've ingested
|
|
14
|
+
You drop documents into a folder. `ico` reads them, compiles the content into a structured wiki on disk (one markdown file per source, per concept, per topic, per contradiction it found), and then lets you:
|
|
18
15
|
|
|
19
|
-
|
|
16
|
+
- **Ask** a question — get an answer with `[source: filename]` citations next to every claim.
|
|
17
|
+
- **Research** a question that's too big for a single retrieval — `ico` spawns a scoped task workspace with four agents (collector, summarizer, skeptic, integrator) that argue across stages and produce a cited final write-up.
|
|
18
|
+
- **Render** a report or slide deck from any topic, and **promote** that artifact back into the wiki so the next answer can cite it.
|
|
19
|
+
- **Recall** what you ingested — generate flashcards with spaced repetition; export to Anki if you prefer.
|
|
20
|
+
- **Audit** anything. Every API call, file write, and task transition is recorded in append-only JSONL with a SHA-256 hash chain. If a citation looks wrong, you can trace it back to the exact source and prompt.
|
|
20
21
|
|
|
21
|
-
|
|
22
|
+
It is a cognition runtime, not a chat wrapper. The model proposes; a deterministic kernel owns durable state, traces, and control. **Your data lives in plain markdown + SQLite on your machine.** The Claude API is called only for the compilation/synthesis/reasoning steps — and only when you trigger them.
|
|
22
23
|
|
|
23
|
-
|
|
24
|
-
ingest → compile → reason → render → refine
|
|
25
|
-
```
|
|
26
|
-
|
|
27
|
-
Every step writes to an append-only audit trail (SQLite index + JSONL trace files), so the system is inspectable, reproducible, and queryable.
|
|
24
|
+
---
|
|
28
25
|
|
|
29
|
-
##
|
|
26
|
+
## Install
|
|
30
27
|
|
|
31
|
-
|
|
28
|
+
```bash
|
|
29
|
+
npm install -g intentional-cognition-os
|
|
30
|
+
ico --version # → 1.0.5
|
|
31
|
+
export ANTHROPIC_API_KEY=sk-ant-...
|
|
32
|
+
```
|
|
32
33
|
|
|
33
|
-
|
|
34
|
-
- pnpm **10+**
|
|
35
|
-
- An [Anthropic API key](https://console.anthropic.com/) (the system uses Claude for compilation and reasoning)
|
|
34
|
+
Requires **Node 22+** and an [Anthropic API key](https://console.anthropic.com/). pnpm not required for usage — only for building from source.
|
|
36
35
|
|
|
37
|
-
|
|
36
|
+
From source:
|
|
38
37
|
|
|
39
38
|
```bash
|
|
40
39
|
git clone https://github.com/jeremylongshore/intentional-cognition-os.git
|
|
41
|
-
cd intentional-cognition-os
|
|
42
|
-
|
|
43
|
-
pnpm build
|
|
40
|
+
cd intentional-cognition-os && pnpm install && pnpm build
|
|
41
|
+
node packages/cli/dist/index.js --version
|
|
44
42
|
```
|
|
45
43
|
|
|
46
|
-
|
|
44
|
+
---
|
|
45
|
+
|
|
46
|
+
## 5-minute quickstart
|
|
47
47
|
|
|
48
48
|
```bash
|
|
49
|
-
|
|
50
|
-
ico
|
|
49
|
+
# 1. Create a workspace
|
|
50
|
+
ico init my-research
|
|
51
|
+
|
|
52
|
+
# 2. Tell it where your sources live
|
|
53
|
+
ico mount add papers ~/Documents/papers --workspace my-research
|
|
54
|
+
|
|
55
|
+
# 3. Ingest (parses PDFs/MD/web clips into ./raw/)
|
|
56
|
+
ico ingest ~/Documents/papers --workspace my-research
|
|
57
|
+
|
|
58
|
+
# 4. Compile — the Claude calls happen here
|
|
59
|
+
ico compile all --workspace my-research
|
|
60
|
+
|
|
61
|
+
# 5. Ask
|
|
62
|
+
ico ask "How does self-attention scale with sequence length?" \
|
|
63
|
+
--workspace my-research
|
|
51
64
|
```
|
|
52
65
|
|
|
53
|
-
|
|
66
|
+
You now have:
|
|
54
67
|
|
|
55
|
-
|
|
68
|
+
- `my-research/wiki/` — readable markdown summary + concept + topic pages, all with frontmatter and inline `[[wikilinks]]`
|
|
69
|
+
- `my-research/audit/log.md` — chronological human-readable record of what just happened
|
|
70
|
+
- `my-research/audit/traces/*.jsonl` — machine-readable trace events for every step
|
|
56
71
|
|
|
57
|
-
|
|
58
|
-
# Create a workspace
|
|
59
|
-
ico init my-knowledge
|
|
72
|
+
`ico status` shows counts. `ico lint` audits the wiki for schema drift / staleness / orphans. `tail workspace/audit/log.md` answers "what did I do today."
|
|
60
73
|
|
|
61
|
-
|
|
62
|
-
ico mount add papers ~/research/papers --workspace my-knowledge
|
|
74
|
+
---
|
|
63
75
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
76
|
+
## When to use it (and when not to)
|
|
77
|
+
|
|
78
|
+
| You want to… | Use `ico`? | Why |
|
|
79
|
+
| -------------------------------------------------------------------------- | ---------- | -------------------------------------------------------- |
|
|
80
|
+
| Build a personal research base from PDFs + notes | ✅ Yes | Core use case |
|
|
81
|
+
| Answer questions with traceable citations to your own sources | ✅ Yes | Citations are first-class, not bolted on |
|
|
82
|
+
| Run a multi-step research investigation (literature review, due diligence) | ✅ Yes | `ico research` spawns scoped agents with a skeptic stage |
|
|
83
|
+
| Study what you've collected with spaced repetition | ✅ Yes | `ico recall` builds + scores cards |
|
|
84
|
+
| Replace your team's wiki / shared docs | ❌ No | Single-user, single-machine for v1 |
|
|
85
|
+
| Drop into Slack / chat with team-shared memory | ❌ No | No multiplayer, no remote sync yet |
|
|
86
|
+
| Build a customer-facing chatbot | ❌ No | Use LangChain / a managed RAG service |
|
|
87
|
+
|
|
88
|
+
---
|
|
67
89
|
|
|
68
|
-
|
|
69
|
-
ico compile all --workspace my-knowledge
|
|
90
|
+
## vs. the obvious alternatives
|
|
70
91
|
|
|
71
|
-
|
|
72
|
-
|
|
92
|
+
| | **ico** | NotebookLM (Google) | Obsidian + AI plugins | Claude Projects / ChatGPT | LangChain / LlamaIndex | Anki |
|
|
93
|
+
| -------------------------------------------- | ------------------------------------------ | ------------------- | ------------------------------------------------- | ------------------------- | ------------------------- | ----------------------------- |
|
|
94
|
+
| **Local-first** | ✅ markdown + SQLite on disk | ❌ cloud | ✅ | ❌ cloud | ✅ (library) | ✅ |
|
|
95
|
+
| **Source-cited answers** | ✅ inline `[source:...]` per claim | ✅ | depends on plugin | ✅ but no per-claim audit | you build it | n/a |
|
|
96
|
+
| **Inspectable compiled wiki** | ✅ readable .md files | ❌ chat only | ✅ (but you write the notes) | ❌ | n/a — you build the store | n/a |
|
|
97
|
+
| **Multi-agent research mode** | ✅ collector→summarizer→skeptic→integrator | ❌ | ❌ | ❌ | you build it | ❌ |
|
|
98
|
+
| **Spaced-repetition recall** | ✅ built-in, Anki export | ❌ | plugin only | ❌ | ❌ | ✅ (that's the whole product) |
|
|
99
|
+
| **Append-only audit trail** | ✅ SHA-256 hash-chained JSONL | ❌ | ❌ | ❌ | ❌ | ❌ |
|
|
100
|
+
| **Open source / hackable** | ✅ MIT | ❌ | partial (core closed) | ❌ | ✅ | ✅ |
|
|
101
|
+
| **Single CLI, no plugin zoo** | ✅ 14 commands | n/a | ❌ (Obsidian Sync / Smart Connections / Copilot…) | n/a | ❌ you assemble | n/a |
|
|
102
|
+
| **You write the data; the AI just reads it** | ✅ kernel owns state | ✅ | ✅ | ✅ | depends | ✅ |
|
|
73
103
|
|
|
74
|
-
|
|
75
|
-
|
|
104
|
+
**The honest summary**: NotebookLM is the closest competitor in _function_, but it's a cloud product with no audit trail and no recall layer. Obsidian + plugins gets you a local wiki but you write every note yourself — `ico` writes the wiki for you by compiling sources. LangChain gives you the parts; `ico` is the assembled tool.
|
|
105
|
+
|
|
106
|
+
---
|
|
107
|
+
|
|
108
|
+
## The six layers (architecture in one screen)
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
L1 raw/ ← what you put in (PDFs, MD, web clips) APPEND-ONLY
|
|
112
|
+
↓ deterministic
|
|
113
|
+
L2 wiki/ ← compiled markdown (sources, concepts, topics, RECOMPILABLE
|
|
114
|
+
contradictions, open questions) probabilistic
|
|
115
|
+
↓
|
|
116
|
+
L3 tasks/<id>/ ← scoped episodic research workspaces PER-TASK
|
|
117
|
+
(brief, evidence, notes, critique, output) probabilistic
|
|
118
|
+
↓
|
|
119
|
+
L4 outputs/ ← rendered reports, slides, briefings PROMOTABLE
|
|
120
|
+
probabilistic
|
|
121
|
+
↓
|
|
122
|
+
L5 recall/ ← flashcards, quizzes, retention scores ADAPTIVE
|
|
123
|
+
deterministic
|
|
124
|
+
L6 audit/ ← trace JSONL + audit log + hash chain APPEND-ONLY
|
|
125
|
+
deterministic
|
|
76
126
|
```
|
|
77
127
|
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
|
85
|
-
|
|
|
86
|
-
| `ico
|
|
87
|
-
| `ico
|
|
88
|
-
| `ico
|
|
89
|
-
| `ico
|
|
90
|
-
| `ico
|
|
91
|
-
| `ico
|
|
92
|
-
| `ico
|
|
93
|
-
| `ico recall generate --topic <
|
|
94
|
-
| `ico recall quiz --topic <
|
|
95
|
-
| `ico recall
|
|
96
|
-
| `ico
|
|
97
|
-
| `ico
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
##
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
| **L4 — Artifacts** | `workspace/outputs/` | Rendered reports, slides, briefings. Promotable to L2. |
|
|
113
|
-
| **L5 — Recall** | `workspace/recall/` | Flashcards, quizzes, retention scores. Adaptive. |
|
|
114
|
-
| **L6 — Audit & Policy** | `workspace/audit/` | Append-only trace JSONL + audit log. Deterministic control plane. |
|
|
115
|
-
|
|
116
|
-
The **deterministic vs probabilistic boundary** is the most important constraint:
|
|
117
|
-
|
|
118
|
-
- **Deterministic** (Kernel + SQLite + JSONL): file storage, mount registry, task state, provenance, policy, permissions, audit, promotion rules, eval execution.
|
|
119
|
-
- **Probabilistic** (Compiler + Claude API): summarization, synthesis, concept extraction, contradiction detection, question decomposition, artifact drafting, recall generation.
|
|
120
|
-
|
|
121
|
-
The model never directly writes to audit, policy, or promotion tables. It proposes; the kernel decides.
|
|
122
|
-
|
|
123
|
-
## Development
|
|
124
|
-
|
|
125
|
-
| | |
|
|
126
|
-
|---|---|
|
|
127
|
-
| **Build all packages** | `pnpm build` |
|
|
128
|
-
| **Run full test suite** | `pnpm test` |
|
|
129
|
-
| **Lint** | `pnpm lint` |
|
|
130
|
-
| **Typecheck** | `pnpm typecheck` |
|
|
131
|
-
| **Coverage** | `pnpm test:coverage` |
|
|
132
|
-
| **Single test file** | `pnpm --filter @ico/<package> test -- <file>` |
|
|
133
|
-
|
|
134
|
-
See [CONTRIBUTING.md](CONTRIBUTING.md) for full development setup, coding conventions, and PR process.
|
|
128
|
+
The hard constraint, drilled through every component: **the model never directly writes to L6 or to promotion tables.** It proposes a summary, a card, a synthesis — the kernel decides whether it lands.
|
|
129
|
+
|
|
130
|
+
---
|
|
131
|
+
|
|
132
|
+
## Commands you'll actually use
|
|
133
|
+
|
|
134
|
+
| | |
|
|
135
|
+
| --------------------------------- | ------------------------------------------------------ |
|
|
136
|
+
| `ico init <name>` | Create a workspace |
|
|
137
|
+
| `ico mount add <name> <path>` | Register a source directory |
|
|
138
|
+
| `ico ingest <path>` | Parse PDFs/MD/web-clips into the raw layer |
|
|
139
|
+
| `ico compile all` | Run the six compiler passes (Claude calls happen here) |
|
|
140
|
+
| `ico ask "<question>"` | Grounded Q&A with citations |
|
|
141
|
+
| `ico research "<brief>"` | Multi-agent research task (5 stages, ~5 min) |
|
|
142
|
+
| `ico render report --topic <t>` | Generate a markdown report |
|
|
143
|
+
| `ico recall generate --topic <t>` | Build flashcards from compiled wiki |
|
|
144
|
+
| `ico recall quiz --topic <t>` | Interactive quiz; tracks retention |
|
|
145
|
+
| `ico recall export --format anki` | Anki-importable TSV |
|
|
146
|
+
| `ico lint` | Audit the wiki (schema, staleness, orphans) |
|
|
147
|
+
| `ico status` / `ico inspect` | Workspace summary / per-subsystem detail |
|
|
148
|
+
|
|
149
|
+
Global flags on every command: `--workspace <path>`, `--json`, `--verbose`, `--quiet`. Full reference: `ico --help` or any command with `--help`.
|
|
150
|
+
|
|
151
|
+
---
|
|
152
|
+
|
|
153
|
+
## Status
|
|
154
|
+
|
|
155
|
+
**v1.0.5 — stable.** 1,210 tests passing across 5 packages. Used daily by the author. Public release on npm.
|
|
156
|
+
|
|
157
|
+
- **Stable**: all 14 commands, the compilation passes, ask + research + recall + render + promote, the audit chain.
|
|
158
|
+
- **In progress**: post-v1 coverage uplift on compiler + cli packages; mutation-testing baseline.
|
|
159
|
+
- **Roadmap**: remote/sync (Phase 3), multi-user (Phase 4), plugin system (Phase 5). All deliberately deferred to keep v1 local-first and inspectable.
|
|
160
|
+
|
|
161
|
+
---
|
|
135
162
|
|
|
136
163
|
## Documentation
|
|
137
164
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
| [User Journey](000-docs/004-PP-UJRN-user-journey.md) | Walkthrough & personas |
|
|
146
|
-
| [Technical Spec](000-docs/005-AT-SPEC-technical-spec.md) | Stack, APIs, deployment |
|
|
147
|
-
| [Master Blueprint](000-docs/007-PP-PLAN-master-blueprint.md) | Authoritative design document |
|
|
148
|
-
| [Glossary](000-docs/008-AT-GLOS-glossary.md) | Canonical terminology |
|
|
149
|
-
| [Frontmatter Schemas](000-docs/009-AT-FMSC-frontmatter-schemas.md) | YAML schemas for all compiled page types |
|
|
150
|
-
| [Database Schema](000-docs/010-AT-DBSC-database-schema.md) | SQLite DDL + migration strategy |
|
|
151
|
-
| [Trace Schema](000-docs/011-AT-TRSC-trace-schema.md) | JSONL event envelope + event types |
|
|
152
|
-
| [Workspace Policy](000-docs/012-AT-WPOL-workspace-policy.md) | Directory layout + naming |
|
|
153
|
-
| [Coding Standards](000-docs/013-AT-CODE-coding-standards.md) | TypeScript conventions |
|
|
154
|
-
| [Testing Strategy](000-docs/015-AT-TEST-testing-strategy.md) | Test layers + coverage targets |
|
|
155
|
-
| [Promotion Rules](000-docs/018-AT-PROM-promotion-spec.md) | L4 → L2 promotion logic |
|
|
156
|
-
| [Trace Coverage Audit](000-docs/023-OD-AUDIT-trace-coverage-2026-05-15.md) | Per-command trace-emission audit (E10-B04) |
|
|
157
|
-
|
|
158
|
-
## Roadmap
|
|
159
|
-
|
|
160
|
-
| Phase | Status |
|
|
161
|
-
|---|---|
|
|
162
|
-
| Phase 1 — Local-first MVP (Epics 1–9) | ✅ Complete |
|
|
163
|
-
| Phase 2 — Hardening & v1.0 release (Epic 10) | 🚧 In progress |
|
|
164
|
-
| Phase 3 — Remote/cloud features | Future |
|
|
165
|
-
| Phase 4 — Multi-user collaboration | Future |
|
|
166
|
-
| Phase 5 — Plugin system | Future |
|
|
167
|
-
|
|
168
|
-
## Security
|
|
169
|
-
|
|
170
|
-
See [SECURITY.md](SECURITY.md) for vulnerability reporting.
|
|
165
|
+
The detailed specs (architecture, frontmatter schemas, trace event types, promotion rules, etc.) live in [`000-docs/`](000-docs/). Start with [007-PP-PLAN-master-blueprint.md](000-docs/007-PP-PLAN-master-blueprint.md) if you want the authoritative design document, or [003-AT-ARCH-architecture.md](000-docs/003-AT-ARCH-architecture.md) for the system-design view.
|
|
166
|
+
|
|
167
|
+
Development setup, conventions, PR process: [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
168
|
+
|
|
169
|
+
Vulnerability reporting: [SECURITY.md](SECURITY.md).
|
|
170
|
+
|
|
171
|
+
---
|
|
171
172
|
|
|
172
173
|
## License
|
|
173
174
|
|