Immutable. This exact content is served forever at /api/v1/blob/9e3e18cc82e81204.
# codemem - Public repo: never add secrets, internal hostnames, private identifiers, or local artifact paths. Keep `.tmp/`, `.venv/`, `*.sqlite`, `packages/*/dist/`, `packages/viewer-server/static/`, and `.opencode/package-lock.json` out of git. - Default to the TypeScript toolchain: this repo is a pnpm workspace on Node 24; use the pnpm version pinned by the root `packageManager` field. ## What runs where - CLI entrypoint: `packages/cli/src/index.ts` (`pnpm run codemem ...`). - Shared store/search/sync logic and exported version: `packages/core/src/index.ts`. - Viewer HTTP API + SPA host: `packages/viewer-server/src/index.ts`. - Viewer UI source: `packages/ui/src/`. - OpenCode plugin source of truth: `packages/opencode-plugin/.opencode/plugins/codemem.js`. - `packages/cli/.opencode/plugins/codemem.js` and repo-root `.opencode/plugins/codemem.js` are wrappers/re-exports, not the main implementation. - `packages/cloudflare-coordinator-worker/` is its own worker package with separate tests. ## Commands worth using - Install: `pnpm install` - Full local gate / CI order: `pnpm run tsc && pnpm run lint && pnpm run test` (`pnpm run check`) - Build everything: `pnpm run build` - Run CLI from source: `pnpm run codemem --help` - Run one vitest file: `pnpm exec vitest run packages/cli/src/commands/serve.test.ts` - Run one package script: `pnpm --filter codemem test`, `pnpm --filter @codemem/ui build`, `pnpm --filter @codemem/cloudflare-coordinator-worker test:worker` - E2E smoke: `CODEMEM_E2E_BUILD=1 CODEMEM_E2E_JSON=1 pnpm run e2e:smoke -- --json` (artifacts land in `.tmp/e2e-artifacts`) ## Gotchas agents usually miss - `pnpm run lint` only checks files included by `biome.json` (mostly `packages/**` TS/TSX/JS/JSON and root TS config). Docs like `AGENTS.md` are outside Biome. - `pnpm run test` is workspace vitest; root `vitest.config.ts` points at `packages/*/vite.config.ts`. - The viewer server throws if `packages/viewer-server/static/index.html` is missing. If you change UI or viewer assets, run `pnpm build` or at least `pnpm --filter @codemem/ui build`. - `packages/viewer-server/static/` is generated and ignored. Do not hand-edit it. UI build stages `packages/ui/static/` there alongside the built `app.js` bundle. - Plugin smoke tests rely on nested `.opencode` runtime deps. CI installs `@opencode-ai/plugin` inside `packages/cli/.opencode` and `packages/opencode-plugin/.opencode` before running smoke tests. - CLI work should follow `docs/cli-design-conventions.md`: max 2 nesting levels, noun-based groups, shared `--db-path` / `--config` / `--json` helpers, and no uncaught throws from command handlers. - The repo is TS-first; trust `package.json`, package scripts, and CI over older migration-era docs/checklists. - `.github/PULL_REQUEST_TEMPLATE.md` is TS-first now; use `pnpm run tsc`, `pnpm run lint`, and `pnpm run test` for normal changes. ## Workflow rules specific to this repo - Use `bd` for issue tracking, not markdown TODOs: `bd ready --json`, `bd create ... --json`, `bd close ... --json`. - If you change plugin behavior, update `README.md` and any affected docs under `docs/`. - If you change memory kinds or their presentation, update all three surfaces together: `packages/core/src/store.ts`, `packages/mcp-server/src/index.ts`, and `packages/ui/src/tabs/feed.ts`. ## Release traps - Release tags trigger publishing. Tag only the merged `main` commit, not a `release/*` branch tip. - Version alignment is scripted in `scripts/release-version.mjs`; tag safety is enforced by `pnpm run release:preflight-tag` / `scripts/release-tag-preflight.sh`. - Releases publish to the public npm registry; keep `.opencode/.npmrc` pointed at `https://registry.npmjs.org/`.