# https://github.com/zaitanabil/remembug-cli Project Manual
Generated at: 2026-07-11 05:04:14 UTC
## Table of Contents
- [Project Overview & Getting Started](#page-1)
- [System Architecture & Data Flow](#page-2)
- [Capture Pipeline, Privacy Scrubbing & LLM Drafter](#page-3)
- [Storage, Search, MCP & Review UI](#page-4)
## Project Overview & Getting Started
### Related Pages
Related topics: [System Architecture & Data Flow](#page-2), [Capture Pipeline, Privacy Scrubbing & LLM Drafter](#page-3)
Related Source Files
The following source files were used to generate this page:
- [README.md](https://github.com/zaitanabil/remembug-cli/blob/main/README.md)
- [docs/quickstart.md](https://github.com/zaitanabil/remembug-cli/blob/main/docs/quickstart.md)
- [package.json](https://github.com/zaitanabil/remembug-cli/blob/main/package.json)
- [pnpm-workspace.yaml](https://github.com/zaitanabil/remembug-cli/blob/main/pnpm-workspace.yaml)
- [packages/cli/src/commands/init.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/cli/src/commands/init.ts)
- [packages/cli/src/commands/config.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/cli/src/commands/config.ts)
# 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.
| File / Directory | Role |
|---|---|
| `package.json` | Root manifest declaring workspaces, scripts, and dev tooling |
| `pnpm-workspace.yaml` | Declares `packages/*` as workspace members |
| `packages/cli/` | Main CLI package containing source under `src/commands/` |
| `docs/quickstart.md` | Step-by-step onboarding guide for new users |
| `README.md` | Top-level project description and usage examples |
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:
```bash
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.
```bash
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.
```bash
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.
```mermaid
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.
---
## System Architecture & Data Flow
### Related Pages
Related topics: [Project Overview & Getting Started](#page-1), [Capture Pipeline, Privacy Scrubbing & LLM Drafter](#page-3), [Storage, Search, MCP & Review UI](#page-4)
Related Source Files
The following source files were used to generate this page:
- [docs/architecture.md](https://github.com/zaitanabil/remembug-cli/blob/main/docs/architecture.md)
- [docs/claude-code-integration.md](https://github.com/zaitanabil/remembug-cli/blob/main/docs/claude-code-integration.md)
- [packages/daemon/src/index.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/index.ts)
- [packages/daemon/src/http.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/http.ts)
- [packages/daemon/src/config.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/config.ts)
- [packages/daemon/src/logger.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/logger.ts)
# 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.
| Process | Role | Entry Point |
| --- | --- | --- |
| `remembug` (CLI) | Short-lived; parses arguments, calls daemon over HTTP, prints results | `packages/cli/src/...` |
| `remembugd` (Daemon) | Long-lived; owns config, log file, and upstream integration | `packages/daemon/src/index.ts` |
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.
```mermaid
flowchart LR
User[Developer] --> CLI[remembug CLI]
CLI -- HTTP/JSON --> Daemon[remembugd daemon]
Daemon --> Store[(Local Store
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 ` 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.
---
## Capture Pipeline, Privacy Scrubbing & LLM Drafter
### Related Pages
Related topics: [System Architecture & Data Flow](#page-2), [Storage, Search, MCP & Review UI](#page-4)
Related Source Files
The following source files were used to generate this page:
- [docs/privacy.md](https://github.com/zaitanabil/remembug-cli/blob/main/docs/privacy.md)
- [packages/daemon/src/hooks/post-tool-use.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/hooks/post-tool-use.ts)
- [packages/daemon/src/hooks/stop.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/hooks/stop.ts)
- [packages/daemon/src/capture/span-detector.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/capture/span-detector.ts)
- [packages/daemon/src/capture/stack-detect.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/capture/stack-detect.ts)
- [packages/daemon/src/scrubber/index.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/scrubber/index.ts)
# 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.
```mermaid
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 `` 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 `Span`s, and the normalized `StackFrame`s, 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.
| Stage | Trigger | Input | Output |
| --- | --- | --- | --- |
| post-tool-use hook | every tool call | tool output | normalized CaptureEvent |
| stop hook | session end | full transcript | closing CaptureEvent |
| span-detector | CaptureEvent | free-form text | Span[] with code excerpts |
| stack-detect | CaptureEvent | error output | deduped StackFrame[] |
| scrubber | any captured payload | raw strings | sanitized strings |
| LLM Drafter | sanitized payload | CaptureEvent + spans + frames | structured bug report |
`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]()`
---
## Storage, Search, MCP & Review UI
### Related Pages
Related topics: [System Architecture & Data Flow](#page-2), [Capture Pipeline, Privacy Scrubbing & LLM Drafter](#page-3)
Related Source Files
The following source files were used to generate this page:
- [packages/daemon/src/store/index.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/store/index.ts)
- [packages/daemon/src/store/schema.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/store/schema.ts)
- [packages/daemon/src/embeddings/index.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/embeddings/index.ts)
- [packages/daemon/src/embeddings/local.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/embeddings/local.ts)
- [packages/daemon/src/embeddings/types.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/embeddings/types.ts)
- [packages/daemon/src/mcp/server.ts](https://github.com/zaitanabil/remembug-cli/blob/main/packages/daemon/src/mcp/server.ts)
# 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.
| Layer | Module | Responsibility |
| --- | --- | --- |
| Persistence | `store/index.ts`, `store/schema.ts` | Owns the on-disk store and its typed schema |
| Retrieval | `embeddings/index.ts`, `embeddings/local.ts`, `embeddings/types.ts` | Vectorizes query/object text for similarity search |
| Tool Bridge | `mcp/server.ts` | Exposes daemon capabilities as MCP tools/resources to LLMs |
| Review (consumer) | CLI / TUI consumer of `mcp/server.ts` | Surfaces stored items for human triage |
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
```mermaid
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` 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]().
---
---
## Pitfall Log
Project: zaitanabil/remembug-cli
Summary: 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
- 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 | https://github.com/zaitanabil/remembug-cli
## 2. 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 | https://github.com/zaitanabil/remembug-cli
## 3. 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 | https://github.com/zaitanabil/remembug-cli
## 4. 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 | https://github.com/zaitanabil/remembug-cli
## 5. 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 | https://github.com/zaitanabil/remembug-cli
## 6. 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 | https://github.com/zaitanabil/remembug-cli
## 7. 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 | https://github.com/zaitanabil/remembug-cli