# https://github.com/JuliusBrussee/cavemem Project Manual Generated at: 2026-06-14 22:46:19 UTC ## Table of Contents - [Overview](#page-overview) - [Cli](#page-apps-cli) - [Src](#page-apps-cli-src) - [Commands](#page-apps-cli-src-commands) ## Overview ### Related Pages Related topics: [Cli](#page-apps-cli)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) - [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md) - [package.json](https://github.com/JuliusBrussee/cavemem/blob/main/package.json) - [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json) - [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) - [packages/compress/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/package.json) - [packages/compress/src/compress.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/compress.ts) - [packages/compress/src/lexicon.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.ts) - [packages/compress/src/count.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/count.ts) - [packages/core/src/types.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/core/src/types.ts) - [biome.json](https://github.com/JuliusBrussee/cavemem/blob/main/biome.json) - [CODE_OF_CONDUCT.md](https://github.com/JuliusBrussee/cavemem/blob/main/CODE_OF_CONDUCT.md)
# Overview ## Purpose and Scope **cavemem** is a cross-agent persistent memory system for AI coding assistants. It captures observations emitted by editor sessions, compresses prose using a deterministic caveman grammar (~75% fewer prose tokens), persists entries to a local SQLite store, and exposes them to agents through a Model Context Protocol (MCP) server and a read-only web viewer. The project signature property — documented in `Source: [CLAUDE.md:7-13]()` — is that **memory is stored compressed**: every write path runs text through `@cavemem/compress`, and every human-facing read path expands it back through `@cavemem/compress#expand`. The system is shipped as the `cavemem` npm package (`Source: [apps/cli/package.json:1-10]()`) and supports five host environments out of the box: **Claude Code, Cursor, Gemini CLI, OpenCode, and Codex**. Per the README headline (`Source: [README.md:1-10]()`), the design priorities are local-first storage, hybrid retrieval, and progressive disclosure so that agents filter before they fetch. ## Architecture and Monorepo Layout cavemem is a pnpm-managed monorepo (`Source: [package.json:14-19]()`) that splits responsibilities across a small number of workspace packages and applications. The top-level release script is `changeset publish`, and the build runs `pnpm -r --filter "./packages/*" --filter "./apps/*" build` (`Source: [package.json:17-19]()`). | Workspace | Role | |---|---| | `@cavemem/compress` (`Source: [packages/compress/package.json:1-10]()`) | Deterministic grammar-based compression library with round-trip-safe expansion. | | `@cavemem/core` (`Source: [packages/core/src/types.ts:1-19]()`) | Shared types (`Observation`, `Session`, `SearchResult`) and the `MemoryStore` write boundary. | | `apps/cli` (`Source: [apps/cli/package.json:6-9]()`) | `cavemem` executable: installer, hook scripts, `start`/`stop`/`viewer`/`doctor`/`search`/`mcp` subcommands. | | `apps/mcp-server` | Stdio MCP server exposing `search`, `timeline`, `get_observations`, `list_sessions`. | | `apps/worker` | Optional background daemon that handles embedding backfill and serves the local web viewer. | The package manager is pinned (`"packageManager": "pnpm@9.12.0"`, `Source: [package.json:21-22]()`), the Node engine is `>=20.0.0` (`Source: [apps/cli/package.json:36-38]()`), and linting/formatting is centralized through Biome (`Source: [biome.json:1-26]()`). ## End-to-End Data Flow The capture → store → retrieve pipeline is the spine of the system. Hooks fire at session boundaries in the host IDE, write synchronously to SQLite, and may detach-spawn a worker for embedding backfill; they never wait on the worker (`Source: [CLAUDE.md:25-28]()` and `Source: [apps/cli/CHANGELOG.md:25-30]()`). ```mermaid flowchart LR IDE["IDE hook event
(SessionStart / PostToolUse / SessionEnd)"] --> HOOK["Hook script
apps/cli/hooks-scripts"] HOOK --> REDACT["redact <private>...</private>"] REDACT --> COMP["@cavemem/compress
compress.ts"] COMP --> STORE["MemoryStore
SQLite + FTS5"] STORE --> EMBED["Worker (detached)
vector index"] STORE --> MCP["MCP server
search · timeline · get_observations"] MCP --> AGENT["Agent query"] STORE --> VIEW["Web viewer
127.0.0.1:37777"] ``` Three invariants are encoded as non-negotiable rules in the agent playbook (`Source: [CLAUDE.md:17-28]()`): 1. **All persisted prose passes through `packages/compress` before storage.** Writing raw prose to SQLite is treated as a defect. 2. **Technical tokens are never compressed.** Code blocks, URLs, file paths, shell commands, version numbers, dates, numeric literals, and quoted identifiers are preserved byte-for-byte by the tokenizer in `packages/compress/src/tokenize.ts`. 3. **Progressive disclosure in MCP.** Compact summaries from `search`/`timeline` first; full bodies via `get_observations` only when needed. ## Compression Engine The compression library is intentionally deterministic and reversible. The lexicon module (`Source: [packages/compress/src/lexicon.ts:1-26]()`) exposes intensity-scoped lookups for fillers, articles, hedges, pleasantries, and abbreviations. The compressor (`Source: [packages/compress/src/compress.ts:11-50]()`) operates in passes: it removes phrase lists (sorted longest-first so multi-word phrases match before single words), then applies word-level abbreviation while preserving the original casing via `matchCase`. The reverse direction is provided by the `expansions` map. Token accounting uses a cheap estimator in `Source: [packages/compress/src/count.ts:3-9]()` that combines whitespace-separated words with a `chars/4` floor — sufficient for relative comparisons between compressed and expanded output without depending on a real tokenizer. ## Operational Model and CLI Surface There is no daemon on the write path (`Source: [apps/cli/CHANGELOG.md:25-30]()`). Hooks write synchronously; the worker auto-spawns on the first hook and self-exits when idle. The CLI exposes installer and inspection commands (`Source: [apps/cli/package.json:8-10]()` and `Source: [README.md:50-70]()`): `install [--ide]`, `status`, `viewer`, `doctor`, `search`, `compress`, `reindex`, `export`, `start`/`stop`/`restart`, and `mcp`. Settings live in `~/.cavemem/settings.json` and the schema is self-documenting via the `settingsDocs()` export from `@cavemem/config` (`Source: [apps/cli/CHANGELOG.md:13-18]()`). ## Known Limitations Reflected in the Community Several behaviors surfaced by users are worth flagging at the overview level: - **Viewer is unauthenticated.** The worker HTTP viewer binds `127.0.0.1:` (default 37777) without authentication and serves decompressed memory; a local process or a CSRF / DNS-rebinding web page can read content. (Issue #51) - **No tool matcher on `PostToolUse`.** The Claude Code installer registers the hook without a matcher, so every tool's input and output is captured by default with no way to exclude sensitive MCP servers. (Issue #50) - **`redactSecrets` is currently a no-op.** Only `…` segments are stripped at the write boundary; secrets in tool output are stored verbatim. (Issue #49) - **`excludePatterns` is documented but not enforced.** Path globs listed under `privacy.excludePatterns` are not actually consulted when matching paths are captured. (Issue #48) - **Windows path handling.** Hook commands written with Windows-style backslashes are interpreted by the bash layer on Windows, collapsing into malformed paths like `C:Usershp...`. (Issue #43) - **Codex installer drift.** Hooks are not installed for Codex and the installer targets `~/.codex/config.json` instead of `~/.codex/config.toml`. (Issue #17) - **Node 26 / better-sqlite3.** Native bindings fail to load on Node.js 26.0.0 due to V8 14.6 breaking changes. (Issue #37) - **Cross-project session leakage.** `session-start` "Prior-session context" surfaces summaries from arbitrary recent sessions, not scoped to the current `cwd`. (Issue #39) These items do not block the core capture → store → retrieve workflow but should be understood before relying on cavemem in shared or multi-project environments. ## See Also - [CLI Reference](./cli.md) - [Compression Engine](./compression.md) - [MCP Server](./mcp-server.md) - [Settings & Configuration](./settings.md) - [Privacy & Redaction](./privacy.md) --- ## Cli ### Related Pages Related topics: [Overview](#page-overview), [Src](#page-apps-cli-src)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) - [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md) - [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) - [package.json](https://github.com/JuliusBrussee/cavemem/blob/main/package.json) - [biome.json](https://github.com/JuliusBrussee/cavemem/blob/main/biome.json) - [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) - [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json) - [apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md) - [apps/worker/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/worker/CHANGELOG.md) - [packages/compress/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/package.json)
# Cli ## Purpose and Scope The `cavemem` CLI is the user-facing binary that ships when users run `npm install -g cavemem`. It is the single entry point for installation, configuration, inspection, search, compression, re-indexing, export, and daemon control over the cavemem memory system. Source: [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) Conceptually the CLI is the **control plane** for the cavemem architecture; it does not own the memory store or the embedding worker. Those concerns live in sibling packages and apps: | Layer | Package / App | Role | |-------|---------------|------| | Domain models | `packages/core` | `MemoryStore` facade, `Embedder` interface | | Persistence | `packages/storage` | SQLite + FTS5 + vector adapter | | Compression | `packages/compress` | Caveman grammar engine | | Settings | `packages/config` | Zod schema, `settingsDocs()` | | Embedding providers | `packages/embedding` | Local / ollama / openai / none | | IDE hook handlers | `packages/hooks` | SessionStart/PostToolUse/etc. | | Local HTTP daemon | `apps/worker` | Read-only viewer + embedding backfill | | MCP server | `apps/mcp-server` | Stdio MCP transport | | User binary | `apps/cli` | The `cavemem` command | Source: [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) The CLI's own package layout is intentionally thin: it parses argv, dispatches to a subcommand, and delegates to one of the shared packages above. This keeps the binary easy to audit — the CLI is mostly a router. ## Package Layout and Build The CLI lives under `apps/cli/` as an ESM-only Node package. Source: [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json) Key facts from the package manifest: - `name`: `cavemem` — what users install globally. - `version`: `0.2.1` (matches the `apps/cli/CHANGELOG.md` minor-version track). - `type`: `module` (ESM; the monorepo is fully ESM — Biome enforces `useNodejsImportProtocol`). Source: [biome.json](https://github.com/JuliusBrussee/cavemem/blob/main/biome.json) - `bin.cavemem`: `./dist/index.js` — the single shim. - `engines.node`: `>=20.0.0`. - `files`: ships only `dist`, `hooks-scripts`, `README.md`, `LICENSE` — keeps the global install small. Build pipeline: - `build` runs `tsup` to produce `dist/index.js`. - `dev` runs `tsup --watch` and then re-invokes the freshly-built binary, so iterating on a command automatically re-runs against the new code. - `stage-publish` runs `scripts/prepack.mjs`, which is invoked before `npm publish` so the published tarball contains the pre-built artifact plus the `hooks-scripts/` directory consumed by IDE hook runners. Source: [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json) The CLI also embeds portable shell stubs that IDE hook runners invoke; those stubs shell out to the Node handlers in `packages/hooks`. This indirection is what makes the same hooks installable on Claude Code, Cursor, Gemini CLI, OpenCode, and Codex. Source: [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) ## Command Surface The README documents a flat, single-binary command set. Source: [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) | Command | Purpose | |---------|---------| | `cavemem install [--ide ]` | Install hook wiring into the chosen IDE | | `cavemem status` | Single-pane dashboard of settings, data dir, DB counts, installed IDEs, embedding backfill, worker pid/uptime | | `cavemem config show\|get\|set\|open\|path\|reset` | Self-documenting config UX backed by the Zod schema | | `cavemem start\|stop\|restart` | Control the worker daemon (usually unnecessary — auto-starts) | | `cavemem viewer` | Open the memory viewer in the default browser | | `cavemem doctor` | Verify installation end-to-end | | `cavemem search [--limit N] [--no-semantic]` | BM25 keyword search with optional cosine re-rank | | `cavemem compress ` | Compress a file with the caveman grammar | | `cavemem reindex` | Rebuild FTS5 + vector index | | `cavemem export ` | Dump observations to JSONL | | `cavemem mcp` | Start the MCP server on stdio | The v0.2.x release added `cavemem status`, the `config` subcommand, `list_sessions` (MCP), and `embedding.autoStart` / `embedding.idleShutdownMs` settings. It also reorganised the post-install message to explain that there is no daemon to start and to surface the embedding model + weight-download cost. Source: [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) ### Install command and IDE choices `cavemem install --ide ` is the on-ramp for new users. The accepted `--ide` values are `claude-code`, `gemini-cli`, `opencode`, `codex`, and `cursor`. Source: [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) The install step is also where two important user-facing invariants are established: 1. **No daemon on the write path.** Hooks write observations synchronously. The worker (if enabled) is detach-spawned in the background by `packages/hooks`; hooks never wait on it. CLAUDE.md documents this as a non-negotiable rule. Source: [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) 2. **Settings schema is self-documenting.** Every setting now has a `.describe()` string; the CLI surfaces that via `settingsDocs()` so there is no parallel docs file to drift. Source: [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) ### Compress command `cavemem compress ` runs the deterministic caveman-grammar compressor from `packages/compress` over a file on disk. The grammar lives in `packages/compress/src/lexicon.json`, is loaded through `lexicon.ts`, and consumed by `compress.ts` which exposes a pure `compress(text, { intensity })` function. Source: [packages/compress/src/lexicon.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.ts) This command exists primarily so users can sanity-check the compression quality and round-trip expandability without going through a full session. ### MCP subcommand `cavemem mcp` boots the stdio MCP server. In v0.1.3 this command was broken: the server module guarded `main()` behind an `isMainEntry()` check, and the CLI's `await import('@cavemem/mcp-server')` side-effect never reached `main()` because `import.meta.url` did not match `process.argv[1]`. The fix landed in v0.2.1 (changeset `c756051`) so the MCP server now boots correctly when invoked via the CLI. Source: [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) ## Development Workflow Four required gates must pass before merging into `apps/cli` or any sibling package: - `pnpm typecheck` - `pnpm lint` - `pnpm test` - `pnpm build` The four are also exposed at the monorepo root in `package.json`. Source: [package.json](https://github.com/JuliusBrussee/cavemem/blob/main/package.json) There is also an end-to-end publish test (`scripts/e2e-publish.sh`) that packs the artifact, installs it into an isolated prefix, and drives every hook event with realistic Claude Code payloads. Unit tests cover handlers, storage, and protocol contracts in isolation, but only the e2e publish test catches issues that only manifest in a globally-installed binary (bin-shim symlink resolution, etc.). Source: [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) For compression work specifically, contributors update `packages/compress/src/lexicon.json`, add a round-trip fixture under `packages/compress/test/fixtures/`, and re-run the benchmark in `evals/` — the README is updated if aggregate numbers shift. Source: [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md) ## Known Community Issues Touching the CLI The CLI surfaces several recurring friction points reported by users. These are not necessarily CLI bugs, but they all manifest through CLI commands, so they are worth knowing: - **`cavemem start` fails with `spawn EFTYPE` on Windows.** Hooks never auto-start the worker because the spawn error is raised before the worker process can be launched. `cavemem status` works; `cavemem start` (and `cmd /c cavemem start`, and `node dist/index.js start`) all reproduce. See [issue #11](https://github.com/JuliusBrussee/cavemem/issues/11). - **OpenCode desktop on Windows has no hook system**, so `cavemem install --ide opencode` on the desktop variant never captures data — `search`/`timeline` work but return nothing. See [issue #45](https://github.com/JuliusBrussee/cavemem/issues/45). - **Windows backslash paths break under bash.** The Claude Code installer writes `C:\Users\hp\...` into `~/.claude/settings.json`, but Claude Code's hook runner shells out through git-bash, which collapses the path. See [issue #43](https://github.com/JuliusBrussee/cavemem/issues/43). - **Codex installer writes to the wrong file.** `cavemem install --ide codex` writes `~/.codex/config.json`, but Codex expects `~/.codex/config.toml` and also requires `[features] codex_hooks = true`. See [issue #17](https://github.com/JuliusBrussee/cavemem/issues/17). - **Missing IDE choices.** Trae SOLO and Antigravity are not in the `--ide` enum (`claude-code | gemini-cli | opencode | codex | cursor`). See [issue #38](https://github.com/JuliusBrussee/cavemem/issues/38) and [issue #40](https://github.com/JuliusBrussee/cavemem/issues/40). - **`better-sqlite3` native binding failures** on newer Node.js / WSL — `cavemem status` reports the DB as `fail` with a V8 ABI mismatch. See [issue #5](https://github.com/JuliusBrussee/cavemem/issues/5), [issue #22](https://github.com/JuliusBrussee/cavemem/issues/22), and [issue #37](https://github.com/JuliusBrussee/cavemem/issues/37). The CLI also forwards several privacy concerns that are *captured* via CLI-installed hooks but *enforced* (or not) in shared packages: `privacy.redactSecrets` is currently a no-op (no secret/key/token scrubber), `privacy.excludePatterns` is documented but never read at the write boundary, and `PostToolUse` has no per-tool matcher so every tool call — including sensitive MCP servers — is captured by default. See [issue #48](https://github.com/JuliusBrussee/cavemem/issues/48), [issue #49](https://github.com/JuliusBrussee/cavemem/issues/49), and [issue #50](https://github.com/JuliusBrussee/cavemem/issues/50). ## See Also - [Mcp Server](mcp-server.md) — the stdio MCP server that the CLI's `cavemem mcp` subcommand launches. - [Worker](worker.md) — the local HTTP daemon that the CLI's `start`/`stop`/`restart`/`viewer` commands manage. - [Storage](storage.md) — the SQLite + FTS5 + vector adapter that `cavemem status` reports on. - [Settings](settings.md) — the Zod schema behind `cavemem config show|get|set`. - [Hooks](hooks.md) — the IDE hook handlers that the CLI's `cavemem install` subcommand wires up. --- ## Src ### Related Pages Related topics: [Cli](#page-apps-cli), [Commands](#page-apps-cli-src-commands)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) - [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) - [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md) - [package.json](https://github.com/JuliusBrussee/cavemem/blob/main/package.json) - [biome.json](https://github.com/JuliusBrussee/cavemem/blob/main/biome.json) - [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json) - [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) - [packages/compress/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/package.json) - [packages/compress/src/compress.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/compress.ts) - [packages/compress/src/lexicon.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.ts) - [packages/compress/src/count.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/count.ts) - [packages/compress/src/lexicon.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.json) - [packages/installers/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/CHANGELOG.md) - [apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md)
# Src The `src/` directories in this repository are the implementation surface of cavemem, a cross-agent persistent-memory system for coding assistants. This page maps the source layout so a new contributor can find the right file quickly. The project is a pnpm monorepo with two top-level source trees — `apps/` and `packages/` — and a small set of cross-cutting config files at the repository root. Source: [package.json](https://github.com/JuliusBrussee/cavemem/blob/main/package.json) ## Monorepo layout The root `package.json` defines the workspace and the build/test scripts that operate over every package and app. It is `private` and `name`-less at the top level (`cavemem-monorepo`), and it pins `packageManager` to `pnpm@9.12.0` with `engines.node >=20.0.0`. Build and test are fan-out commands: `pnpm -r --filter "./packages/*" --filter "./apps/*" build` and `pnpm -r test`. Lint and format delegate to Biome, configured by [`biome.json`](https://github.com/JuliusBrussee/cavemem/blob/main/biome.json) (two-space indent, single quotes, trailing commas, organized imports). Source: [package.json](https://github.com/JuliusBrussee/cavemem/blob/main/package.json), [biome.json](https://github.com/JuliusBrussee/cavemem/blob/main/biome.json) | Directory | Role | |---|---| | `apps/cli/` | The `cavemem` CLI binary — install hooks, search memory, start MCP, run the viewer. | | `apps/mcp-server/` | The standalone MCP stdio server (also launched via `cavemem mcp`). | | `packages/compress/` | `@cavemem/compress` — the caveman grammar compressor used on every write/read path. | | `packages/core/` | `@cavemem/core` — `MemoryStore`, the storage facade that enforces compression. | | `packages/config/` | `@cavemem/config` — Zod settings schema and the `settingsDocs()` export. | | `packages/embedding/` | `@cavemem/embedding` — local/remote vector embedders (lazy singleton). | | `packages/hooks/` | `@cavemem/hooks` — session-boundary hook runners (SessionStart, PostToolUse, …). | | `packages/installers/` | `@cavemem/installers` — per-IDE installers (Claude Code, Cursor, Gemini, OpenCode, Codex). | | `packages/worker/` | `@cavemem/worker` — the Hono HTTP worker that serves the viewer on `127.0.0.1:37777`. | The package list above is corroborated by the changelog set published from these workspaces (e.g. `@cavemem/config@0.2.0`, `@cavemem/embedding@0.2.0`, `@cavemem/mcp-server` updates). Source: [apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md), [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) ## The CLI source tree (`apps/cli/src`) `apps/cli/package.json` declares the binary name `cavemem` mapped to `dist/index.js` after build. The package type is `module`, and the `files` whitelist includes `dist`, `hooks-scripts`, `README.md`, and `LICENSE` so the published artifact carries only the runtime surface. The CLI's source is organized as one subcommand per file under `apps/cli/src/commands/` (e.g. `install.ts`, `config.ts`, `doctor.ts`, `search.ts`, `compress.ts`, `export.ts`, `hook.ts`, `mcp.ts`, `viewer.ts`), with a top-level `index.ts` performing command registration. Source: [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json) The non-negotiable "no daemon on the write path" invariant is enforced by how these files compose: hooks may detach-spawn the worker but must never wait on it, while observations always write synchronously through `MemoryStore`. The `cavemem install` command now prints a "what to try next" block and surfaces the embedding model plus weight-download cost, and the `runHook()` runtime accepts an injected `MemoryStore` so test code never touches the real `~/.cavemem` directory. Source: [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md), [packages/installers/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/installers/CHANGELOG.md) ## The compressor source tree (`packages/compress/src`) `packages/compress` is the lexical heart of the project — every persisted observation flows through it. Its `package.json` defines two entry points: the main `index` (TS build at `dist/index.js`) and the `./lexicon` subpath that exposes the JSON rule table directly. The `files` whitelist ships `dist` and `src/lexicon.json` so consumers can inspect the rule data. Build is `tsup` producing ESM with `.d.ts`; tests are Vitest; typecheck is `tsc --noEmit`. Source: [packages/compress/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/package.json) The source modules are intentionally narrow: - [`compress.ts`](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/compress.ts) — the compression pipeline: phrase removal (`removePhrases`), abbreviation substitution (`abbreviate`), and case-matching helpers (`matchCase`). Operates on `Segment` arrays produced by the tokenizer. - [`lexicon.ts`](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.ts) — typed accessors (`fillersFor`, `articlesFor`, `hedgesFor`, `pleasantriesFor`, `abbreviationsFor`, `expansions`) keyed by the `Intensity` type. The JSON file is imported with the import attribute `{ type: 'json' }`. - [`lexicon.json`](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/lexicon.json) — the data: fillers, articles, hedges, pleasantries, abbreviations, and expansion dictionaries for `lite`, `full`, and `ultra` intensity levels. The `expansions` map provides round-trip guarantees from abbreviations back to full forms. - [`count.ts`](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/count.ts) — a stable, cheap token estimator (max of whitespace-separated word count and `chars/4`) used to benchmark compressed-vs-expanded output. Per `CONTRIBUTING.md`, adding a compression rule means editing `lexicon.json`, adding a round-trip fixture under `packages/compress/test/fixtures/`, and re-running the eval benchmark — there is no parallel documentation to maintain. Source: [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md) ## Non-negotiable invariants that shape the source `CLAUDE.md` codifies four rules that every contributor must respect when writing into `src/`: 1. **All persisted prose must pass through `@cavemem/compress` before hitting storage.** New write paths must use `MemoryStore`, which enforces this. 2. **Never compress technical tokens.** Code blocks, inline code, URLs, file paths, shell commands, version numbers, dates, numeric literals, and quoted identifiers are preserved byte-for-byte. The tokenizer in `packages/compress/src/tokenize.ts` is the single authority. 3. **Round-trip tests must pass.** Any change to the compressor, lexicon, or tokenizer requires `pnpm --filter @cavemem/compress test` green, including the technical-token preservation suite. 4. **Progressive disclosure in MCP.** `search` and `timeline` return compact results; `get_observations` fetches full bodies. These rules directly explain why `compress.ts` operates on `Segment` arrays rather than raw strings, and why `lexicon.json` keeps the `expansions` map separate from the forward `abbreviations` tables. Source: [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md), [packages/compress/src/compress.ts](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/src/compress.ts) ## See Also - [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) — agent playbook and non-negotiable rules. - [CONTRIBUTING.md](https://github.com/JuliusBrussee/cavemem/blob/main/CONTRIBUTING.md) — how to add a compression rule, test fixtures, and the release flow. - [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) — user-facing overview, CLI command list, MCP tool list, and settings table. - [packages/compress/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/packages/compress/CHANGELOG.md) — compressor release history. - [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) — CLI release history. --- ## Commands ### Related Pages Related topics: [Src](#page-apps-cli-src)
Related Source Files The following source files were used to generate this page: - [apps/cli/src/commands/install.ts](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/src/commands/install.ts) - [apps/cli/src/commands/doctor.ts](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/src/commands/doctor.ts) - [apps/cli/src/commands/hook.ts](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/src/commands/hook.ts) - [apps/cli/src/commands/compress.ts](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/src/commands/compress.ts) - [apps/cli/src/commands/export.ts](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/src/commands/export.ts) - [apps/cli/src/commands/config.ts](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/src/commands/config.ts) - [README.md](https://github.com/JuliusBrussee/cavemem/blob/main/README.md) - [CLAUDE.md](https://github.com/JuliusBrussee/cavemem/blob/main/CLAUDE.md) - [apps/cli/package.json](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/package.json) - [apps/cli/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/cli/CHANGELOG.md) - [apps/mcp-server/CHANGELOG.md](https://github.com/JuliusBrussee/cavemem/blob/main/apps/mcp-server/CHANGELOG.md)
# Commands ## Overview The `cavemem` command-line interface is the user's primary entry point into the cavemem persistent-memory system. It is published as the `cavemem` binary from the `apps/cli` workspace, targets Node.js >=20, and is built as an ESM module via `tsup` ([apps/cli/package.json:18-22]()). Commands fall into four functional areas: installing and inspecting IDE wiring, controlling the optional background worker, querying and exporting stored observations, and ad-hoc compression utilities. The CLI is intentionally lightweight on the write path. IDE hook runners invoke the same in-process storage that the CLI uses, and the project's non-negotiable rule is that **hooks write synchronously and must never wait on a daemon** ([CLAUDE.md:11-15]()). Commands that need the worker (embedding backfill, viewer, MCP) detach-spawn it on first use; it self-exits when idle. ## Command Reference The full surface documented in the project README is summarized below. Each row maps a public command to the source file in `apps/cli/src/commands/` that implements it. | Command | Purpose | Source file | |---|---|---| | `cavemem install [--ide ]` | Register hooks and config with the chosen IDE (`claude-code`, `gemini-cli`, `opencode`, `codex`, `cursor`) | [install.ts]() | | `cavemem status` | Show settings path, data directory, DB path, and embedding backfill state | [doctor.ts]() | | `cavemem viewer` | Open the local read-only web UI at `http://127.0.0.1:37777` | (worker-driven) | | `cavemem doctor` | Verify installation health (settings, db, hooks) | [doctor.ts]() | | `cavemem search [--limit N] [--no-semantic]` | Hybrid BM25 + optional cosine re-rank over stored observations | (CLI dispatcher) | | `cavemem compress ` | Apply the caveman grammar to a file and print the result | [compress.ts]() | | `cavemem reindex` | Rebuild FTS5 keyword index and vector index | (CLI dispatcher) | | `cavemem export ` | Dump observations to JSONL | [export.ts]() | | `cavemem mcp` | Start the MCP stdio server (delegates to `@cavemem/mcp-server`) | (CLI dispatcher) | | `cavemem start\|stop\|restart` | Control the worker daemon (auto-spawns in normal use) | (worker control) | | `cavemem config ` | Read and write `~/.cavemem/settings.json` | [config.ts]() | | `cavemem hook ` | Internal entry point invoked by IDE hook runners | [hook.ts]() | Source: [README.md:54-66](), [apps/cli/package.json:18-22](). ## Lifecycle: Install, Worker, and Hooks `cavemem install` is the on-ramp command. It edits the IDE-specific configuration file to register cavemem's hook scripts for the lifecycle events the IDE exposes (typically `SessionStart`, `PostToolUse`, `SessionEnd`). The v0.2.x release updated the installer to print a multi-line "what to try next" block that explains there is no daemon to start and surfaces the embedding model + weight-download cost ([apps/cli/CHANGELOG.md:5-18]()). The Claude Code path was hardened end-to-end in the same release so the memory system actually works after `npm install -g cavemem` ([apps/cli/CHANGELOG.md:25-32]()). Three known installer rough edges surface repeatedly in the community: - On Windows, hook commands are written with backslashes (e.g. `C:\Users\hp\...`), and Claude Code's hook runner shells out through `bash` (git-bash), which collapses the path to `C:Usershp...` and breaks the hook ([Issue #43]()). - The Codex installer historically wrote `~/.codex/config.json`, but codex reads `~/.codex/config.toml`, and hooks were not registered at all ([Issue #17]()). - `opencode` has no hooks system — only MCP — so installing against it captures nothing into the DB ([Issue #45]()). `cavemem start`, `stop`, and `restart` control the worker explicitly. In normal use, the first hook invocation detach-spawns the worker; the system never blocks on it. Idle shutdown is governed by `embedding.idleShutdownMs` in settings ([CLAUDE.md:11-15]()). The internal `cavemem hook ` subcommand is the entry point that hook runners shell out to — the on-disk scripts that the installer drops into `~/.claude/` (or the equivalent per-IDE config) are thin wrappers around it ([hook.ts]()). ## Read-Side: Search, Reindex, Export, Viewer, MCP The query-side commands share the same backing store (SQLite + FTS5) and reach it through the same in-process API that hooks use. `cavemem search` runs a hybrid query: BM25 over the FTS5 index, optionally re-ranked with the local embedding model. Pass `--no-semantic` to skip the embedding leg. The MCP `search` tool returns the same shape — `[{id, score, snippet, session_id, ts}]` ([README.md:71-78]()). `cavemem reindex` rebuilds both the FTS5 keyword index and the vector index. Run it after changing embedding models or after a bulk `export` / re-import flow. `cavemem export ` streams stored observations to JSONL, which pairs naturally with the new MCP `list_sessions` tool (`[{id, ide, cwd, started_at, ended_at}]`) for archival ([README.md:71-78](), [apps/cli/CHANGELOG.md:18-24]()). `cavemem viewer` opens the read-only HTTP UI on `127.0.0.1:37777`. **The viewer is unauthenticated** and several routes serve decompressed memory content, so a local process or a CSRF / DNS-rebinding attack from a malicious page can read the full corpus ([Issue #51]()). `cavemem mcp` starts the MCP stdio server; it had a real failure mode in v0.1.x where the dynamic import's `import.meta.url` did not match `process.argv[1]`, so the `isMainEntry()` guard short-circuited and the process exited with code 0. This was fixed in v0.2.1: "fix(mcp): boot stdio server when invoked via `cavemem mcp`" ([Issue #3](), [apps/mcp-server/CHANGELOG.md:33-39]()). `cavemem compress` is a development utility that applies the caveman grammar from `@cavemem/compress` to an arbitrary file and prints the result. It exercises the same compressor the write path uses, making it the right tool for tuning the lexicon or benchmarking the ~75% prose-token reduction the project claims ([README.md:30-46](), [packages/compress/src/compress.ts:1-12]()). ## Common Failure Modes A short list of failure modes the community has hit, useful when triaging `cavemem` output: - **`cavemem start` → `spawn EFTYPE` on Windows.** A shim / shebang issue; reproducible with `node dist/index.js start` ([Issue #11]()). - **`cavemem status` shows `db: … fail` "compiled against a different Node".** Native `better-sqlite3` mismatch, common under WSL or after a Node-version change ([Issue #5](), [Issue #22]()). - **`better-sqlite3` fails to load on Node 26.0.0 / V8 14.6.** Native binding incompatibility ([Issue #37]()). - **`cavemem mcp` exits silently with code 0.** `isMainEntry()` returns false on dynamic import; fixed in v0.2.1 ([Issue #3]()). - **Captured tool I/O contains secrets.** `privacy.redactSecrets` is documented as a control but is never read; only `…` is actually stripped ([Issue #49]()). - **`privacy.excludePatterns` is ignored.** The setting is read by no code path; matching paths are still captured ([Issue #48]()). The `doctor` command exists specifically to surface the first three categories in a single run; `cavemem status` prints the same shape. The privacy items (#48, #49) are configuration-asserted guarantees that the current code does not enforce, so they show up as semantic surprises rather than command errors. ## See Also - **Configuration** — settings schema, defaults, and the `config` subcommand in detail. - **MCP Server** — tool surface, hand-shake, and the v0.2.1 stdio boot fix. - **Architecture** — write-path invariants, hook → store → MCP data flow, and the worker process model. - **Privacy and Redaction** — what is and is not stripped at the write boundary, including the open issues above. --- --- ## Pitfall Log Project: JuliusBrussee/cavemem Summary: Found 35 structured pitfall item(s), including 8 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification. ## 1. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/17 ## 2. Installation risk - Installation risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/11 ## 3. Configuration risk - Configuration risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/39 ## 4. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default - User impact: Developers may expose sensitive permissions or credentials: No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/50 ## 5. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: Windows: hook commands written with backslashes break under bash -c (path collapse to `C:Usershp...`) - User impact: Developers may expose sensitive permissions or credentials: Windows: hook commands written with backslashes break under bash -c (path collapse to `C:Usershp...`) - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/43 ## 6. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory - User impact: Developers may expose sensitive permissions or credentials: Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/51 ## 7. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: privacy.excludePatterns is documented as enforced but is never read (matching paths still captured) - User impact: Developers may expose sensitive permissions or credentials: privacy.excludePatterns is documented as enforced but is never read (matching paths still captured) - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/48 ## 8. Security or permission risk - Security or permission risk requires verification - Severity: high - Evidence strength: source_linked - Finding: Developers should check this security_permissions risk before relying on the project: redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber) - User impact: Developers may expose sensitive permissions or credentials: redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber) - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/49 ## 9. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: Add Antigravity IDE support - User impact: Developers may fail before the first successful local run: Add Antigravity IDE support - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/38 ## 10. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: Add Trae SOLO IDE support - User impact: Developers may fail before the first successful local run: Add Trae SOLO IDE support - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/40 ## 11. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: Codex installer is out of date - User impact: Developers may fail before the first successful local run: Codex installer is out of date - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/17 ## 12. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: cavemem start fails with spawn EFTYPE on Windows - User impact: Developers may fail before the first successful local run: cavemem start fails with spawn EFTYPE on Windows - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/11 ## 13. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: cavemem v0.1.0 - User impact: Upgrade or migration may change expected behavior: cavemem v0.1.0 - Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/cavemem/releases/tag/v0.1.0 ## 14. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: cavemem v0.1.1 - User impact: Upgrade or migration may change expected behavior: cavemem v0.1.1 - Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/cavemem/releases/tag/v0.1.1 ## 15. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.1.3 - User impact: Upgrade or migration may change expected behavior: v0.1.3 - Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/cavemem/releases/tag/v0.1.3 ## 16. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this installation risk before relying on the project: v0.2.1 - User impact: Upgrade or migration may change expected behavior: v0.2.1 - Evidence: failure_mode_cluster:github_release | https://github.com/JuliusBrussee/cavemem/releases/tag/v0.2.1 ## 17. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/38 ## 18. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/40 ## 19. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/50 ## 20. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/43 ## 21. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/37 ## 22. Installation risk - Installation risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/48 ## 23. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.host_targets | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem ## 24. Configuration risk - Configuration risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/45 ## 25. Capability evidence risk - Capability evidence risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: README/documentation is current enough for a first validation pass. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: capability.assumptions | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem ## 26. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Developers should check this migration risk before relying on the project: bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback? - User impact: Developers may hit a documented source-backed failure mode: bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use bun:sqlite as fallback? - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/37 ## 27. Maintenance risk - Maintenance risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem ## 28. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: downstream_validation.risk_items | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem ## 29. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: no_demo - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: risks.scoring_risks | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem ## 30. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/51 ## 31. Security or permission risk - Security or permission risk requires verification - Severity: medium - Evidence strength: source_linked - Finding: Project evidence flags a security or permission risk. Review the linked source before relying on this workflow. - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/49 ## 32. Capability evidence risk - Capability evidence risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this capability risk before relying on the project: session-start: prior-session context not scoped to cwd, leaks across unrelated projects - User impact: Developers may hit a documented source-backed failure mode: session-start: prior-session context not scoped to cwd, leaks across unrelated projects - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/39 ## 33. Runtime risk - Runtime risk requires verification - Severity: low - Evidence strength: source_linked - Finding: Developers should check this performance risk before relying on the project: Cavemen with Opecode Desktop App on windows not working - User impact: Developers may hit a documented source-backed failure mode: Cavemen with Opecode Desktop App on windows not working - Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/45 ## 34. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: issue_or_pr_quality=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem ## 35. Maintenance risk - Maintenance risk requires verification - Severity: low - Evidence strength: source_linked - Finding: release_recency=unknown。 - User impact: May increase setup, validation, or first-run risk for the user. - Evidence: evidence.maintainer_signals | github_repo:1213956965 | https://github.com/JuliusBrussee/cavemem