Related Pages

Related topics: System Architecture & Data Flow, Capture Pipeline, Privacy Scrubbing & LLM Drafter

Project Overview & Getting Started

Purpose and Scope

remembug-cli is a command-line interface tool designed to help developers capture, organize, and retrieve coding-related "remembered bugs" — recurring mistakes, edge cases, and lessons learned — directly from the terminal. The project aims to build a persistent, searchable, and shareable personal knowledge base for debugging insights, integrated with local development workflows.

The repository is structured as a pnpm monorepo, containing multiple packages under the packages/ directory. The primary deliverable is the CLI tool located in packages/cli, which exposes commands such as init and config for bootstrapping and managing the tool's local state. Source: pnpm-workspace.yaml:1-10.

The README positions the project as a developer-focused utility, emphasizing minimal configuration, local-first storage, and seamless shell integration. Source: README.md:1-40.

Repository Structure

The project follows a workspace-based layout, enabling shared dependencies and code reuse across packages.

Source: package.json:1-30, pnpm-workspace.yaml:1-10.

Getting Started

Prerequisites

• Node.js: A recent LTS version (18+ recommended).
• pnpm: Used as the package manager for installing workspace dependencies.
• A terminal environment (Bash, Zsh, or PowerShell).

Source: README.md:20-35, docs/quickstart.md:1-15.

Installation

Clone the repository and install dependencies at the workspace root:

git clone https://github.com/zaitanabil/remembug-cli.git
cd remembug-cli
pnpm install

The root package.json defines the install, build, and dev scripts used across the workspace. Source: package.json:5-25.

First Run — `remembug init`

The init command prepares a local configuration directory and writes a default configuration file. It is typically the first command a user runs after installation.

pnpm --filter cli run build
node packages/cli/dist/index.js init

The implementation in init.ts performs directory creation, writes an initial JSON config, and prints a confirmation message indicating the storage path. Source: packages/cli/src/commands/init.ts:1-40.

Managing Configuration — `remembug config`

The config command allows users to read and update configuration values such as the storage path, default namespaces, and editor preferences.

remembug config get storage.path
remembug config set storage.path ~/.remembug

The command resolves subcommands (get, set, list) and persists changes to the local config file. Source: packages/cli/src/commands/config.ts:1-50.

Command Workflow

The following diagram summarizes the typical first-time user flow from cloning to capturing an entry.

flowchart TD
    A[Clone repository] --> B[pnpm install]
    B --> C[pnpm build]
    C --> D[remembug init]
    D --> E[remembug config set]
    E --> F[Ready to use]

Source: README.md:30-50, docs/quickstart.md:20-40.

Key Takeaways

• The project is a pnpm monorepo with the CLI packaged under packages/cli. Source: pnpm-workspace.yaml:1-10.
• Onboarding is driven by two primary commands: init for bootstrapping storage and config for adjusting settings. Source: packages/cli/src/commands/init.ts:1-40, packages/cli/src/commands/config.ts:1-50.
• The quickstart guide in docs/quickstart.md walks new users from installation through first configuration. Source: docs/quickstart.md:1-40.
• The root package.json coordinates build and development scripts across the workspace. Source: package.json:1-30.
• The README provides the high-level project pitch, feature list, and example invocations. Source: README.md:1-50.

After completing these steps, the CLI is ready to record, retrieve, and manage debugging insights from the terminal.

Related Pages

Related topics: Project Overview & Getting Started, Capture Pipeline, Privacy Scrubbing & LLM Drafter, Storage, Search, MCP & Review UI

System Architecture & Data Flow

Purpose and Scope

remembug-cli is structured as a client–daemon system designed to record, persist, and later surface contextual bug memories to an AI assistant (Claude Code) during development workflows. The CLI command is the user-facing entry point, while a long-lived background daemon owns all persistence, configuration, and integration logic. Splitting responsibilities this way keeps the CLI invocation fast and lets the daemon retain state across commands.

The architectural intent documented in docs/architecture.md is to separate four concerns: command parsing (CLI), transport (HTTP), state (config + storage), and integration (Claude Code bridge). The daemon binary is the only process allowed to mutate persistent state; the CLI acts purely as a thin RPC client.

Process Topology

The runtime consists of two cooperating processes started from the same monorepo package set.

The daemon entry script bootstraps configuration loading, initializes the logger, mounts the HTTP server, and registers signal handlers for graceful shutdown. packages/daemon/src/index.ts is the composition root that wires these modules together. The CLI is expected to either spawn the daemon on first use or attach to an already-running instance via a well-known local port.

flowchart LR
  User[Developer] --> CLI[remembug CLI]
  CLI -- HTTP/JSON --> Daemon[remembugd daemon]
  Daemon --> Store[(Local Store<br/>config + memory)]
  Daemon --> CC[Claude Code Integration]
  CC -. injects context .-> Editor[IDE / Agent Session]

HTTP Transport and Request Lifecycle

The daemon exposes a small JSON-over-HTTP surface defined in packages/daemon/src/http.ts. Each route maps directly to a user-facing subcommand (for example, "remember", "recall", "list", "forget"), so the wire protocol mirrors the CLI 1:1. This is deliberate: keeping request and response shapes aligned with command semantics makes the daemon easy to drive from scripts or future UIs.

The request lifecycle in packages/daemon/src/http.ts follows a uniform pipeline:

1. Parse the JSON body and extract the command verb plus arguments.
2. Validate inputs against the registered schema for that verb.
3. Dispatch to the handler, which reads or writes through the config module.
4. Serialize the result as JSON and return it with an appropriate status code.

Errors raised inside handlers are caught at the transport boundary and translated into structured error envelopes, so the CLI never needs to parse free-form log lines. The logger module (packages/daemon/src/logger.ts) writes a parallel human-readable trace to a log file for post-mortem inspection.

Configuration, Persistence, and Logging

All durable state is funneled through packages/daemon/src/config.ts. This module owns the on-disk location of the memory store, the daemon port, the upstream integration credentials, and per-project overrides. Centralizing configuration means the CLI never reads or writes the store directly, which prevents partial writes and lock contention.

The logger (packages/daemon/src/logger.ts) is initialized once at daemon startup and injected wherever structured logging is needed. It writes to a rotating file under the user's config directory and also streams to stderr when the daemon runs in the foreground. Log levels and output destinations are themselves controlled by values resolved from config.ts, keeping the two modules symmetric.

Key invariants enforced by these modules:

• Only one daemon process may hold the store lock at a time; the CLI must connect rather than write.
• Config changes are atomic: the module writes to a temp file and renames, so a crashed write cannot corrupt state.
• Log entries include a request correlation id propagated from the HTTP layer, making traces reconstructable.

Integration With Claude Code

The bridge to the AI assistant is described in docs/claude-code-integration.md and implemented as an adapter inside the daemon. When the CLI requests a recall, the daemon formats the stored bug memory into the shape Claude Code expects (typically a system-prompt injection or a context-file append) and forwards it through the integration adapter.

Data flow for a typical recall session:

1. Developer runs remembug recall <id> in a shell that already has Claude Code loaded.
2. CLI sends the request to the daemon over HTTP.
3. Daemon loads the memory record from the store via config.ts.
4. Daemon hands the formatted payload to the Claude Code integration adapter.
5. The adapter injects the context into the active Claude Code session and returns a confirmation to the daemon.
6. Daemon responds to the CLI, which prints a short success message.

This round trip keeps the CLI agnostic of the upstream API and lets the daemon change integration strategies (Claude Code today, other agents later) without touching the client.

Summary

The architecture favors a thin CLI over a stateful daemon so that bug memory is durable, addressable, and injectable into AI-assisted workflows. The composition root (packages/daemon/src/index.ts) ties together transport (packages/daemon/src/http.ts), state (packages/daemon/src/config.ts), observability (packages/daemon/src/logger.ts), and external integration (documented in docs/claude-code-integration.md), while docs/architecture.md records the rationale and constraints that hold the system together.

Related Pages

Related topics: System Architecture & Data Flow, Storage, Search, MCP & Review UI

Capture Pipeline, Privacy Scrubbing & LLM Drafter

The Capture Pipeline is the core subsystem of remembug-cli's daemon that turns raw agent activity — tool invocations, command outputs, stack traces, and natural-language exchanges — into sanitized, structured bug reports. It runs entirely inside the local daemon (packages/daemon), so user code and secrets never leave the host before being filtered through the privacy scrubber. The pipeline is composed of three cooperating stages: event capture (triggered by Claude Code hooks), raw-signal detection (span and stack), and redaction, after which an LLM Drafter produces the final human-readable summary.

Architecture Overview

The pipeline is event-driven. Two Claude Code hook entry points feed the capture stage: a post-tool-use hook that fires after every tool invocation and a stop hook that fires when the agent session ends. Both hooks normalize their payloads into a common CaptureEvent shape and dispatch it to the capture utilities. The capture/ folder holds the detection logic that turns free-form text into structured Span and StackFrame records, and the scrubber/ module is applied as a mandatory gate before anything is persisted or sent to an external model.

flowchart LR
    A[Claude Code Agent] -->|tool finishes| B[post-tool-use hook]
    A -->|session stops| C[stop hook]
    B --> D[CaptureEvent]
    C --> D
    D --> E[span-detector]
    D --> F[stack-detect]
    E --> G[Scrubber]
    F --> G
    G --> H[LLM Drafter]
    H --> I[Sanitized Bug Report]

Source: packages/daemon/src/hooks/post-tool-use.ts:1-80

Source: packages/daemon/src/hooks/stop.ts:1-60

Capture Stage: Hooks and Signal Detection

The post-tool-use hook is the workhorse of the pipeline. It runs synchronously after every tool call made by the agent, receives the tool name, input arguments, and resulting output, and decides whether the output contains a recoverable defect signal. Outputs that match the configured heuristics are forwarded to the detector layer; everything else is discarded early to minimize overhead.

Source: packages/daemon/src/hooks/post-tool-use.ts:20-90

The stop hook complements the post-tool-use hook by performing a final sweep at the end of the session. It scans the accumulated transcript for retrospective signals — for example, a final assistant message apologizing for a failed action — and emits a closing CaptureEvent if any are found. Together, the two hooks guarantee that both transient errors and end-of-session reflections are captured.

Source: packages/daemon/src/hooks/stop.ts:10-50

Detection of code spans is delegated to capture/span-detector.ts. It scans tool output for inline file-and-line references (e.g. path/to/file.ts:42) and locates the corresponding source in the local working tree so the span can be enriched with a short code excerpt. This produces a Span object containing the file path, line range, and a bounded snippet suitable for downstream LLM prompting.

Source: packages/daemon/src/capture/span-detector.ts:1-70

Stack-trace detection is handled by capture/stack-detect.ts. It applies language-aware regular expressions to recognize frames from Node.js, Python, Go, and Rust error formats, normalizes each frame into a StackFrame (file, line, function, source), and deduplicates consecutive identical frames. The deduplication step is important because long crash dumps often contain thousands of repeated frames from libraries and would otherwise dominate the prompt.

Source: packages/daemon/src/capture/stack-detect.ts:1-80

Privacy Scrubbing

Before any captured event leaves the daemon, it must pass through the scrubber. The scrubber is defined as the single public surface in scrubber/index.ts and is composed of multiple ordered redaction passes. The implementation enforces a deny-by-default posture: anything not explicitly whitelisted is either replaced with a stable token or removed.

The redaction passes typically include:

• Secret patterns — API keys, bearer tokens, JWTs, AWS access keys, and Authorization header values are matched against compiled regexes and replaced with <REDACTED:secret> placeholders.
• PII patterns — email addresses, IPv4/IPv6 literals, and phone-like digit sequences are masked.
• Path normalization — absolute filesystem paths are rewritten to repo-relative paths so the host's directory layout is not leaked.
• Stack-frame file paths — file paths inside StackFrame records are scrubbed using the same path rule to keep redacted traces consistent.

Source: packages/daemon/src/scrubber/index.ts:1-120

The privacy contract is documented for end users in docs/privacy.md, which states that raw tool output is never persisted before scrubbing and that the LLM Drafter only ever sees the post-scrub payload. Operators can extend the redaction set by adding patterns to the scrubber configuration without touching the capture or drafting stages.

Source: docs/privacy.md:1-40

LLM Drafter

The final stage consumes the sanitized CaptureEvent, the enriched Spans, and the normalized StackFrames, and assembles a structured prompt for an LLM. The drafter's job is strictly summarization: it produces a title, a one-paragraph description, reproduction steps, observed vs. expected behavior, and a list of referenced code locations. Because the input has already been scrubbed, the drafter never has the opportunity to echo secrets back to the user, even if the upstream model is misbehaving.

The drafter output is the canonical bug-report payload that gets stored in the local bug database and, optionally, posted to a configured issue tracker. By separating capture, scrubbing, and drafting, the system keeps each concern testable in isolation: detectors can be unit-tested with raw tool output, the scrubber with adversarial secrets, and the drafter with synthetic sanitized events.

Source: packages/daemon/src/scrubber/index.ts:80-140

Source: packages/daemon/src/capture/span-detector.ts:40-70

Operational Notes

The capture pipeline is intentionally conservative. Hooks return early when the agent is not in a capturing session, the scrubber short-circuits on empty input, and the LLM Drafter is only invoked when at least one span or stack frame has been detected. This keeps the runtime overhead negligible for ordinary agent activity while still capturing high-signal failure moments.

Source: packages/daemon/src/hooks/post-tool-use.ts:1-20

Source: packages/daemon/src/hooks/stop.ts:1-10

Source: packages/daemon/src/capture/span-detector.ts:1-40

Source: packages/daemon/src/capture/stack-detect.ts:1-40

Source: packages/daemon/src/scrubber/index.ts:1-80

Source: docs/privacy.md:1-40

Related Pages

Related topics: System Architecture & Data Flow, Capture Pipeline, Privacy Scrubbing & LLM Drafter

Storage, Search, MCP & Review UI

The remembug-cli daemon is organized around four tightly-coupled subsystems that together provide persistence, semantic retrieval, model-tool bridging, and human-facing review. This page documents the implementation surface for Storage, Search (Embeddings), MCP (Model Context Protocol) Server, and the Review UI flow, focusing on the modules under packages/daemon/src/.

1. System Role & Boundaries

The daemon acts as the long-lived background service for the CLI. It owns durable memory of bug observations, exposes search across them through semantic vectors, and bridges them into LLM clients via the Model Context Protocol.

Source: packages/daemon/src/store/index.ts:1-40, packages/daemon/src/embeddings/index.ts:1-30, packages/daemon/src/mcp/server.ts:1-50.

2. Storage Layer

2.1 Entry Point

store/index.ts is the facade for all persistence operations. It re-exports the typed schema, opens the underlying connection lazily, and offers high-level CRUD helpers (e.g., createBug, listBugs, updateBug, getBugById) so callers do not touch raw SQL or the underlying driver directly. Insert and query methods normalize timestamps and ensure required fields are populated before write.

Source: packages/daemon/src/store/index.ts:1-120.

2.2 Schema Definition

store/schema.ts defines the canonical entity shapes used across the daemon. The schema is intentionally small and stable, and is consumed both by the store facade and by MCP tool input validators, guaranteeing that what an LLM sends through MCP matches what is written to disk.

Typical schema fields (per the repository's Bug shape) include:

• id — locally generated primary key
• title, description — human-readable text used as the embedding source
• status — lifecycle state used by Review UI (e.g., open, confirmed, resolved)
• createdAt, updatedAt — ISO timestamps set by store/index.ts

Source: packages/daemon/src/store/schema.ts:1-80.

2.3 Storage Workflow

flowchart LR
  A[CLI / MCP caller] -->|createBug / searchBugs| B(store/index.ts)
  B -->|read/write| C[(schema-defined rows)]
  B -->|embed text| D(embeddings/local.ts)
  D -->|return vector| B
  B -->|result| A

Source: packages/daemon/src/store/index.ts:40-120, packages/daemon/src/embeddings/local.ts:1-40.

3. Embeddings & Semantic Search

The embeddings subsystem is structured around a provider abstraction so the daemon can switch between local and remote backends without changing call sites.

3.1 Provider Interface

embeddings/types.ts declares the provider contract — at minimum an asynchronous embed(text: string | string[]): Promise<number[][]> method returning fixed-dimension vectors, plus metadata such as modelId and dimensions. The store facade depends only on this interface, never on a concrete provider.

Source: packages/daemon/src/embeddings/types.ts:1-40.

3.2 Local Provider

embeddings/local.ts implements the default provider so the daemon runs offline. It loads the bundled model lazily on first use, caches it in-process, and exposes the same embed signature required by the interface. Callers benefit from deterministic, network-free retrieval which is important for the Review UI's responsiveness.

Source: packages/daemon/src/embeddings/local.ts:1-80.

3.3 Wiring

embeddings/index.ts selects and exports the active provider based on configuration or environment, defaulting to the local implementation. The store then composes this provider to index text on write and to vectorize queries on read.

Source: packages/daemon/src/embeddings/index.ts:1-60.

4. MCP Server & Review UI Integration

4.1 Server Topology

mcp/server.ts registers the daemon's persistence and search functionality as MCP tools (e.g., create_bug, search_bugs, get_bug) and, where applicable, as MCP resources. Each tool's input schema mirrors store/schema.ts, which means LLM-generated payloads are validated against the same types the storage layer expects.

Source: packages/daemon/src/mcp/server.ts:1-120.

4.2 End-to-End Flow

1. An LLM client invokes an MCP tool such as search_bugs(query="login crash").
2. mcp/server.ts validates the payload, then calls the store facade.
3. The store embeds the query via embeddings/index.ts (typically routing to local.ts) and runs a similarity query.
4. Results, including status fields used by Review UI, are returned through the MCP response and surfaced in the human-facing Review UI for triage.

Source: packages/daemon/src/mcp/server.ts:50-150, packages/daemon/src/store/index.ts:80-140, packages/daemon/src/embeddings/index.ts:20-60.

4.3 Review UI Contract

Although the Review UI lives outside the daemon source tree, its contract is defined implicitly by the union of the MCP tool surface in mcp/server.ts and the status enum in store/schema.ts. Any UI state (open/confirmed/resolved) is read through MCP, never by directly querying storage, which preserves single-source-of-truth semantics for memory.

Source: packages/daemon/src/mcp/server.ts:100-200, packages/daemon/src/store/schema.ts:1-80.

5. Key Takeaways

• store/ is the single owner of persistence; MCP and embeddings only reach data through its facade.
• embeddings/ is provider-pluggable thanks to types.ts, with local.ts as the offline-first default.
• mcp/server.ts is the integration seam: every Review UI action maps to an MCP tool whose schema is enforced by store/schema.ts.
• Status fields flow from store/schema.ts → mcp/server.ts → Review UI, giving humans a consistent lifecycle view over LLM-mediated writes.

Source: packages/daemon/src/store/schema.ts:1-80, packages/daemon/src/store/index.ts:1-120, packages/daemon/src/embeddings/types.ts:1-40, packages/daemon/src/embeddings/local.ts:1-80, packages/daemon/src/embeddings/index.ts:1-60, packages/daemon/src/mcp/server.ts:1-200.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• 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: capability.host_targets | https://github.com/zaitanabil/remembug-cli

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• 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: capability.assumptions | https://github.com/zaitanabil/remembug-cli

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• 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.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://github.com/zaitanabil/remembug-cli

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

• Severity: medium
• Finding: no_demo
• 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: downstream_validation.risk_items | https://github.com/zaitanabil/remembug-cli

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

• Severity: medium
• Finding: no_demo
• 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: risks.scoring_risks | https://github.com/zaitanabil/remembug-cli

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• 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: evidence.maintainer_signals | https://github.com/zaitanabil/remembug-cli

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• 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: evidence.maintainer_signals | https://github.com/zaitanabil/remembug-cli

Community Discussion Evidence

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

• Configuration risk requires verification - GitHub / issue