Cortex

The upgrade path is a normal version bump on a semantically versioned package: claude plugin update, a new .mcpb, or pip install -U hypermnesia-mcp. Store-format changes ship as one-shot migrations executed on startup (mcp_server/migrate.py, mcp_server/infrastructure/pg_schema.py) rather than back-compat shims, so an older store is upgraded in place. Every behaviour or contract change a consumer can observe is recorded in https://github.com/cdeust/Cortex/blob/main/CHANGELOG.md (Keep a Changelog), with breaking changes called out explicitly and the migration step named; SECURITY.md states that security patches target the latest minor release.

GitHub Issues is used as the bug tracker: https://github.com/cdeust/Cortex/issues

No vulnerability has been reported and resolved in the last 12 months, so there is no reporter to credit. The standing commitment to credit reporters unless they request anonymity is documented at https://github.com/cdeust/Cortex/blob/main/SECURITY.md#recognition.

https://github.com/cdeust/Cortex/blob/main/SECURITY.md — private advisory channel, a per-severity response and patch SLA (24h/7d for critical, 3d/14d for high, 7d best-effort otherwise), and a five-step disclosure timeline ending in a public advisory on an agreed date. GitHub private vulnerability reporting is enabled on the repository.

https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#coding-standards-excerpt names the standard for the primary language (Python): ruff formatting and linting as the style baseline, plus the project's own load-bearing rules (no Any in production code, sourced constants, no bare except, file and function size limits), with the full text at https://github.com/cdeust/zetetic-team-subagents/blob/main/rules/coding-standards.md. Compliance is required of contributions, not suggested.

Automatically enforced in CI on every push and pull request: ruff format --check . and ruff check . with ruff pinned at 0.15.20, plus a pyright per-rule ratchet (scripts/check_pyright_ratchet.py) that fails the build if any rule's diagnostic count rises above its committed floor. Style exceptions are per-line # noqa with the rule code named at the site. See .github/workflows/ci.yml (jobs lint and typecheck).

No native binaries are produced. Cortex is pure Python packaged with hatchling; there is no compiler or linker invocation for CC/CFLAGS/LDFLAGS to reach.

Nothing is compiled or stripped: the installed artifact is Python source in a wheel, so tracebacks always carry full file, line and symbol information. There is no debugging information a build or install step could discard.

The build is a single non-recursive hatchling invocation over one package ([tool.hatch.build.targets.wheel] packages = ["mcp_server"] in pyproject.toml). There is no per-subdirectory build and therefore no cross-directory dependency for a recursive build to get wrong.

No compilation occurs — Python source is used directly, which is the case this criterion names as not applicable. The integrity of what is distributed is established instead by a SHA-256 per release asset and a Sigstore build-provenance attestation binding each artifact digest to the repository and workflow that produced it: https://github.com/cdeust/Cortex/blob/main/SECURITY.md#supply-chain-assurance.

Three commonly-used conventions, all documented in the README's Getting Started section: the single-click .mcpb bundle for Claude Desktop, the Claude Code plugin marketplace (claude plugin install, uninstalled with claude plugin uninstall), and the Python package manager (pip install hypermnesia-mcp, removed with pip uninstall). All state lives under ~/.claude/methodology/, which the user deletes to remove it fully (https://github.com/cdeust/Cortex/blob/main/PRIVACY.md#your-controls).

Installation is delegated to the language package manager, so it honours that ecosystem's standard conventions: pip/uv install into the active environment or the location --target/--prefix/VIRTUAL_ENV selects, and the plugin and .mcpb installs write where the host dictates. No bespoke prefix handling is implemented that could ignore them.

https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#dev-setup — git clone then pip install -e ".[postgresql,benchmarks,dev]" installs the project, the test environment and the benchmark extras in one command; the default SQLite store means the suite runs with nothing else provisioned. bash scripts/setup.sh additionally installs PostgreSQL + pgvector for the integration tests, and python -m mcp_server.doctor verifies the result.

Declared in computer-processable form: runtime and per-extra dependencies in https://github.com/cdeust/Cortex/blob/main/pyproject.toml, resolved and pinned transitively in https://github.com/cdeust/Cortex/blob/main/uv.lock, and republished per release as a CycloneDX SBOM (hypermnesia-mcp.cdx.json) generated from that lockfile and attached to the GitHub Release with its own provenance attestation.

GitHub Dependabot alerts and automated security fixes are both enabled on the repository (verified via the GitHub API on 2026-07-27: /vulnerability-alerts returns 204 and /automated-security-fixes reports enabled and not paused), so the dependency graph — including the ML stack that dominates the attack surface — is checked continuously against the advisory database and fixes are proposed automatically. Current state: zero open alerts. A CycloneDX SBOM ships with every release for downstream scanning.

No vendored or forked copies of external components are committed: every dependency is a normal versioned package resolved by pip/uv from pyproject.toml and uv.lock (the local deps/ tree used when assembling the bundle is git-ignored and rebuilt from the lockfile, not maintained by hand). Updating a vulnerable component is a version bump in one place.

The stack targets currently supported runtimes and APIs: Python 3.10 through 3.13, all four in the CI matrix, with pgvector 0.3+/PostgreSQL 17 and current major versions of FastMCP, Pydantic v2, numpy and sentence-transformers. Deprecated interfaces are removed rather than wrapped — the standing rule is one-shot migrations with no back-compat shims (CLAUDE.md), and CI runs on the newest released Python so a deprecation surfaces as a warning in the build rather than as a surprise at end of life.

The full suite runs on every push and pull request to main via .github/workflows/ci.yml and reports success or failure per job: 5587 tests on Python 3.10-3.13 against PostgreSQL + pgvector, the same suite against the SQLite backend, the suite on Windows, and a Docker smoke job that boots the bare container and exercises the DB-less contract. tests_py/integration/ holds the database-backed integration tests specifically.

Measured on 2026-07-27 over the merged pull requests titled as fixes in the preceding six months (2026-01-27 onward): 23 of 30 — 76.7% — changed the test tree in the same PR, against the 50% this criterion asks for. (The measure counts a PR as carrying tests when it touches tests_py/ or tests_js/, which is a proxy for 'added a regression test'; the policy behind it is written down at https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory — a bug fix carries a regression test that fails on the pre-fix code.)

Statement coverage is 82.02% (30,229 of 36,854 statements in mcp_server), measured by coverage.py 7.15.2 in the CI coverage job, run 30316548703 (2026-07-28) — above the 80% this criterion requires. The gap was closed by https://github.com/cdeust/Cortex/issues/196: the four zero-importer modules were wired-and-tested or removed with proof, and contract tests now cover the previously-uncovered context-assembly, hook, and wiki modules. The figure cannot silently fall back: the same CI coverage job enforces --cov-fail-under=82 as a floor, seeded at the achieved number.

https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md#the-testing-policy-mandatory states it as policy, not preference: every change that adds or alters externally observable behaviour must arrive with tests in the same pull request, new functionality ships with tests in the automated suite, a bug fix carries a regression test that fails on the pre-fix code, and each failure path asserts its observable effect including the signal it emits. The consequence is stated — such a PR is sent back rather than merged with a follow-up promise.

The requirement is written down in CONTRIBUTING.md's per-tool and per-mechanism checklists rather than left to convention: https://github.com/cdeust/Cortex/blob/main/CONTRIBUTING.md

Maximally strict, by configuration rather than promise. Ruff runs an explicit broadened rule set — select = [E4, E7, E9, F, S110, BLE001, PLR2004, E501, PLC0415, S608] (pyproject.toml [tool.ruff.lint]) — with every production finding fixed or carrying a per-site noqa naming its mechanism, and CI fails on any finding. Pyright (pinned 1.1.410) runs typeCheckingMode standard over mcp_server/ with ZERO diagnostics (568-diagnostic ratchet backlog burned to zero, measured 2026-07-28, issue #197); the per-rule ratchet is retired and CI fails on ANY pyright diagnostic via its exit code. strict mode is not practical: it reports 10,231 errors, about 9,300 of them the Unknown-type annotation-coverage family (measured 2026-07-27). See .github/workflows/ci.yml jobs lint and typecheck.

https://github.com/cdeust/Cortex/blob/main/docs/ASSURANCE-CASE.md#4-secure-design-principles-applied maps each principle to the code that implements it: least privilege and no ambient authority (no network listener, no privileged install, destructive tools rejected on call under the lean profile rather than merely hidden), fail-safe defaults (local SQLite by default, telemetry off until an env var is set, a malformed ingest writes nothing), complete mediation (one middleware chain and one schema check for every tool call), economy of mechanism (one write path, one retrieval path, one ingestion seam), and separation of concerns as a security property (the layer rule keeps all I/O auditable as a set).

No security mechanism depends on cryptography, so there is no default algorithm choice whose weakening would matter. See the crypto_working justification for the single non-security SHA-1 use.

No security mechanism in Cortex depends on a cryptographic algorithm, so there is no algorithm choice for a user to switch. Hashing is used only for content addressing (SHA-256/BLAKE2b via hashlib) and for MinHash sketching, where the single SHA-1 call protects nothing.

The only credential Cortex handles is the PostgreSQL connection string, and it is read from the DATABASE_URL environment variable (or the user's own MCP host configuration) — never from source, and never written into the store. Changing or rotating it is an environment change with no code change and no recompilation; the value is masked structurally before it can reach a log or diagnostic output (mcp_server/shared/redaction.py::redact_url). Cortex generates and stores no private keys.

Every network communication Cortex initiates uses a secure protocol: HTTPS for the one-time embedding/reranker model download from Hugging Face and for the GitHub API calls in the optional pipeline installer, and libpq for PostgreSQL (with TLS controlled by the user's own connection string). No insecure protocol is supported or enabled by default — the server itself opens no socket and listens on no port; its control channel is stdio.

TLS is used through CPython's stdlib (urllib/ssl over OpenSSL) with default contexts, whose minimum accepted version on every supported Python (3.10-3.13) is TLS 1.2. No code path lowers the minimum version, sets a custom protocol constant, or weakens the cipher policy: grep over mcp_server for ssl context manipulation returns nothing.

Certificate verification is the stdlib default and is never disabled: there is no verify=False, no ssl._create_unverified_context, no check_hostname = False and no CERT_NONE anywhere in the codebase (verified by grep over mcp_server, scripts and hooks on 2026-07-27). Every outbound request goes through urllib with the default verified context.

The same default verified TLS context applies to every outbound request, so verification completes before any headers are sent. In practice Cortex sends no private information over TLS at all: the model download is an anonymous public fetch and the GitHub API calls are unauthenticated release lookups; memory content never leaves the machine.

Every release is cryptographically signed and the verification process is documented for users at https://github.com/cdeust/Cortex/blob/main/SECURITY.md#supply-chain-assurance. The wheel, the sdist and the CycloneDX SBOM each carry a Sigstore-backed build-provenance attestation minted in .github/workflows/release.yml (gh attestation verify <file> --repo cdeust/Cortex), the PyPI channel publishes with PEP 740 attestations via Trusted Publishing, and every release asset ships a <asset>.sha256 companion checked by scripts/verify_release_artifact.py. Signing is keyless: there is no private key held on the distribution site, or anywhere else.

Input from the host is validated against an allowlist before any handler runs: each MCP tool declares a typed signature and JSON schema, and FastMCP rejects arguments that do not match; mcp_server/validation/schemas.py adds a per-tool type and required-field check on top. Content parsed from untrusted documents is handled as data by pure stdlib parsers that fail loudly and write nothing on malformed input. Where a query has to become SQL, values cross as bound parameters and identifiers come from explicit allowlists (_TABLE_WHITELIST / _COLUMN_WHITELIST in mcp_server/core/wiki_view_executor.py) with unknown names refused rather than escaped, and result limits are clamped to a maximum. The full argument is in https://github.com/cdeust/Cortex/blob/main/docs/ASSURANCE-CASE.md#5-common-implementation-weaknesses-and-how-each-is-countered.

https://github.com/cdeust/Cortex/blob/main/docs/ASSURANCE-CASE.md — security requirements (including what a user must NOT expect), a six-entry threat model with the out-of-scope adversaries named, the five trust boundaries where data or execution changes trust level, secure design principles mapped to the code implementing each, a CWE-by-CWE table of countered implementation weaknesses with its evidence, and a closing section on what the case does not claim (prompt injection through recalled content, 74.83% coverage, warnings not yet maximally strict, no dynamic analysis).

CodeQL's default query suite is specifically a vulnerability-detection suite (injection, path traversal, unsafe deserialization and similar), and it is configured with the 'remote' threat model.

Cortex is written in Python, a memory-safe language, so the memory-safety tooling this criterion asks about (ASan, Valgrind) does not apply.