Make your AI remember the work

Koed helps your AI coding tool remember useful context from previous work, so it can bring back project decisions, debugging history, and other details when you need them.

Quickstart

[!IMPORTANT] Codex, Claude Code, and Pi are independently installed supported AI Client integrations. Koed core setup does not require any AI Client. Koed does not bundle AI Client runtimes or provider credentials; configure each client only after core services are ready.

Requirements

• macOS, Linux, or WSL.
• Node.js and pnpm.
• Homebrew for the source-checkout bundled-local runtime install. Packaged Desktop can use packaged native runtime assets; external dependency mode does not require Homebrew.
• No AI Client is required for core Koed readiness.
• Optionally, install and authenticate Codex, Claude Code, or Pi before explicitly configuring that client. Claude Code requires 2.1.227 or newer; Pi requires 0.84.2 or newer. Claude synthesis reuses the local Claude Code subscription through the pinned Agent SDK. Pi synthesis reuses Pi-managed local authentication through isolated RPC.

If you are on Windows, run Koed inside WSL as Linux tooling. Keep KOED_HOME and checkout paths on Linux filesystem paths inside WSL; native Windows packaged app support is not shipped in this build.

Start Koed Desktop from source

From a fresh clone, run:

pnpm install
pnpm local:setup
KOED_DEPENDENCY_MODE=bundled-local KOED_AUTO_PORTS=1 pnpm desktop:start

pnpm local:setup prepares .env, builds the workspace, links the Homebrew-backed bundled-local runtime, and installs the pinned embedding and Privacy Filter models.

Koed Desktop opens when core setup is complete. Mandatory setup does not configure or select an AI Client. Configure Codex, Claude Code, or Pi independently with their integration guides below. Packaged Desktop follows the same local-personal bundled-local flow, but it starts its managed koed-server from the app bundle, prefers packaged native runtime assets, and keeps KOED_HOME state outside the source checkout. See Koed Desktop for packaged first-run, signing/notarization, and smoke details.

If setup fails with a path like /path/to, unset any placeholder overrides from previous experiments before restarting Desktop:

unset KOED_HOME KOED_EMBEDDING_MODEL_PATH KOED_RERANKER_MODEL_PATH

To stop Koed later:

node packages/koed-server/dist/cli.js stop --json

Headless Operators can prepare client-neutral core state and create or reuse the Local AI Runtime credential with:

node packages/koed-server/dist/cli.js setup core --json

setup codex --json remains an explicit Codex profile compatibility command; it never selects Codex merely because Codex is installed.

Health and routing model

Core health covers Koed services and remains healthy with zero configured AI Clients. Client installation, authentication, capture, capability snapshots, and synthesis readiness are separate per-client diagnostics; one broken client does not make core unhealthy. A stale or unavailable capability snapshot blocks only affected operations.

Memory Answer, LCM Summary, Session Title, and Curated Memory Review each have an independent provider, AI Client instance, model, and reasoning-effort assignment. Persisted assignments take precedence over environment defaults; environment and documented Codex defaults apply only when no assignment exists. An explicit unavailable assignment fails closed and never falls back to another client or provider.

Managed Conversations are separate from ordinary externally managed Conversations: Koed owns lifecycle and exact AI Client instance for Managed Conversations, while Codex, Claude Code, or Pi owns its ordinary Conversation and Koed captures its source through that client's watcher. Managed Conversation ownership does not select synthesis providers. See Managed Conversation routing.

Advanced setup and configuration

The README keeps to one basic local path. For other options, see:

• Running Koed for external dependency mode, manual server commands, alternate ports, smoke tests, packaged first-run notes, and desktop development.
• Koed Desktop for the Personal/Team information model, collaboration workflows, recovery behavior, accessibility, and performance boundaries.
• Configuration for environment variables, runtime modes, model overrides, logging, and production settings.
• Codex integration for manual Codex setup and recovery.
• Claude Code integration for capture, recall, and local Claude synthesis setup.
• Pi integration for global package setup, persistent session capture, Recall tools, and isolated local Pi RPC synthesis.
• Curated Memory for source-linked durable facts and recall behavior.
• Personal Device Sync controls for opt-in future-Session replication, recovery-kit ceremony, and headless Operator secret references.
• Security, Backup and restore, and Upgrades for operational guidance.

For local Desktop, private VPS, Team Self-Hosted, and cloud deployment language, use koed-server plus dependencies as the product boundary. API and Worker remain useful implementation names for code, logs, and troubleshooting. The retired Explorer is not a process or deployment dependency.

Security Notes

Koed assumes the operator controls the deployment. The API supports bearer API tokens for AI-client integrations. Local operators create tokens with pnpm api-token:create, which uses trusted database access and stores only token hashes. Postgres and Redis should stay on private Docker/internal networks in production deployments. See docs/security.md.

Local personal deployments may keep operational Memory rows in Postgres unless app-layer encryption is configured. Private VPS, Team Self-Hosted, and Koed-managed cloud deployments should configure envelope encryption for human-readable Memory and evidence payloads; queryable vectors still remain sensitive trusted-boundary data. Protect the database, volumes, backups, and administrator access with deployment-level controls.

Report suspected vulnerabilities privately. See SECURITY.md for supported versions, the reporting channel, and guidance on not disclosing user Memory data publicly.

Operations

Use normal Postgres backups and restore into the same Koed version before upgrading. The API runs database migrations during startup.

Local Operators can also run the same Drizzle migration path manually with:

pnpm --filter @koed/db migrate:up

See docs/backup-restore.md, docs/hosted-backups.md, and docs/upgrades.md.

Releases

Koed uses one product release version for the self-hosted distribution. Add a changeset for release-noteworthy changes:

pnpm changeset

See docs/upgrades.md for upgrade guidance.

License

Koed is licensed under the Apache License 2.0 (Apache-2.0). See LICENSE, CONTRIBUTING.md, and docs/license.md. Apache-2.0 is also offered for Koed's repository history; existing AGPL grants remain valid. See Commercial Feature Boundary for the public distribution, Team Self-Hosted, hosted-only services, and managed add-ons.

Learn More

• Running Koed
• Koed Desktop
• Configuration
• Server deployment boundary
• Hosted database roles
• Security
• Backup and restore
• Hosted backups
• Upgrades
• CI and release validation
• Codex integration
• Curated Memory
• License
• Commercial feature boundary