Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
119 lines (87 loc) · 4.07 KB

CONTRIBUTING.md

File metadata and controls

119 lines (87 loc) · 4.07 KB
Raw

Contributing to Cortex

Thanks for contributing. Cortex is a local-first memory system for AI agents, with a Rust daemon and a Tauri desktop app. Keep changes focused, documented, and easy to verify.

Before You Start

  • Search existing issues and pull requests before opening a new one.
  • Prefer small, reviewable PRs over broad refactors.
  • If your change affects behavior, update docs in the same PR.
  • If your change affects APIs or workflows, update README.md or Info/connecting.md.

Multi-Model Development

  • Cortex work is coordinated across Claude, Gemini, Codex, and local models.
  • Check open issues and Info/roadmap.md before starting to avoid duplicate work.
  • If you claim a roadmap item, note scope and milestone clearly in your PR description.

Development Setup

Prerequisites

  • Rust 1.78+ (required for daemon): Install from https://rustup.rs/
  • Node.js 18+ (required for desktop app): Install from https://nodejs.org/
  • Windows users: MSVC build tools (required for Rust): x86 Native Tools Command Prompt for VS
  • Linux users: pkg-config and libssl-dev (required for some dependencies): sudo apt install pkg-config libssl-dev
  • macOS users: Xcode command line tools: xcode-select --install

Core daemon

git clone https://github.com/AdityaVG13/cortex.git
cd cortex
cargo build -p cortex-daemon --release
# Binary at target/release/cortex(.exe)
# Package name is cortex-daemon; sources live in crates/daemon and crates/logic.

Desktop app

cd desktop/cortex-control-center
npm ci
npm run dev

Recommended Checks

Run the checks relevant to the area you changed. See Info/testing-philosophy.md for what we optimize for (release boundaries, not exhaustive unit coverage).

Daemon / Rust changes

cargo fmt
cargo check -p cortex-daemon --all-features
# Optional for most PRs; required before release or when touching CLI output:
cargo test -p cortex-tests --test cli_goldens
# When changing recall, store, clocks, or graph:
cargo test -p cortex-tests --offline --test clock_quorum --test cli_goldens --test store_recall --test conflict --test temporal --test history --test recall_truth -- --test-threads=4
# Full suite only when changing core recall/store/MCP behavior:
cargo test -p cortex-tests
cargo clippy -p cortex-daemon --all-targets --all-features -- -D warnings

For setup or auth-token changes, include a focused regression check for token persistence failures. Team setup must not report success unless the owner API key was written to the shared cortex.token path. Token permission changes need platform proof: Unix mode checks or Windows DACL/ACL regression coverage.

Desktop / frontend changes

cd desktop/cortex-control-center
npm test
npm run build
npm run verify:lifecycle:dev

Release / smoke (maintainers)

bash tests/scripts/first-run-smoke.sh
cargo test -p cortex-tests --test cli_goldens

Root convenience scripts

From the repo root:

npm run daemon:clippy
npm run daemon:check
npm run test
npm run build
npm run desktop:build
npm run desktop:verify:lifecycle:dev

Pull Request Guidelines

  • Use a clear title and explain the user-visible impact.
  • Include screenshots or GIFs for UI changes.
  • Call out breaking changes explicitly.
  • Note any follow-up work that is intentionally out of scope.

Documentation Expectations

Please update docs when you change:

  • installation or setup steps,
  • public HTTP or MCP behavior,
  • auth or security expectations,
  • desktop workflows,
  • release artifacts or supported platforms.

Scope and Style

  • Keep dependencies justified; local-first and low-runtime-complexity are project priorities.
  • Do not reinstall embeddings, ONNX, tokenizers, or a reranker on the hot path.
  • Avoid silently changing security-sensitive defaults.
  • Do not commit local databases, logs, personal config, or machine-specific artifacts.

For security issues, do not open a public issue with exploit details. Follow Info/security-rules.md.