@danielblomma/cortex-mcp 2.2.5 → 2.4.1

package/CHANGELOG.md

@@ -0,0 +1,201 @@
+# Changelog
+
+## 2.4.1 — 2026-07-28
+
+### Security
+
+- Validated remote enterprise skill names, blocked symlink targets, and
+  added Cortex ownership markers so personal skill directories cannot be
+  overwritten or recursively deleted. Deletion targets are derived from
+  managed CLI roots instead of trusting cached absolute paths.
+- Bound license-cache reuse to the normalized endpoint and a one-way API-key
+  fingerprint. Malformed, future-dated, and expired cache assertions fail
+  closed; HTTP 401/403 responses reject authorization without grace.
+- Changed enterprise onboarding to read API keys from stdin and atomically
+  create `.context/enterprise.yml` with mode `0600`. Remote endpoints require
+  HTTPS, with a loopback-only HTTP exception for local development.
+- Bound user-global organization artifacts and host process detection to one
+  opaque Enterprise credential identity per OS user. A conflicting endpoint
+  is rejected, same-endpoint API-key rotation safely purges old marker-owned
+  skills and caches, and only one host-wide process scanner runs.
+- Moved unattributed process findings into a credential-bound, mode-`0600`
+  user-global queue instead of the first project's audit directory.
+- Enterprise admin commands now execute only package-owned trusted code.
+  Repository runtime modules and project-local state writes never execute with
+  root authority; persisted govern paths are not deletion authority.
+- Suppressed shared-proxy project audit events when a connection has no
+  trustworthy project attribution.
+- Added verified socket-based daemon stop/restart. Bootstrap now restarts an
+  already-running daemon so the upgraded security code replaces the old
+  in-memory runtime, and init repairs preserved Enterprise configs to `0600`.
+- Updated the frontend and packaged MCP dependency trees to patched PostCSS,
+  SDK, Hono, archive, URI, YAML, protobuf, ONNX ZIP, and Sharp versions. All
+  committed npm lockfiles now have a zero-vulnerability audit target.
+
+### Changed
+
+- Replace `sudo cortex enterprise <api-key>` with:
+
+  ```bash
+  printf '%s\n' "$CORTEX_API_KEY" |
+    sudo cortex enterprise install --api-key-stdin
+  ```
+
+- After updating the npm package, run `cortex init --force` and
+  `cortex bootstrap`. The latter safely restarts a verified running daemon;
+  an npm update alone does not activate this fix in an existing process.
+- Existing Enterprise users must then rerun the stdin install to create the
+  durable host-identity marker. Confirm
+  `cortex enterprise status --json` reports
+  `enterprise.host_identity_bound: true`; Cortex never auto-enrolls from a
+  repository config.
+- The minimum supported runtime is Node.js 20.9 (the first Node 20 LTS
+  release), required by the patched native embedding dependency chain.
+- Before re-enrollment, review legacy `~/.cortex/skills.local.json` records
+  without `credential_id`, back up each exact matching Claude/Codex skill
+  directory outside the discovery roots, and back up the state file. Ambiguous
+  legacy directories are deliberately not adopted or deleted automatically.
+
+### Rollout and emergency containment
+
+- Do not downgrade to 2.4.0: that reopens the remote skill traversal boundary.
+  Use a forward fix.
+- Before rollout, back up `.context/enterprise.yml` with ownership and mode
+  preserved. After restore, verify the correct owner and run
+  `chmod 600 .context/enterprise.yml`.
+- If suspicious remote organization content is observed, run
+  `cortex daemon stop` and stop Enterprise AI sessions until a forward fix is
+  installed. Enforced hooks intentionally fail closed while the daemon is
+  unavailable.
+- After rollout, verify `cortex daemon status` reports a verified PID,
+  `cortex enterprise status` is healthy, the config mode is `0600`, and a
+  canary organization sync cannot overwrite an unmanaged personal skill.
+
+## 2.4.0 — 2026-07-13
+
+### Added
+
+- Added a native agent behavior layer: dual plugin manifests (Claude Code +
+  Codex), five Cortex skills with trigger descriptions, a cached
+  SessionStart bootstrap that survives clear/compaction, and a Claude Code
+  marketplace entry.
+
+### Changed
+
+- Upgraded the `cortex init` AGENTS.md section from an update reminder to a
+  compact using-cortex bootstrap.
+
+## 2.3.0 — 2026-07-13
+
+### Added
+
+- Added `cortex pattern-evidence <file-path|entity-id>` for cited, structured
+  review evidence ordered by same file, module, feature area, and repository
+  fallback.
+- Integrated bounded, non-blocking pattern context into enterprise
+  `context.review` without changing policy pass/fail or workflow trust.
+
+### Changed
+
+- Made equal-score search ordering deterministic with stable entity/path
+  tie-breaks.
+- Added strict numeric validation for CLI query limits.
+- Fixed the enterprise runtime package-version lookup so compiled enterprise
+  tools load from the packaged MCP runtime.
+- Made `context.review` scope=changed list staged and untracked files in
+  repositories without commits instead of falling back to a full project
+  walk that ignores `.gitignore`.
+- Made pattern review context load the Cortex index once per review instead
+  of once per target, and cached the ranking reference-time scan per loaded
+  index.
+- Unified review path canonicalization and text comparison on the shared
+  pattern-evidence and search helpers.
+
+## 2.2.5 — 2026-06-21
+
+### Changed
+
+- Made the default embedding token-budget `auto` mode memory-aware: Cortex
+  still starts from the embedding model's maximum context, but degrades to a
+  safe cap when local memory headroom is unlikely to fit the full context.
+
+## 2.2.4 — 2026-06-20
+
+### Changed
+
+- Added an explicit embedding token-budget profile and benchmark support for
+  `CORTEX_EMBED_MAX_TOKENS`.
+- Kept the default `auto` token budget quality-preserving: Cortex uses the
+  embedding model's own maximum context unless a numeric cap is explicitly set.
+- Reduced embedding memory overhead by avoiding full normalized-text copies for
+  cached entities before deciding what needs re-embedding.
+
+## 2.1.0 — 2026-06-11
+
+New features and behavior changes, no API breaks.
+
+### Changed
+
+- **Default embedding model is now `jinaai/jina-embeddings-v2-base-code`**
+  (was `Xenova/all-MiniLM-L6-v2`). The old model truncated input at 512
+  tokens, which clipped the majority of file-level embeddings in typical
+  repositories and made code-oriented queries miss implementation files.
+  The jina code model has an 8192-token window. Override with
+  `CORTEX_EMBED_MODEL` as before.
+- **Embedding input text is no longer character-capped.** The previous
+  7000-char entity cap and 2000-char chunk-body preview (and the
+  `CORTEX_EMBED_MAX_CHARS` env var) were calibrated for small models. The
+  tokenizer's own 8192-token truncation is now the only limit.
+  `CORTEX_EMBED_MAX_CHARS` is removed and silently ignored if set.
+- **`graph_score` now uses a midrank percentile of relation degree within
+  the entity's own type** instead of `min(1, degree/4)`, which saturated at
+  degree >= 4 and made the graph ranking weight a constant for nearly every
+  entity. Percentiles are type-neutral (every type averages ~0.5), so
+  hub-heavy types such as rules cannot drown out leaf code.
+- **Default ranking weights changed** to `semantic: 0.55, graph: 0.10,
+  trust: 0.20, recency: 0.15` (was `0.40 / 0.25 / 0.20 / 0.15`). Graph
+  degree mostly measures how many rules constrain an entity, so it gets low
+  weight; this reweighting and the percentile graph_score were benchmarked
+  as a pair. **Existing projects keep their per-project `config.yaml` —
+  ranking weights are NOT updated automatically.** To adopt the new
+  defaults, edit `.context/config.yaml`:
+
+  ```yaml
+  ranking:
+    semantic: 0.55
+    graph: 0.10
+    trust: 0.20
+    recency: 0.15
+  ```
+
+### Added
+
+- **Markdown chunking.** `.md`/`.mdx` files are now chunked into H1–H3
+  heading-bounded sections (headings inside fenced code blocks are ignored,
+  preamble before the first heading is captured, empty sections are
+  skipped). Long sections are window-split with overlap, so prose gets
+  overlap while code stays symbol-chunked without it. Queries that target a
+  specific document section now return that section chunk directly.
+- `rules.yaml` is now preserved on re-scaffold (`cortex init --force`),
+  alongside `config.yaml`, so project-specific rules survive upgrades.
+
+### Upgrading an existing project
+
+1. `npm i -g @danielblomma/cortex-mcp@2.1.0`
+2. In the project: `cortex init --force` (re-scaffolds `.context/mcp` and
+   `.context/scripts`; your `config.yaml`, `rules.yaml`, notes and
+   decisions are preserved), then `cortex bootstrap`.
+3. `cortex update` — the stored embedding-model id no longer matches, so
+   this triggers a **full re-embed automatically**. Cost: roughly 2 minutes
+   per 1000 entities plus a one-time download of the jina ONNX model. The
+   embeddings file grows (768-dim vectors vs 384).
+4. Restart the MCP server (e.g. restart your editor/agent session) — the
+   compiled search code only loads on process start.
+
+Known quirk: the MCP server lazy-loads the embeddings file, so the first
+search immediately after a re-embed can be served from a stale cache —
+re-run the query.
+
+## 2.0.19 and earlier
+
+See git history (`git log --oneline`) and GitHub releases.

package/README.md

@@ -79,7 +79,7 @@ The result is an assistant that behaves as if it already knows your codebase, be
 
 ## Requirements
 
-- Node.js 20+
+- Node.js 20.9+ (Node 20 LTS or newer)
 - Git repository
 - Optional for MCP registration: `claude` and/or `codex` CLI in `PATH`
 
@@ -96,15 +96,31 @@ To upgrade an already-scaffolded project to a new Cortex version:
 ```bash
 npm i -g @danielblomma/cortex-mcp
 cortex init --force   # re-scaffolds .context runtime + .context/scripts
-cortex bootstrap
+cortex bootstrap     # rebuilds and safely restarts a verified running daemon
 cortex update
 ```
 
 `cortex init --force` preserves per-project files: `.context/config.yaml`,
-`.context/rules.yaml`, and your notes/decisions.
+`.context/rules.yaml`, `.context/enterprise.yml`, and your notes/decisions.
+It repairs existing Enterprise config permissions to `0600` without rewriting
+the file. An npm update alone does not replace code already loaded by the
+per-user daemon; `cortex bootstrap` performs the verified restart.
 
 Version-specific notes (see [CHANGELOG.md](CHANGELOG.md) for details):
 
+- **2.4.1**: enterprise onboarding no longer accepts API keys as positional
+  arguments. Pipe the key to
+  `sudo cortex enterprise install --api-key-stdin`. Enterprise endpoints must
+  use HTTPS (loopback HTTP remains available for local development). Existing
+  Enterprise users must rerun that stdin install after `cortex bootstrap`;
+  enrollment is deliberately not inferred from repository config. Verify
+  `cortex enterprise status --json` reports
+  `enterprise.host_identity_bound: true`. One Enterprise endpoint is supported
+  per OS user because organization skills and host process detection are
+  user-global; an explicit install may rotate its API key. Before upgrading
+  legacy organization skills without Cortex ownership markers, back up and
+  move the exact reviewed directories listed by
+  `~/.cortex/skills.local.json` out of the Claude/Codex discovery roots.
 - **2.1.0**: the default embedding model changed, so the first
   `cortex update` after upgrading triggers a full re-embed automatically
   (~2 min per 1000 entities plus a one-time model download). The
@@ -143,6 +159,26 @@ Check context status:
 cortex status
 ```
 
+## Agent plugin (Claude Code + Codex)
+
+The `plugins/cortex` directory is a dual-manifest agent plugin: five behavior
+skills (`using-cortex`, `repo-research`, `change-impact`, `pattern-review`,
+`context-review`), a SessionStart bootstrap that re-injects Cortex
+instructions after new sessions, `/clear`, and compaction (Claude Code), and
+an MCP config that follows the active workspace.
+
+Claude Code:
+
+```bash
+/plugin marketplace add DanielBlomma/cortex
+/plugin install cortex@cortex
+```
+
+Codex discovers the same skills through `.codex-plugin/plugin.json`; repos
+initialized with `cortex init` also get an AGENTS.md bootstrap section as a
+fallback when the plugin is not installed. The CLI remains the engine — the
+plugin only adds the behavior layer, and `cortex connect` stays opt-in.
+
 ## Query From The CLI
 
 Use the CLI as the default local agent interface:
@@ -153,6 +189,7 @@ cortex related file:src/auth.ts --json
 cortex impact "payment service" --json
 cortex rules --json
 cortex explain "where retries are configured" --json
+cortex pattern-evidence src/auth.ts --query "error handling" --json
 ```
 
 These commands read the same local graph, embeddings, and rules used by the MCP server, but they do not require an MCP client registration.
@@ -381,12 +418,39 @@ cortex related <entity-id> [--json]
 cortex impact <query|entity-id> [--json]
 cortex rules [--json]
 cortex explain <query|entity-id> [--json]
+cortex pattern-evidence <file-path|entity-id> [--query <text>] [--top-k <n>] [--json]
 cortex status
 cortex dashboard [--interval <sec>]
 cortex watch [start|stop|status|run|once] [--interval <sec>] [--debounce <sec>] [--mode <auto|event|poll>]
 cortex help
 ```
 
+## Enterprise Pattern Review
+
+Enterprise `context.review` includes bounded repo-local pattern context by
+default. This evidence is advisory and does not change policy validator totals,
+workflow approval, or review trust.
+
+Optional MCP inputs:
+
+- `include_pattern_evidence` — enable or disable pattern context (default `true`).
+- `pattern_query` — shared pattern query; otherwise Cortex derives one per file.
+- `pattern_top_k` — evidence items per locality tier, from 1 to 5 (default `2`).
+- `pattern_limit` — analyzed review targets, from 1 to 25 (default `10`).
+
+The response adds `pattern_review` with deterministic targets, the canonical
+review question, cited evidence tiers, explicit repository fallback, unindexed
+status, and omitted-file counts. Pattern evidence never constitutes automatic
+code approval. Enterprise pattern review is lexical-only and never downloads an
+embedding model or calls an external service.
+
+Every target uses the same response fields. `status` is one of
+`local_evidence`, `repo_fallback`, `no_evidence`, `not_indexed`, or `error`;
+`local_pattern_found` and `fallback_used` are always explicit booleans, and
+`evidence_order` plus all four `tiers` are always present. Unavailable evidence
+uses empty tiers and sanitized messages rather than local paths or runtime
+errors.
+
 ## Automated Release
 
 This repository includes two GitHub Actions workflows:
@@ -428,6 +492,12 @@ set it to `model` or `full` to force the full-model baseline even on tight
 machines. When several cortex instances share one machine, set
 `CORTEX_EMBED_THREADS` to give each its fair share of cores.
 
+For experiments on very large repositories, `CORTEX_EMBED_TEXT_PROFILE=compact-files`
+compacts only large file-level embedding records while keeping chunk-level
+embedding text full. The default remains `full`; use the compact profile only
+with a before/after semantic quality check because file-level compaction can
+change retrieval behavior.
+
 ## Limitations
 
 - Requires repo initialization (`cortex init --bootstrap`).