cli: Instructions file for Codex

Agent Instructions

Project Overview

Konteks is a local-first memory engine and MCP-enabled CLI for AI coding agents. It builds project-local memory artifacts under .konteks/ and exposes warm-up, recall, save, search, and forget workflows through the CLI and MCP server.

Tech Stack

• Runtime/package manager: Bun >=1.3 with Node.js >=22 support.
• Language: strict TypeScript, ESM modules, path alias @/* for src/*.
• Build/test tooling: tsup, Bun test, Biome, Knip, and tsc --noEmit.
• Formatting/linting: Biome enforces kebab-case filenames, single quotes, no semicolons unless required, organized imports, and no explicit any.

Repository Layout

• src/entrypoints/cli: CLI command registration and command handlers.
• src/entrypoints/mcp: MCP server, prompts, handlers, and tools.
• src/modules: domain logic for memory, extraction, project state, and embeddings.
• src/database: schema, persistence services, actions, migrations, and database utilities.
• src/support: shared filesystem, CLI, output, formatting, TUI, and error-log utilities.
• src/assets: bundled prompts, grammar registry, and ignore-rule assets.
• tests/features: behavior-focused test coverage for CLI, MCP, memory, extraction, and project flows.
• tests/support and tests/fake: test helpers and fakes.

Common Commands

bun run dev
bun run lint
bun run check

• bun run dev runs the CLI from src/main.ts.
• bun run lint runs Biome formatting/checks, Knip, and TypeScript.
• bun run check runs build, lint, and tests.

Coding Guidelines

• Keep changes scoped to the relevant entrypoint, module, database, or support boundary.
• Prefer existing helpers and public APIs over new abstractions or direct database access.
• Preserve strict TypeScript behavior; do not introduce any or loosen compiler settings.
• Keep .konteks/ local and ignored. Do not commit generated memory artifacts.
• Keep project error logging best-effort and non-blocking; logging failures must not mask original CLI or MCP errors.
• Route CLI color and branded header output through src/support/console-output; prefer consoleOutput.print(color => ...), consoleOutput.writeError(color => ...), consoleOutput.header(), and consoleOutput.printHeader() over importing palette or banner helpers in command code.
• Keep ConsoleOutput.colorPalette as semantic string wrappers only: dim, error, info, primary, secondary, success, and warning. Keep raw RGB helpers, gradients, and banner-specific color logic private to console-output support modules.
• Preserve rebuild semantics: konteks rebuild rebuilds derived memory artifacts and must preserve durable memories and diary entries.
• Keep ignore matching fail-safe across ecosystems unless a deliberate product change says otherwise.
• Do not reintroduce file-size caps, per-file section caps, word chunking caps, or embedding/FTS retrieval truncation in core SQLite payload handling.
• Update docs when changing user-facing CLI behavior, MCP behavior, setup steps, storage behavior, or terminology.