TT-Wang/cortex-plugin

The OSS-readiness release. Cortex now self-installs on first run via a uv-backed bootstrap shim, gracefully degrades when optional dependencies are missing, ships a /cortex-doctor preflight skill, and validates A-tier on the Glama MCP registry across all three quality dimensions.

Highlights

• Self-healing install. The MCP command in plugin.json now points at bootstrap.sh, which on first run installs uv if missing, hash-caches a uv sync against the committed uv.lock into a plugin-local .venv, canary-tests directory writability, writes ~/.cortex/.capabilities, and exec's the server. ~5s on first run, ~100ms on every subsequent run. No separate pip install step required.
• Graceful degraded mode. When the claude CLI is missing, context_assemble and smart_recall return raw playbook+memories materials instead of failing. The SessionStart status banner makes this visible: [Cortex] N memories · miner OK · assembly degraded.
• /cortex-doctor — preflight health check that pretty-prints HEALTHY / DEGRADED / FAILING with explicit fix instructions for any blocker.
• Glama A-A-A. Validated on Glama with A-tier scores across license_grade, security_grade, and TDQS (Tool Definition Quality Score). Every MCP tool now carries a multi-paragraph docstring with read/write classification, auth requirements, rate limits, data scope, idempotency, failure modes, and worked examples — plus pydantic.Field(description=...) on every parameter with length/range constraints.
• Reliable miner auto-start. _auto_start_miner is now poll-and-log: Popens the wrapper, then polls the miner PID file for up to 2s and logs a clear warning if the daemon doesn't come up. Falls back to plain bash when setsid is missing.
• Lazy MCP import. Non-MCP CLI commands (--status, --rebuild-index, --doctor, etc.) no longer require the mcp package to be importable — verified via a poisoned-import smoke test.
• Packaging refactor. Renamed cortex-mcp-server/ → cortex_server/ (a real Python package identifier), miner-daemon.py → miner_daemon.py, all intra-package imports rewritten, tests no longer hack sys.path.
• CI gate. Mypy is now blocking (no more || true). A new build job builds a wheel and smoke-tests it in a clean venv on every push.

Reliability fixes

• _extract_json_string (mining) now uses json.JSONDecoder.raw_decode to respect string literals, fixing false-negative parse failures on Haiku output containing unbalanced brackets inside titles
• _check_contradictions requires word-set containment ≥ 0.3 before flagging (was over-eager, could trigger wrongful mass deprecations)
• purge_mined_memories now removes deleted memories from FTS5 + _index.md (was orphaning both)
• save_mined_session_state fsyncs before rename — closes a crash-window data-loss path
• _record_access (telemetry) uses atomic writes; corrupt JSON is preserved as <file>.corrupt.<mtime> instead of being silently overwritten
• _save_memory writes the memory once instead of twice with a stale-index window between
• _yaml_escape strips control characters from values to prevent frontmatter injection from titles
• Tag and related field values are sanitized (no [, ], ,, \n) to prevent frontmatter injection from hallucinated mining output
• Recall no longer raises ValueError on memories with missing IDs
• Module-level RotatingFileHandler and basicConfig in miner_daemon.py moved into a function so importing the module is side-effect-free

Testing

• 54 tests passing (was 48 in 0.5.0)
• New: tests/test_bootstrap.py (6 subprocess-level shim tests), tests/test_packaging.py runtime tests for miner-wrapper.sh, mine-cron.sh, and auto-recall.sh, tests/test_obsidian_store.py::test_purge_mined_memories_clears_fts_and_index regression guard
• Ruff clean
• Mypy strict-clean

Discovery / packaging

• Submitted to the Anthropic Claude Code plugin marketplace
• Submitted to awesome-mcp-servers (punkpeye/awesome-mcp-servers#4612, awaiting merge)
• Listed on Glama with A-tier across all three dimensions
• llms.txt for LLM crawler discovery
• SECURITY.md with vulnerability reporting policy
• Repo About description, homepage, and 10 GitHub topics set

Install

/plugin marketplace add TT-Wang/cortex-plugin
/plugin install cortex

That's it. First run takes ~5 seconds (the bootstrap shim does everything). Every run after is ~100ms.

See CHANGELOG.md for the full change list.