{"_id":"@avivk5498/cortex","name":"@avivk5498/cortex","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@avivk5498/cortex","version":"0.1.0","description":"Cortex — an npx-installable global Markdown knowledge brain for coding agents (Claude Code & Codex). Local-only, git-audited, secret-scanned. Your projects are documented inside one global brain.","bin":{"brain":"bin/brain.js"},"type":"commonjs","engines":{"node":">=18"},"scripts":{"test":"node --test 'test/unit/*.test.js' 'test/integration/*.test.js' 'test/e2e/*.test.js' 'test/regression/*.test.js'","test:unit":"node --test 'test/unit/*.test.js'","test:integration":"node --test 'test/integration/*.test.js'","test:e2e":"node --test 'test/e2e/*.test.js'","test:regression":"node --test 'test/regression/*.test.js'"},"repository":{"type":"git","url":"git+https://github.com/AvivK5498/Cortex.git"},"homepage":"https://github.com/AvivK5498/Cortex#readme","bugs":{"url":"https://github.com/AvivK5498/Cortex/issues"},"keywords":["cortex","brain","knowledge-base","claude-code","codex","agent","memory","cli","second-brain"],"author":{"name":"Aviv Kaplan"},"license":"MIT","publishConfig":{"access":"public"},"dependencies":{"js-yaml":"^4.1.0"},"_id":"@avivk5498/cortex@0.1.0","gitHead":"363bb60ba8e8a5130c61ad4152d9a590420128af","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-pVe5PugHQmNucCjcYevEJqCPRX6YgELwrirDBDGRVqzU/CLWOY6i8B85wVlWxY1Ig4dty5MBqHLUcus+Ma7zZA==","shasum":"4702572f33753948819174d20959c14fb50d3f4d","tarball":"https://registry.npmjs.org/@avivk5498/cortex/-/cortex-0.1.0.tgz","fileCount":41,"unpackedSize":151776,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIGPOsVTOkN4x5M58pdd60KEOtvATj94plo3agmBDW2MFAiBq0Y5WYo/vTdU5o4s+ljsDEqKfcl112pu39+j4bs2REg=="}]},"_npmUser":{"name":"avivk5498","email":"aviv@avivkaplan.com"},"directories":{},"maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/cortex_0.1.0_1780913766420_0.807995998614002"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-08T10:16:06.161Z","0.1.0":"2026-06-08T10:16:06.549Z","modified":"2026-06-08T10:16:06.835Z"},"maintainers":[{"name":"avivk5498","email":"aviv@avivkaplan.com"}],"description":"Cortex — an npx-installable global Markdown knowledge brain for coding agents (Claude Code & Codex). Local-only, git-audited, secret-scanned. Your projects are documented inside one global brain.","homepage":"https://github.com/AvivK5498/Cortex#readme","keywords":["cortex","brain","knowledge-base","claude-code","codex","agent","memory","cli","second-brain"],"repository":{"type":"git","url":"git+https://github.com/AvivK5498/Cortex.git"},"author":{"name":"Aviv Kaplan"},"bugs":{"url":"https://github.com/AvivK5498/Cortex/issues"},"license":"MIT","readme":"<div align=\"center\">\n\n# Cortex\n\n**One global, local-only Markdown brain that documents all your projects — for Claude Code and Codex.**\n\n[![npm](https://img.shields.io/npm/v/@avivk5498/cortex.svg)](https://www.npmjs.com/package/@avivk5498/cortex)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)\n[![Node >=18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)\n\n</div>\n\n🧠 One brain · 🗂️ Markdown only · 🤖 Claude Code + Codex · 📦 npx-first · 🔒 secret-scanned · 🧾 git-audited\n\n---\n\n## What it is\n\nCortex is a **global** knowledge brain that lives on your machine as a folder of plain Markdown (`~/brain` by default). Every project you work on is documented **inside that one brain** — not scattered across per-repo `docs/brain/` folders. Open it in any editor; it is just files.\n\n- **Local-only.** No server, no cloud, no telemetry. Your brain never leaves your disk.\n- **Built for coding agents.** Claude Code and Codex read it at session start and query it on demand.\n- **npx-first.** Try it without installing anything.\n- **git-audited.** Every write commits locally so you have a full, reversible history. No remote is ever added; nothing is ever pushed.\n- **Secret-scanned.** Every write passes a secret gate that refuses high-confidence leaks and redacts low-confidence ones.\n\nThis is currently positioned for **personal reuse** — a tool Aviv built for his own multi-project workflow and is sharing. It is not yet a team product (see [Limitations](#limitations)).\n\n## Quick start\n\n```bash\n# Try it with npx — no install\nnpx @avivk5498/cortex init        # create ~/brain\nbrain bootstrap                   # document the project in the current directory\nbrain build                       # (re)build the search index\nbrain check                       # validate the brain\n```\n\nOr install globally:\n\n```bash\nnpm i -g @avivk5498/cortex\nbrain init\n```\n\nWire up your agent once:\n\n```bash\nbrain agent-hook-setup claude     # Claude Code\nbrain agent-hook-setup codex      # Codex\n```\n\n## The global brain\n\nA Cortex brain is a single directory. Projects are **pages inside it**, organized by type:\n\n```\n~/brain/\n├── SCHEMA.md                 # the page taxonomy + frontmatter contract\n├── MOC.md                    # Map of Content — the hub index, hand-curated\n├── log.md                    # append-only operation log\n├── AGENTS.md                 # generic agent contract\n├── _sync-state.json          # bookkeeping (counts, known projects, install flags)\n├── inbox/\n│   └── scratchpad.md         # capture buffer; non-template lines = \"pending\"\n├── sources/                  # raw source material (binaries gitignored)\n├── adapters/                 # adapter-owned, brain-committed snippets\n└── pages/\n    ├── projects/<slug>.md            # project overview (one per project)\n    ├── project/<slug>/overview.md    # nested per-project detail\n    ├── reference/<slug>-important-files.md\n    ├── decision/<slug>-*.md          # decisions, with citations\n    └── gotcha/<slug>-*.md            # sharp edges / footguns\n```\n\nProject pages carry citation metadata — `project_path`, `project_slug`, and a `cites:` list of `{ref: path:line, sha: <git hash-object>}` — so `brain check` can detect when the underlying code has drifted from what the brain claims. The full contract is documented in `SCHEMA.md` inside every brain.\n\n### How a project gets into the brain\n\n`brain bootstrap` (run from inside a repo) does **not** invent knowledge. It collects facts about the repo and writes an **agent prompt** to `inbox/bootstrap-<slug>.md`. Your coding agent then synthesizes the project pages — with citations — and writes them through Cortex's safe-write path. The tool prepares; the agent fills in the knowledge. See [the agentic bootstrap flow](#the-agentic-bootstrap-flow).\n\n## Command reference\n\n| Command | What it does | Key flags |\n|---|---|---|\n| `brain init` | Scaffold a new global brain (dirs, SCHEMA/MOC/log/AGENTS, git repo, index). | `--force`, `--agent <x>`, `--json` |\n| `brain bootstrap` | Collect repo facts and prepare an agent prompt to document the current project. | `--dry-run`, `--json` |\n| `brain build` | Rebuild the search index and commit it. | `--json` |\n| `brain query \"<text>\"` | Rank brain pages for a query. | `--limit N`, `--important`, `--bundle`, `--json` |\n| `brain check` | Validate the brain: required files, stale index, frontmatter, MOC orphans, stale citations, pending inbox, dirty git. | `--verbose`, `--json` |\n| `brain status` | Snapshot: git state, last op, index freshness, counts, adapter install status. | `--json` |\n| `brain sync` | Deterministic pass (reindex + check + state) then emit the agent task block for durable-learning capture. | `--json` |\n| `brain update-brain` | Emit an agent prompt to sweep the current conversation for durable knowledge and file confirmed items. | `--dry-run`, `--json` |\n| `brain session-context` | Emit the matched project page + MOC + routing instruction (used by the SessionStart hook). | `--hook-json`, `--agent <x>` |\n| `brain agent-hook-setup <agent>` | Install the Claude / Codex / generic adapter. | `--force`, `--json` |\n\nExit codes: `0` success/clean · `1` validation findings or empty query · `2` runtime/config error.\n\n### BRAIN_HOME / --brain\n\nThe brain home is `~/brain` by default. Override it with the `BRAIN_HOME` environment variable, or per-invocation with `--brain PATH`:\n\n```bash\nBRAIN_HOME=~/work-brain brain status\nbrain --brain /tmp/scratch-brain init\n```\n\n`--brain` wins over `BRAIN_HOME`, which wins over the default.\n\n## Claude setup\n\n```bash\nbrain agent-hook-setup claude\n```\n\nThis writes into `~/.claude` (the Claude adapter; see [docs/claude-adapter.md](./docs/claude-adapter.md)):\n\n- **`~/.claude/commands/brain-bootstrap.md`, `brain-sync.md`, `brain-update.md`, `brain-query.md`** — slash commands that drive the `brain` CLI flows.\n- **`~/.claude/settings.json`** — a `SessionStart` hook is merged in that runs `brain session-context --hook-json --agent claude`. Your existing settings are preserved; the file is backed up to `settings.json.bak` before writing.\n\nRe-running without `--force` skips files that already exist (reported as `skipped`).\n\n## Codex setup\n\n```bash\nbrain agent-hook-setup codex\n```\n\nThis writes into `~/.codex` (the Codex adapter; see [docs/codex-adapter.md](./docs/codex-adapter.md)):\n\n- **`~/.codex/AGENTS.md`** — a marked block (`<!-- BEGIN cortex-brain --> … <!-- END cortex-brain -->`) with a compact pointer to the brain and how to query it. Re-runs replace only that block; the rest of your AGENTS.md is untouched. The block is kept small because all AGENTS.md files share a 32 KiB cap.\n- **`~/.codex/prompts/brain-query.md`, `brain-sync.md`, `brain-update.md`, `brain-bootstrap.md`, `brain-status.md`** — prompt commands (`$ARGUMENTS`-based).\n- **`~/.codex/hooks.json`** — a `SessionStart` (and `PreCompact`) command hook running `brain session-context --hook-json --agent codex`, merged with any existing hooks.\n\n> **Trust prompt:** Codex asks you to trust the hook on first run. If your environment sets `allow_managed_hooks_only`, user-level hooks are blocked and the SessionStart injection will not fire — fall back to the AGENTS.md pointer. Codex prompt commands are local-only and require a restart to reload.\n\n## The agentic bootstrap flow\n\nCortex deliberately separates **fact collection** (deterministic, done by the tool) from **knowledge synthesis** (judgment, done by the agent):\n\n1. You run `brain bootstrap` inside a repo. Cortex collects context (repo metadata, file tree, key facts).\n2. Cortex writes an agent prompt to `inbox/bootstrap-<slug>.md` and commits it. The prompt names the exact pages to write (`pages/projects/<slug>.md`, `pages/reference/<slug>-important-files.md`, optional decisions/gotchas/sources) and requires citations (`ref: path:line`, `sha:` via `git hash-object`).\n3. Your agent reads the prompt, studies the repo, and writes the pages **through Cortex's safe-write path** — so every page is secret-scanned and committed.\n4. `brain build` indexes the new pages; `brain check` validates them.\n\nThe tool never makes up knowledge about your code; the agent does the writing, Cortex enforces the discipline.\n\n## Local git & audit model\n\nEvery command that writes to the brain commits it locally with a `brain: <message>` message. This gives you a complete, reversible audit trail (`git log` inside `~/brain`).\n\n- **No remote is ever added.**\n- **Nothing is ever pushed.**\n- Adapter files live outside the brain (in `~/.claude`, `~/.codex`) and are **not** committed to the brain — only the brain's *record* of the install is.\n\n## Secret scanning\n\nEvery write passes through a secret gate before it touches disk:\n\n- **Refuses** high-confidence secrets — the write is aborted (`SecretRefusal`) and nothing is written.\n- **Redacts** low-confidence matches in place and writes the redacted content.\n- **Blocks by filename** — writes to `.env`, `*.pem`, `id_*`, `credentials*`, and gitignored paths are refused outright.\n\n`brain check` also flags any **staged** file that matches the secret filename rules, so a leak can't slip through the commit.\n\n## Safety guarantees\n\n- Local-only; no network calls, no telemetry.\n- No git remote, no push, ever.\n- High-confidence secrets are refused, not just redacted.\n- Adapter installs back up `settings.json` and never overwrite adapter-owned files without `--force`.\n- Writes that would fail the commit leave your files intact and return a runtime error.\n\n## Limitations\n\n- **Single-user.** One brain, one author. No team workflow yet.\n- **No merge model.** There is no conflict resolution for concurrent editors.\n- **No embeddings.** Search is token-overlap ranking, not vector/semantic search.\n\n## Troubleshooting\n\n- **`already initialized (use --force)`** — a brain already exists at the target home. Use `--force` to re-scaffold, or point elsewhere with `--brain` / `BRAIN_HOME`.\n- **`check` reports a stale index** — run `brain build`.\n- **`check` reports stale citations** — the cited code changed; have your agent re-verify and update the page's `sha`.\n- **Codex SessionStart hook never fires** — your environment likely enforces `allow_managed_hooks_only`; rely on the AGENTS.md pointer instead.\n- **Claude slash commands missing** — re-run `brain agent-hook-setup claude`; pass `--force` to refresh existing command files.\n- **`brain status` shows the adapter as not installed** — run the matching `brain agent-hook-setup <agent>`.\n\n## Testing\n\n```bash\nnpm test                  # full suite\nnpm run test:unit\nnpm run test:integration\nnpm run test:e2e\nnpm run test:regression\n```\n\n## License\n\nMIT © 2026 Aviv Kaplan. See [LICENSE](./LICENSE).\n","readmeFilename":"README.md","_rev":"1-2f37187cfd29142885079055c9ebb829"}