Related Pages

Related topics: Cli

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).

The package manager is pinned ("packageManager": "[email protected]", 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).

flowchart LR
  IDE["IDE hook event<br/>(SessionStart / PostToolUse / SessionEnd)"] --> HOOK["Hook script<br/>apps/cli/hooks-scripts"]
  HOOK --> REDACT["redact &lt;private&gt;...&lt;/private&gt;"]
  REDACT --> COMP["@cavemem/compress<br/>compress.ts"]
  COMP --> STORE["MemoryStore<br/>SQLite + FTS5"]
  STORE --> EMBED["Worker (detached)<br/>vector index"]
  STORE --> MCP["MCP server<br/>search · timeline · get_observations"]
  MCP --> AGENT["Agent query"]
  STORE --> VIEW["Web viewer<br/>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:<workerPort> (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 <private>…</private> 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
• Compression Engine
• MCP Server
• Settings & Configuration
• Privacy & Redaction

Related Pages

Related topics: Overview, Src

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

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:

Source: 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

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
• 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

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

Command Surface

The README documents a flat, single-binary command set. Source: README.md

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

Install command and IDE choices

cavemem install --ide <name> is the on-ramp for new users. The accepted --ide values are claude-code, gemini-cli, opencode, codex, and cursor. Source: 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
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

Compress command

cavemem compress <file> 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

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

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

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

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

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.
• 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.
• 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.
• 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.
• Missing IDE choices. Trae SOLO and Antigravity are not in the --ide enum (claude-code | gemini-cli | opencode | codex | cursor). See issue #38 and issue #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, issue #22, and issue #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, issue #49, and issue #50.

See Also

• Mcp Server — the stdio MCP server that the CLI's cavemem mcp subcommand launches.
• Worker — the local HTTP daemon that the CLI's start/stop/restart/viewer commands manage.
• Storage — the SQLite + FTS5 + vector adapter that cavemem status reports on.
• Settings — the Zod schema behind cavemem config show|get|set.
• Hooks — the IDE hook handlers that the CLI's cavemem install subcommand wires up.

Related Pages

Related topics: Cli, Commands

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

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 [email protected] 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 (two-space indent, single quotes, trailing commas, organized imports). Source: package.json, biome.json

The package list above is corroborated by the changelog set published from these workspaces (e.g. @cavemem/[email protected], @cavemem/[email protected], @cavemem/mcp-server updates). Source: apps/mcp-server/CHANGELOG.md, 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

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, 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

The source modules are intentionally narrow:

• 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 — 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 — 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 — 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

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, packages/compress/src/compress.ts

See Also

• CLAUDE.md — agent playbook and non-negotiable rules.
• CONTRIBUTING.md — how to add a compression rule, test fixtures, and the release flow.
• README.md — user-facing overview, CLI command list, MCP tool list, and settings table.
• packages/compress/CHANGELOG.md — compressor release history.
• apps/cli/CHANGELOG.md — CLI release history.

Related Pages

Related topics: Src

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.

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 <event> 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 <out.jsonl> 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 <private>…</private> 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.

Doramagic Pitfall Log

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
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/17

2. Installation risk: Installation risk requires verification

• Severity: high
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/11

3. Configuration risk: Configuration risk requires verification

• Severity: high
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/JuliusBrussee/cavemem/issues/39

4. Security or permission risk: Security or permission risk requires verification

• Severity: high
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured by default. Context: Observed during installation or first-run setup.
• 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
• 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...)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Windows: hook commands written with backslashes break under bash -c (path collapse to C:Usershp...). Context: Observed when using node, windows
• 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
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves decompressed memory. Context: Observed during installation or first-run setup.
• 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
• 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)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: privacy.excludePatterns is documented as enforced but is never read (matching paths still captured). Context: Source discussion did not expose a precise runtime context.
• 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
• 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)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: redactSecrets is a no-op: secrets in tool output are stored verbatim (no output-side scrubber). Context: Source discussion did not expose a precise runtime context.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/49

9. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Add Antigravity IDE support. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/38

10. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Add Trae SOLO IDE support. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/40

11. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Codex installer is out of date. Context: Observed when using node
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/17

12. Installation risk: Installation risk requires verification

• Severity: medium
• 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
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: cavemem start fails with spawn EFTYPE on Windows. Context: Observed when using node, windows, macos, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/JuliusBrussee/cavemem/issues/11

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using cavemem with real data or production workflows.

• Worker HTTP viewer on 127.0.0.1:37777 is unauthenticated and serves deco - github / github_issue
• No per-tool capture allowlist/matcher: sensitive MCP tool I/O captured b - github / github_issue
• redactSecrets is a no-op: secrets in tool output are stored verbatim (no - github / github_issue
• privacy.excludePatterns is documented as enforced but is never read (mat - github / github_issue
• cavemem start fails with spawn EFTYPE on Windows - github / github_issue
• Cavemen with Opecode Desktop App on windows not working - github / github_issue
• Windows: hook commands written with backslashes break under bash -c (pat - github / github_issue
• Codex installer is out of date - github / github_issue
• Add Trae SOLO IDE support - github / github_issue
• session-start: prior-session context not scoped to cwd, leaks across unr - github / github_issue
• Add Antigravity IDE support - github / github_issue
• bug: better-sqlite3 native bindings fail on Node.js 26.0.0 (v147) - use - github / github_issue