{
  "markdown": "# Cognitive OS\n\n> **Think before you spec. Decide before you execute.**\n\n[Português (Brasil)](README.pt-BR.md)\n\nCognitive OS is a portable Agent Skill for maturing decisions before consequential action. It reconstructs context, separates evidence from assumptions, chooses proportional research and reasoning methods, challenges the leading conclusion, identifies the next useful proof, and knows when further analysis is no longer worth its cost.\n\nIt is deliberately **not** a software delivery lifecycle or an autonomous executor. A decision may hand off to a human, a coding workflow, a research process, another agent—or to no action at all.\n\n> **Current stable release:** [`v1.4.0`](https://github.com/FilipeGCB/cognitive-os/releases/tag/v1.4.0). Behavioral conformance, live host/capability E2E, promotion CI, downstream `main` CI, and the stable release workflow all passed before publication.\n\n## Install\n\nOn Agent Skills-compatible environments supported by the Skills CLI:\n\n```bash\nnpx skills add FilipeGCB/cognitive-os --skill cognitive-os -g\n```\n\n`npx` is only an installation transport. **Node.js is not part of the Cognitive OS runtime.** The installed skill is a self-contained directory of instructions, references, policies and schemas.\n\nYou can also install manually by copying:\n\n```text\nskills/cognitive-os/\n```\n\ninto a skill directory supported by your agent. Host-specific notes live under [`distribution/`](distribution/).\n\n## 60-second use\n\nAfter installation, ask your agent normally:\n\n> I want to build an AI product for small businesses. Help me decide whether the idea is worth pursuing before I start building it.\n\nIf the idea is too ambiguous to analyze responsibly, Cognitive OS asks **one high-value question at a time**. If the task is already clear, it does not run an intake ritual.\n\nFor a material decision, the result should read like a strong analyst/consultant brief—not a dump of internal frameworks:\n\n```text\ndecision first\n↓\nwhat changed from the initial idea, when relevant\n↓\nwhy the decision changed\n↓\nwhat could still change it\n↓\none clear next move\n```\n\nSee [`examples/`](examples/) for compact examples.\n\n## What changes with Cognitive OS\n\nA vague starting idea can mature without being buried in process.\n\n| | Starting point | Matured decision |\n|---|---|---|\n| Problem | Accept the proposed solution as the problem | Reconstruct context and formulate the real decision |\n| Truth | Plausible statements blend together | Distinguish evidence, inference, hypothesis, assumption, unknown and contradiction |\n| Research | Search because more information feels safer | Obtain information only when it can materially change the decision |\n| Challenge | List generic risks | Close each material attack to its impact on the recommendation |\n| Action | Keep analyzing or start building | Decide, test, wait, stop, investigate further—or deliberately do nothing |\n\n## Cognitive core\n\nThe installed skill includes a selective, adaptive set of capabilities:\n\n- **Adaptive Discovery Interview** — interview only when ambiguity can materially change the outcome.\n- **Sensemaking** — identify what kind of response the situation requires before choosing a method.\n- **Evidence discipline** — separate observed facts/evidence from inference, assumptions and unknowns.\n- **Outside View** — look for defensible comparable outcomes/base rates when they can change the judgment; never invent them.\n- **Diagnosis** — causal reasoning, bottleneck analysis and first principles when justified.\n- **Decision challenge** — trade-offs, red team, premortem, reversibility, second-order effects and kill criteria.\n- **Value of Information** — prioritize the smallest evidence worth obtaining next.\n- **Robustness** — under deep uncertainty, prefer decisions that survive multiple plausible futures rather than fake precise probabilities.\n- **Decision Quality closure** — check framing, alternatives, information, values/trade-offs, reasoning and next action before closing a material decision.\n- **Stop discipline** — know when additional research is unlikely to change the recommendation.\n\nMethods are not shown merely to prove rigor. Cognitive OS reports what they helped discover.\n\n## Capabilities, not vendor lock-in\n\nThe core requests abstract capabilities rather than hard-coding products:\n\n| Need | Capability |\n|---|---|\n| Current external information | Web Search |\n| Broad/deep external investigation | Deep Research |\n| Large or persistent closed corpus | Grounded Corpus Research |\n| Current code/repository state | Repository Research |\n| Authorized documents/files | Document/File Research |\n| Material quantitative work | Data Analysis |\n| Multi-page structured collection | Structured Crawl |\n| Specialized technical security work | Security Analysis |\n| Find reusable procedures/connections | Capability Discovery |\n\nThe current host maps those needs to tools it actually has. A native capability that is already sufficient wins over installing another tool.\n\n### NotebookLM\n\nNotebookLM is a first-class **implementation** of Grounded Corpus Research, not a dependency of Cognitive OS.\n\nThe evaluated community adapter is [`notebooklm-py`](adapters/notebooklm/), which provides a CLI/MCP path to NotebookLM. Because it requires Google/NotebookLM authentication and stores authentication material locally, Cognitive OS **always asks for specific consent** before installing or connecting it. A bounded read-only Hermes E2E has been observed with successful `source_read`, but NotebookLM remains an optional account-bound candidate implementation rather than a bundled/default dependency or an official Google API.\n\n### Open-source corpus companions\n\nCognitive OS is also evaluating local alternatives such as OpenNotebookLM, Open Notebook, SurfSense and AnythingLLM. None is currently installed by default. Repository review selected OpenNotebookLM as a future direct integration candidate, but no default will be promoted until direct retrieval/citation and installation tests pass. See [`docs/capabilities/grounded-corpus-gauntlet.md`](docs/capabilities/grounded-corpus-gauntlet.md).\n\n## Zero-config where possible\n\nFor hosts that can inspect/configure their environment, Cognitive OS follows this principle:\n\n> **Zero-config whenever possible. One confirmation when necessary. Explicit consent when consequential.**\n\nThe optional bootstrap planner first detects what the host already provides. A one-time consent may allow demand-driven installation of approved components only when they are light, local/user-space, reversible, require no account/secret, access no sensitive persistent data, expose no external write, and make no privileged change.\n\nIt **always asks again** before Docker/persistent services, large downloads, external accounts, API keys/credentials, sensitive data access, write-capable integrations, privileged changes or other material consequences.\n\nThe bootstrap planner itself is side-effect-free; it returns an installation decision and does not execute third-party installers.\n\n## Decision artifacts\n\nCognitive OS keeps three responsibilities separate:\n\n```text\nDecision Pack          canonical structured decision truth\n└── Decision Brief     human/editorial projection\n\nCognitive Run Record   separate observable audit evidence when needed\n```\n\nA normal conversation should feel natural and direct. Full Flow/Audit is available when a formal gate or explicit user request requires evidence of what was traversed or executed, without persisting chain-of-thought.\n\n## Output quality is part of correctness\n\nA correct conclusion that is hard to read is a worse decision product.\n\nDecision Brief guidance treats hierarchy, whitespace, density and typography as functional requirements. Markdown is the portable human format. An optional dependency-free HTML renderer produces a restrained editorial/executive-memo view with system fonts, responsive layout and light/dark support:\n\n```bash\npython renderers/decision-brief/render.py \\\n  examples/decision-brief-idea-evolution.md \\\n  decision.html\n```\n\n## Repository layout\n\n```text\ncognitive-os/\n├── skills/cognitive-os/       # self-contained runtime skill\n│   ├── SKILL.md\n│   ├── references/\n│   ├── schemas/\n│   └── policies/\n├── bootstrap/                 # optional side-effect-free capability planner\n├── adapters/                  # isolated candidate/host capability adapters\n├── evals/                     # behavioral case definitions and validators\n├── examples/                  # human-facing Decision Brief examples\n├── renderers/                 # optional presentation layer\n├── distribution/              # thin host/discovery packaging guidance\n├── tests/                     # deterministic contract/regression tests\n└── docs/                      # architecture, evidence and release documentation\n```\n\n## Runtime truth\n\nCognitive OS distinguishes:\n\n```text\navailability = AVAILABLE | UNAVAILABLE | UNKNOWN\ninvocation   = CALLED | NOT_CALLED\nresult       = SUCCESS | PARTIAL | TRUNCATED | RATE_LIMITED | UNAVAILABLE | BLOCKED | FAILED | NOT_APPLICABLE\n```\n\nA capability that is installed or documented has **not** necessarily executed. Successful execution is claimed only when runtime evidence supports it.\n\n## Conformance\n\nThe private predecessor V1.3 established the behavioral and auditability baseline from which this public product was derived. Those historical results do **not** automatically prove V1.4.\n\nThe public V1.4 case manifests live under [`evals/`](evals/). The released `v1.4.0` candidate passed the declared 29-case behavioral/output suite with the local Gemma SUT and an independent Qwen cross-grader, with zero critical failures and zero grader disagreements. Live Hermes capability E2E also passed 6/6 on one candidate SHA. Promotion CI, downstream `main` CI, and the stable release workflow subsequently passed before the `v1.4.0` tag and GitHub Release were created. See [`docs/releases/v1.4.0-release-evidence.md`](docs/releases/v1.4.0-release-evidence.md) for the evidence boundary.\n\n## License\n\nCognitive OS is licensed under the **Apache License 2.0**. See [`LICENSE`](LICENSE).\n\nStable `v1.4.0` was published only after the explicit release gate was satisfied, the promotion PR was merged with user approval, downstream `main` CI passed, and the release workflow verified the exact target commit.",
  "bytes": 10357,
  "sha": "e8dee1876574f80b3db2cccd630b3678ed047986c4ad287a4a87a74ad2cd218d",
  "repo_slug": "filipegcb/cognitive-os",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_filipegcb_cognitive_os_01932ca1/readme"
}