Koed is a universal memory layer for AI clients. It captures project knowledge, coding sessions, decisions, debugging history, and remembered context, then makes that memory available through MCP recall.
- Automatic conversation capture with hooks.
- Seamless recall for prior conversations, project history, and remembered context.
- Explorer for inspecting captured Koed memory.
- Postgres + pgvector storage under your control.
- Local embedding, reranking, and Redis-backed memory processing.
Important
Codex is currently the only supported AI Client integration for capture and recall. Future integrations are tracked separately.
Run the guided local bootstrap in one step:
pnpm clients:bootstrapThe Explorer runs beside the API:
http://localhost:5174
pnpm codex:bootstrap creates or reuses the local API token, builds
@koed/db and @koed/mcp-server, writes the Codex MCP and Capture Hook
configuration, verifies capture, and finishes with a doctor check.
pnpm explorer:bootstrap writes the token into Explorer local config and
refreshes the Docker-built Explorer. pnpm clients:bootstrap runs the guided
end-to-end path. See docs/codex-integration.md
for manual setup and deeper Codex integration details.
Start from .env.example:
pnpm env:setupSee Configuration for all environment variables, embedding settings, logging options, AI client values, and production notes.
Koed is composed of the following primary services:
| Path | Role |
|---|---|
apps/api |
API for auth, capture policy, memory capture, recall, graph inspection, export, and diagnostics |
apps/worker |
Background memory and embedding jobs |
apps/embedding-service |
Local embedding and reranking service |
apps/explorer |
Explorer UI for inspecting captured Koed memory |
packages/mcp-server |
MCP Server, local answer bridge, and Codex Capture Hook |
packages/db |
Postgres repositories, migrations, and operator scripts |
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.
Memory payloads remain plaintext at the application layer in Postgres in the current build. 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.
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:upSee docs/backup-restore.md and docs/upgrades.md.
Koed currently uses one product release version for the Docker Compose distribution. Add a changeset for release-noteworthy changes:
pnpm changesetSelect @koed/koed and choose the SemVer bump for the deployment as a whole.
Merging to main creates or updates a release pull request. Merging that
release pull request verifies the release commit, creates a single vX.Y.Z tag,
and publishes a GitHub Release.
Koed is licensed under the GNU Affero General Public License version 3 only
(AGPL-3.0-only). See LICENSE, CONTRIBUTING.md,
and docs/license.md.