context-engine

context-engine is the top-level workspace that coordinates the graph crates in context-stack, the viewer and operator tooling in memory-viewers, and the repo-local configuration and install surfaces that bind them together.

Getting Started

Before step 1, install Git, a Rust toolchain with cargo and rustup, and a Bash shell (Git Bash on Windows). Node/npm are not required for this bootstrap or the Trunk-based viewer frontends. install-deps.sh installs ripgrep, rtk, trunk, cargo-llvm-cov (and llvm-tools-preview), and cargo-make.

From a fresh clone, bootstrap everything with a single script:

bash bootstrap.sh

This also regenerates .github/agents/, .github/prompts/, and .github/instructions/ from this repo's canonical .agents/ sources, so a Copilot CLI session opened in this repo automatically sees the repository's custom agents, prompt templates, and path-scoped instructions with no extra setup step. If a step fails, bootstrap.sh stops immediately and prints which step failed and the exact command to re-run once the reported problem is fixed; every step is safe to re-run, including bootstrap.sh itself.

bootstrap.sh runs the following steps in order; each is documented and can also be run standalone for partial/advanced setups:

bash setup_git.sh
./install-deps.sh
./install-tools.sh --mcp
bash init.sh
bash tools/verify-bootstrap.sh

Repository Map

The root-level repo_map.toon file is the compact structural index for this repository. Refresh it with:

cargo run -p peek-cli -- . --repo-map --output repo_map.toon

Use peek repo_map.toon --grep "crates" for bounded inspection or decode/query it as TOON when automation needs machine-readable structure.

Child repo or folder	What it contains	Direct README
context-stack	Graph, search, insert, and read crates plus extracted support dependencies.	context-stack/README.md
memory-viewers	Viewer binaries, CLI/MCP/HTTP tooling, and shared viewer runtime packages.	memory-viewers/README.md
config	Shared tracing and repository configuration.	config/README.md

context-stack child READMEs:

• context-stack/context-api/README.md
• context-stack/context-trace/README.md
• context-stack/context-search/README.md
• context-stack/context-insert/README.md
• context-stack/context-read/README.md

memory-viewers child READMEs:

• memory-api/README.md
• viewer-api/README.md

Installable Tools

The shared installer in install-tools.sh refreshes the 30 executable Rust binaries and installable tooling surfaced by this repository.

Install the complete MCP server set used by VS Code with:

./install-tools.sh --mcp

The MCP configuration invokes these installed binaries directly rather than running Cargo for each request. Ensure Cargo's binary directory ($HOME/.cargo/bin on Unix or %USERPROFILE%\\.cargo\\bin on Windows) is on the PATH inherited by VS Code, then run Developer: Reload Window to restart and rediscover the servers.

The companion installer in install-deps.sh installs the repo-wide developer dependencies listed in Getting Started.

The companion installer in install-extensions.sh packages and installs the workspace's VS Code extensions into your local VS Code profile:

• memory-api/ticket-vscode/package.json exposes the ticket-vscode extension package and the repo-local VSIX install workflow.

• memory-viewers/README.md covers the top-level viewer workflows and the spec-viewer and ticket-viewer binaries.

• viewer-api/README.md covers the install-ctl binary and the trunk-backed frontend toolchain.

• memory-api/README.md covers the rule, spec, ticket, and audit CLIs, the cargo llvm-cov coverage collector used by audit, and the MCP and HTTP surfaces behind them.

• memory-viewers/doc-viewer/README.md covers the doc-viewer binary.

• memory-viewers/log-viewer/README.md covers the log-viewer binary.

Working With Submodules

Getting Started initializes submodules and attaches them to their configured tracking branches. Once initialization completes, continue from context-stack/README.md and memory-viewers/README.md for repository-local commands.

Workflow Tools

context-engine consumes workflow-tool domain crates through their canonical Git sources and invokes installed workflow-tool binaries. Install the commit-pinned workflow-tools bundle before running commands that require install-ctl, session-capture-hook, or an MCP transport.

Workspace Validation

cargo test --workspace
cargo doc --workspace --open

• cargo test --workspace is documented in The Cargo Book: cargo test.
• cargo doc --workspace --open is documented in The Cargo Book: cargo doc.
• Crate-specific validation entry points live in context-stack/README.md and the child READMEs linked above.