v0.8.0 — Tag Governance, Vault Scaffolding & Plugin Distribution

Wires the tag-governance infrastructure that shipped inert in prior releases into the 3 skills that actually use it, lets cortex-forge-setup scaffold a brand-new vault instead of requiring one to already exist, closes a cortex-prune performance cliff that made it unusable on vaults of a few hundred pages, and adds a plugin-marketplace distribution channel alongside the existing npx skills add.

• Tag governance, wired in: cortex-assimilate validates proposed tags against wiki/meta/tags.md before writing a page; cortex-prune flags tags used exactly once with no backing page; cortex-forge-setup's maintenance menu can run the tag audit script. Nothing auto-mutates — all findings surface for human decision.
• New-vault scaffolding: cortex-forge-setup can now bootstrap a brand-new vault's wiki/ structure and a starter AGENTS.md instead of requiring them to pre-exist.
• Recall persistence + contradiction detection: cortex-recall offers to persist genuinely new synthesis and logs recall misses; cortex-prune flags factual contradictions between related pages and surfaces recurring recall misses as ingest candidates.
• Pasted-text ingestion: cortex-assimilate accepts pasted text as a source and falls back to it automatically when a fetch fails — covers sites that block scraping or sit behind a paywall.
• cortex-prune performance fix: orphan-page and unprocessed-.raw/ checks were O(n × m) and never finished on a 353-page vault (10+ min) — now ~17s.
• Plugin marketplace distribution: the skill suite is installable via /plugin marketplace add itsmistermoon/cortex-forge, alongside the existing npx skills add.

See CHANGELOG.md for the full detail.

v0.7.0 — npx-only Distribution, Security Hardening & Suite Compaction

Eliminates all local vault code execution, drops the tarball/curl-installer in favor of npx skills add (skills.sh) as the sole distribution channel, and closes out with a full compaction pass across all 6 skills.

• Zero vault-code-execution: scripts skills invoke now live co-located inside each skills/<name>/, never copied to {vault}/.cortex/db/. Found by a Snyk security audit (E006, CRITICAL) that flagged cortex-recall executing code potentially planted inside the vault.
• npx-only distribution: drops the tarball/curl-installer entirely — npx skills add itsmistermoon/cortex-forge is the sole channel, agent-agnostic across 40+ agents.
• Suite compaction: all 6 skills (crystallize, imprint, prune, assimilate, recall, forge-setup) rewritten for less text with zero loss of decision logic, fixing contradictory instructions and broken references found along the way.
• Locale-aware ephemeral prompts: the flavor line and every ephemeral prompt/menu/confirmation now follows the current conversation's language across all 6 skills, instead of being hardcoded in English — content persisted to the vault still follows locale:.
• Security hardening: mandatory in-place credential redaction before cortex-assimilate ever sees the sanitization output; batch confirmation before overwriting templates during upstream sync.
• CodeRabbit review against the full diff before this release — 8 real bugs confirmed and fixed (prefix-matching wikilinks in cortex-prune, PRAXIS pruning pointing at a nonexistent heading, missing single-vault-no-default fallback, error handling in sqlite-vec loading, among others).

See CHANGELOG.md for the full detail.

v0.6.0 — Hookless Protocol & skills.sh Compatibility

What's new in v0.6.0

This release removes agent lifecycle hooks entirely and makes cortex-forge installable via skills.sh (npx skills add), independent of the tarball/curl installer. It also includes a same-day fail-loud audit that closed every silent-failure path this change touched — including a regression the audit caught before it caused real damage.

---

Hookless protocol — one mechanism, every agent

SessionStart, PreCompact, SessionEnd, Stop, and PreToolUse hooks are gone. Support for these events was too uneven across Claude Code, Codex, Antigravity, and CommandCode to build the suite on top of them — two agents had hooks that silently misfired or deadlocked in live testing (see agent-hook-compatibility.md for the findings that drove the call).

• AGENTS.md now mandates reading .cortex/MEMORY.md before the first response and invoking /cortex-crystallize manually — identical on every agent, no hook wiring required
• Imprint-candidate detection moved from the (removed) SessionStart hook chain to a manual check against the latest ## History entry
• cortex-forge-setup and install.sh no longer install any hook symlinks or merge settings.json/hooks.json
• The only hook left is cortex-reindex-post-commit.sh — a git hook (fires on git commit), not an agent lifecycle hook, so it behaves identically regardless of which agent made the commit

---

Installable via npx skills add (skills.sh)

npx skills add itsmistermoon/cortex-forge --all

Every script a skill needs (cortex-prune.sh, cortex-sanitize.sh, cortex-validate-schema.sh, cortex-index.py, cortex-search.py, embeddings.py) now lives inside the skills/<name>/ directory that uses it, instead of a shared bin/ that only existed in the source repo. Each skill is fully self-contained and works whether it arrived via npx skills add, the tarball installer, or a plain git clone.

~/.cortex-forge/bin/ is demoted to a small runtime cache, populated only for the two git hooks (which need a fixed absolute path since they run outside any agent session) — it's no longer the source of truth for anything.

cortex-forge-setup also now detects a missing or incomplete tarball runtime before symlinking skills from it, and suggests npx skills add instead of silently creating broken symlinks.

install.sh keeps working exactly as before, in parallel — not deprecated.

---

Fail-loud audit

A follow-up pass reviewed every script for unbounded waits, unchecked mktemp, and broken path references:

• Regression caught same-day: the script co-location above moved cortex-prune.sh but left cortex-validate-schema.sh behind in bin/, silently disabling schema-drift checks for every install. CI now has an invariant (colocated-script-exists) that fails the build if this happens again.
• embeddings.py's real Ollama embed call had no timeout (only the 3s detection ping did) — a stalled Ollama server could hang indexing/search indefinitely. Added a 30s timeout.
• cortex-reindex-post-commit.sh's backgrounded reindex is now wrapped in a timeout, so a hang can't accumulate orphan processes across commits.
• cortex-prune.sh's mktemp failures and mid-run corruption now abort loudly instead of silently reporting "no findings."
• cortex-sanitize.sh now checks for jq (previously only checked rg) — a missing jq produced invalid JSON that cortex-assimilate could misread as "no findings."
• install.sh added --max-time to all network calls and a clear error instead of a cryptic git failure when the local dev checkout has uncommitted changes.
• Atomicity: vault-report.json and config.yml writes now go through a temp file + atomic rename, so a crash mid-write can't leave them truncated or empty.
• Investigated and confirmed clean: paths with spaces, sqlite concurrent-write handling, log growth. Manual YAML parsing remains a known, low-priority latent risk (adopting a real parser was judged not worth a new dependency).

Fixes

• cortex-reindex-post-commit.sh pointed at a nonexistent {vault}/bin/cortex-index.py — vaults other than the source repo never actually had a working reindex hook
• cortex-assimilate step 7 pointed at .cortex/cortex-index.py instead of .cortex/db/cortex-index.py
• A stray compiled .pyc file was accidentally tracked in git

Full Changelog: v0.5.0...v0.6.0

v0.5.0 — Backward Enrichment, Drift Detection & Skill Quality Hardening

What's new in v0.5.0

This release closes the skill quality hardening cycle started after v0.4.0, adds two new protocol behaviors to the ingestion and pruning pipelines, and consolidates the vault taxonomy to 4 canonical types.

---

Backward enrichment in `cortex-assimilate` (Step 9)

After ingesting a new source, the skill now scans existing wiki pages for candidates that should reference it.

• Identifies pages that share at least one tag with the new source AND have an `updated:` date predating the ingestion
• Classifies each candidate inline as ENRICHABLE or FALSE_POSITIVE
• For ENRICHABLE candidates: states exactly what to add and where
• Reports to user — no changes written without explicit confirmation per candidate
• Skipped if the source has no tags or fewer than 5 wiki pages exist

---

Drift detection in `cortex-prune` (Layer 3)

A new third layer detects when a raw source file has been updated but its wiki page hasn't.

• For each `wiki/sources/` page with a `raw:` field: reads `updated:` from frontmatter and compares against the `.raw/` file's mtime
• If `.raw/` mtime > `updated:` → MEDIUM finding
• Surfaces staleness that would otherwise go undetected across long ingestion gaps

---

Skill quality audit (writing-great-skills pass)

Applied Matt Pocock's whiteness test + 9 principles across the full skill suite:

• `cortex-assimilate`: step 5 gains a checkable completion criterion (zero qualifying types skipped)
• `cortex-imprint`: adds `disable-model-invocation: true` — skill is now mechanically manual-only, not just verbally instructed
• `cortex-forge-setup`: embedding dependency check (step 6d) extracted to `skills/cortex-forge-setup/EMBEDDING-SETUP.md` via context pointer
• `cortex-recall`: duplicate rules removed (`## Constraints` is authoritative); search-method note retained as unique content
• `cortex-prune`: remaining Spanish body text translated (sediment removal)

---

Locale resolution extracted

`skills/LOCALE-RESOLUTION.md` is now the single source of truth for the locale fallback chain. Five identical inline blocks across 5 skills replaced with a one-line context pointer. No behavior change — reduces future drift.

`cortex-crystallize` description enriched with session-close trigger phrases so the model invokes it when the user wants to wrap up or save context.

---

Vault taxonomy: 4 canonical types

Type `reference` deprecated. All existing `wiki/reference/` pages migrated to `type: concept`. Templates and `AGENTS.md` updated across all vaults.

`bin/cortex-validate-schema.sh` gains support for `type: series` in `wiki/pages/`.

---

Slash-tag convention

Tag notation `project/subtopic` adopted across all vault `AGENTS.md` files and templates. Obsidian renders these as nested tags under the prefix — no directory restructuring required.

Applied retroactively to 11 cortex-forge wiki pages:

• `cortex-forge/architecture`: cortex-forge-vs-alternatives, vault-design-karpathy-vs-hq, vault-mcp-server-pattern, embedding-backend-selection
• `cortex-forge/skills`: skill-dependency-graph, no-op-audit-adversarial-debate, skill-design-principles, skill-self-improvement-loop
• `cortex-forge/protocol`: crystallize-vs-imprint, crystallize-automation-architecture, agent-hook-compatibility

---

`cortex-prune` fixes

• `bin/cortex-prune.sh`: `sources:` YAML frontmatter now counts as a valid reference — pages linked from concept/entity `sources:` fields are no longer reported as orphans
• Layer 2: hard cap of 20 pairs / 20 sources; "spawn subagents" language replaced with always-inline evaluation

---

Knowledge base additions

• `wiki/concepts/skill-design-principles.md` — whiteness test, 9 principles, 11-item checklist for evaluating skill quality
• `wiki/concepts/skill-self-improvement-loop.md` — observer skill pattern, inner vs outer loop, Anthropic's eval-based variant
• `wiki/entities/compound-engineering.md` — Every Inc plugin, compound loop, skill-local prompt assets architecture
• 4 new sources ingested: `anthropic-skill-creator`, `writing-great-skills`, `compound-engineering-plugin`, `skill-optimization-loop`

---

Upgrade

# Pull latest skills
curl -fsSL https://github.com/itsmistermoon/cortex-forge/releases/latest/download/cortex-forge.tar.gz | tar -xz -C ~/.cortex-forge

# No schema changes — existing wiki pages are fully compatible with v0.5.0

Full Changelog: v0.4.0...v0.5.0

v0.4.0 — Protocol Hardening & Autonomous Imprint

What's new in v0.4.0

This release closes Phase 2 (Protocol Hardening) and Phase 2.5, completing the planned hardening cycle that began after v0.3.0. The vault is now production-stable for multi-agent use across Claude Code, Codex, CommandCode, and Antigravity.

---

⚠️ Breaking: .hot/ → .cortex/ consolidation

The mutable zone is now exclusively .cortex/. .hot/ is removed.

• MEMORY.md, PRAXIS.md, imprint-draft.md, db/, imprint-candidates.md — all under .cortex/
• All hooks updated to write to .cortex/ instead of .hot/
• Existing vaults: rename .hot/ to .cortex/ manually, or re-run /cortex-forge-setup

---

Autonomous imprint pipeline (auto mode)

When imprint_triage: auto is set in config.yml, session crystallize now automatically writes wiki pages without agent intervention.

• bin/hooks/cortex-imprint-auto.sh — new script invoked from cortex-reactivate.sh at SessionStart. Reads .cortex/imprint-draft.md + session transcript, calls claude -p (Haiku) with vault identity + templates, writes the page, updates wiki/index.md and wiki/meta/log.md, removes the draft.
• Runs in background — SessionStart is never blocked.
• Safeguards: skips if page already exists, exits cleanly on missing transcript, falls back to nudge if script not found.
• suggest mode unchanged.

---

Hook distribution architecture

New propagation model separates source from runtime:

bin/hooks/                  ← git-tracked source
~/.cortex-forge/bin/hooks/  ← runtime copies (owned by cortex-forge-setup)
~/.claude/hooks/            ← symlinks → runtime
~/.gemini/config/hooks/     ← symlinks → runtime
~/.codex/hooks/             ← symlinks → runtime

/cortex-forge-setup update propagates all changes. No more per-agent manual installs.

---

.cortex/PRAXIS.md — permanent agent context split

MEMORY.md (session state, volatile) and PRAXIS.md (accumulated conventions + working context with 30-day TTL) are now separate files. CODEX.md absorbed into AGENTS.md under ## Vault identity.

---

Multi-vault support

~/.cortex-forge/config.yml with vaults: {name: path} + default:. Vault resolved by CWD first, then default. /cortex-forge-setup registers/deregisters the current vault (toggle by CWD). Legacy vault: key supported.

---

Semantic search — stable backend (Phase 3.6)

• bin/embeddings.py — Ollama → mlx-embeddings → sentence-transformers with per-backend error messages and Codex config.toml hint.
• bin/cortex-index.py and bin/cortex-search.py consolidated from .cortex/db/ to bin/.
• Auto-reindex on assimilate — cortex-assimilate triggers re-index of newly added pages.
• Post-commit hook — re-indexes only wiki/ files modified in each commit.
• Codex sandbox fix: Codex blocks loopback by default. Fix via ~/.codex/config.toml documented in SKILL.md and wiki/concepts/agent-hook-compatibility.md.
• MLX compatibility status documented in wiki/concepts/embedding-backend-selection.md — both available packages fail on Python 3.14 + transformers 5.x. Gate for switching: upstream update.
• nomic-embed-text-v2-moe upgrade path gated on ollama/ollama#16076.

---

Antigravity crystallize hook removed

cortex-crystallize-antigravity.sh retired after live testing (2026-06-27) confirmed two structural blockers:

1. No /exit hook — process killed abruptly, hook never fires.
2. agy -p deadlocks when called from a hook while a primary session is alive.

Crystallize in Antigravity is manual-only. /cortex-crystallize skill unchanged.

---

Stale cache detection

hot_cache_stale_days: in config.yml. cortex-reactivate.sh injects a warning at session start if .cortex/MEMORY.md hasn't been updated in more than N days. CONSOLIDATED.md fallback added for vaults with history archive.

---

Protocol hardening (Phase 2)

• Context fencing in cortex-imprint — source hierarchy: session > .raw/ > wiki/ (reference only). Circular synthesis test. raw: field in provenance.
• Behavior tags — behavior: frontmatter in all skills: #ingest, #synthesize, #recall, #prune, #snapshot, #configure.
• Link-count scan — orphan page detection in cortex-prune.sh; orphan_pages in vault-report.json, surfaced at session start.
• cortex-recall hardening — blocks Explore as bypass, accounts for optional embedding index, clarifies fallback behavior.
• Compliance guardrails — verifiable contracts in AGENTS.md + mandatory output format in cortex-recall, cortex-assimilate, cortex-crystallize.
• Schema versioning — schema_version: "0.3" in AGENTS.md and all templates.
• AGENT-LOG migrated to wiki/meta/agent-diagnostics.md.

---

Knowledge base additions

• wiki/concepts/embedding-backend-selection.md — MLX compatibility table, Codex sandbox note, v2-moe upgrade path.
• wiki/concepts/crystallize-automation-architecture.md — per-agent crystallize matrix with root constraints verified against .raw/ sources.
• VISUAL_IDENTITY.md — canonical visual direction for Cortex Forge.

---

Known limitations

• Codex crystallize: manual-only. Transcript format incompatible with Claude parser; Stop fires per-turn.
• MLX embedding backend: blocked by transformers 5.x incompatibility. Ollama remains default.
• Phase 3 items pending: onboarding guide, example pages, MCP server, cortex-prune dual mode.

---

Upgrade

cd /path/to/cortex-forge
git pull

# Rename mutable zone (if upgrading from v0.3.0)
mv .hot/ .cortex/          # inside your vault, if it exists

# Propagate hooks to runtime
/cortex-forge-setup update

No template schema changes — existing wiki pages are fully compatible with v0.4.0.

Full Changelog: v0.3.0...v0.4.0

v0.3.0 — Multi-vault, cortex-prune global

What's in this release?

Multi-vault (all skills)

All skills now accept an explicit vault argument: /cortex-recall work <query>, /cortex-imprint personal, /cortex-prune staging. Resolution priority: explicit argument → CWD → default vault.

cortex-prune as a global skill

cortex-prune is now installed globally (like all other skills), not only in local vaults. Includes:

• Confirmation gate: if the vault is specified as an explicit argument, prompts for confirmation before operating
• Consolidating subagent (Step 5): reduces main agent context at the end of analysis
• Agent/model-agnostic subagents: the skill delegates with "lightest capable model available" instead of a hardcoded model; falls back inline if the environment doesn't support subagents

Phase 3.6 — Semantic retrieval (planned)

Extended roadmap with implementation plan for semantic search over the vault:

• Stack: sqlite-vec + platform-aware embeddings (mlx-embeddings on Apple Silicon, sentence-transformers universal)
• Shared module .cortex/embeddings.py with load_embedding_model() / embed()
• Stage 2 (FastMCP server) gated on validated Stage 1 + >1 client

Documented design decisions

wiki/pages/cortex-forge.md extended with 7 new decisions: why sqlite-vec, why Ollama was discarded, why MCP is deferred, dot product as metric, Leiden/Graphify discarded.

New wiki pages

• wiki/entities/codex.md — Codex CLI (OpenAI), hook compatibility
• wiki/entities/graphify.md — Graphify (66.3k stars, YC S26), CommandCode gap
• wiki/concepts/headless-agent-mode.md — -p, --yolo flags, cross-agent session persistence
• wiki/concepts/tool-context-budget.md — 30K tokens of tool schemas before the first message
• wiki/concepts/agent-permission-model.md — cross-agent permission surface

Fixes

• bin/cortex-prune.sh: fix double-.md in wikilinks and fix grep over JSON files (now --include="*.md")
• Cross-wikilinks in 7 concept pages

Schema

schema_version: "0.3" in AGENTS.md and all templates.

---

Upgrading from v0.1.0: run /cortex-forge-setup to install the global symlink for cortex-prune (~/.claude/skills/cortex-prune).

v0.2.0 — CODEX.md, Reference taxonomy, AI Coding Dictionary, handoff improvements

What's new

Protocol improvements

• CODEX.md — new vault identity file (Mission, Owner, Domains, Vocabulary, Out of scope), read at session start after .hot/MEMORY.md. All skills now check it for relevance and vocabulary decisions.
• Parametric knowledge disqualified — cortex-recall protocol now explicitly rejects agent training knowledge for vault topics. The vault is always the source of truth.
• Reference taxonomy — fifth wiki type for lookup tables, wire formats, and cheat sheets (wiki/reference/, templates/reference.md). Distinct from Concept: no prose, just tables and code blocks.

Session memory

• fix: PreCompact now uses claude -p — previously generated a raw list of file paths with no description. Both PreCompact and SessionEnd now synthesize descriptive bullets. Each prompt includes a note distinguishing compaction (mid-session, session continues) from handoff (no return path).
• MEMORY-FORMAT.md: new trigger table (PreCompact vs SessionEnd), optional ### Suggested skills section in Zone 1, argument next: <focus> for /cortex-crystallize to orient the snapshot toward what comes next.

Vault setup

• Templates co-located with skills — MEMORY-FORMAT.md (crystallize), CODEX-FORMAT.md and TASTE-FORMAT.md (forge-setup) live next to their skill, not in a separate templates directory.
• .hot/MEMORY.md fixed name — removed project-name detection; one file per repo, safe across projects.
• AGENT-LOG.md replaces AGENTS-TESTING.md — append-only session bitácora with a minimal template and explicit rules to avoid format drift between agents.

Knowledge base

• AI Coding Dictionary ingested — 68 entries from Matt Pocock's dictionary (wiki/sources/ai-coding-dictionary.md, .raw/ai-coding-dictionary.md)
• 5 new concept pages: parametric-knowledge, contextual-knowledge, memory-system, handoff-artifact (with design decisions section), smart-zone
• wiki/concepts/handoff-artifact.md documents the design decisions behind .hot/MEMORY.md: why .hot/ instead of /tmp, two-zone structure, fixed naming, compaction vs handoff distinction.
• AGENTS.md architecture table labels .raw/ as primary sources and wiki/ as secondary sources, with conflict resolution rule.

Docs

• README updated: 6 layers, 6 skills, 5 wiki types, accurate agent compatibility table, promo image.

v0.1.0 — First usable release

Cortex Forge is a session memory protocol for AI agents. It gives any agent — Claude Code, Codex, Antigravity, CommandCode, or others — persistent context across sessions through a shared vault structure.

What works in v0.1.0

Core skills (installable via /cortex-forge-setup):

• cortex-crystallize — snapshot session context into .hot/MEMORY.md
• cortex-assimilate — ingest a URL or file into the vault; synthesizes wiki pages with SPA detection fallback
• cortex-recall — query synthesized vault knowledge with wiki/ citations
• cortex-imprint — archive a session synthesis as a permanent wiki page
• cortex-prune — detect orphans, dead links, and stale claims in the vault

Protocol:

• Multi-vault support via ~/.cortex-forge/config.yml
• AGENTS.md with MANDATORY protocols and verifiable compliance criteria for recall, assimilation, and crystallize
• Parametric knowledge explicitly disqualified as a source for vault topics — epistemological rule, not just workflow instruction
• Cross-project snapshots (crystallize from outside the vault, updates linked vault page)
• Skills include explicit output format requirements and failure mode handling (SPA STOP guard, citation requirement)
• Vault selection as explicit argument: /cortex-recall second-brain <query> from any project
• Invoke messages per skill (Crystallizing memory..., Recalling memory..., etc.)

Vault structure:

• CODEX.md — vault context file: Mission, Owner, Domains, Vocabulary, Out of scope; read by all skills
• wiki/reference/ — new taxonomy type for lookup tables, wire formats, cheat sheets (distinct from Concept)
• Templates co-located with their skills: MEMORY-FORMAT.md, CODEX-FORMAT.md, TASTE-FORMAT.md
• .hot/MEMORY.md — fixed filename (previously {project}.md); simpler hook scripts

Agent compatibility (tested):

• Claude Code — full hook support (SessionStart, PreCompact, SessionEnd)
• Codex — native SessionStart hook confirmed; Stop hook pending real-session validation
• Antigravity CLI — PreInvocation + Stop hooks configured; real-session crystallize pending
• CommandCode — Capa 1 (AGENTS.md MANDATORY) confirmed; Stop hook installed in second-brain/

Known limitations

• cortex-recall compliance depends on model obedience — PostToolUse hook guardrail is next
• Antigravity and Codex Stop hooks validated with mock payloads only, not real session closes
• cortex-forge-setup step 7 (TASTE rule) is blocked by CommandCode system policy — must run from Claude Code
• Skills in ~/.agents/skills/ are manual copies — no auto-sync after updates

Getting started

git clone https://github.com/itsmistermoon/cortex-forge your-vault
cd your-vault
# Open in Claude Code and run:
/cortex-forge-setup