# https://github.com/MiguelMedeiros/unforgit Project Manual Generated at: 2026-07-16 20:45:29 UTC ## Table of Contents - [System Overview & Architecture](#page-1) - [Memory Lifecycle, Curation & Quality](#page-2) - [CLI, HTTP API, Web & Admin Dashboards](#page-3) - [Agent Integrations, MCP, Plugins & Deployment](#page-4) ## System Overview & Architecture ### Related Pages Related topics: [Memory Lifecycle, Curation & Quality](#page-2), [CLI, HTTP API, Web & Admin Dashboards](#page-3)
Related Source Files The following source files were used to generate this page: - [README.md](https://github.com/MiguelMedeiros/unforgit/blob/main/README.md) - [package.json](https://github.com/MiguelMedeiros/unforgit/blob/main/package.json) - [pnpm-workspace.yaml](https://github.com/MiguelMedeiros/unforgit/blob/main/pnpm-workspace.yaml) - [tsconfig.base.json](https://github.com/MiguelMedeiros/unforgit/blob/main/tsconfig.base.json) - [docker-compose.yml](https://github.com/MiguelMedeiros/unforgit/blob/main/docker-compose.yml) - [docs/architecture.md](https://github.com/MiguelMedeiros/unforgit/blob/main/docs/architecture.md)
# System Overview & Architecture ## 1. Purpose and Scope Unforgit is positioned as a daily agent memory system that emphasizes reviewable curation rather than irreversible, invisible broad merges. The project's headline theme, captured in the v0.8.0 release notes, is to "make Unforgit safe and pleasant to operate as a daily agent memory system" by providing a reviewable curation inbox before applying broad memory changes and making memory health visible across CLI, API, and dashboard surfaces. Source: [README.md:1-40]() The system exposes its functionality through several coordinated surfaces: a published CLI distributed via npm, an HTTP API for programmatic access, a web dashboard for curation workflows, and a static/mobile-friendly website. Each surface shares an underlying memory store and configuration model so that operators can move between them without losing context. Source: [package.json:1-60]() ## 2. Repository Layout and Build Topology The repository is organized as a pnpm monorepo. The workspace declaration enumerates the packages that compose the runtime and tooling, allowing shared TypeScript configuration, lockfile, and dependency management across the CLI, server, and frontend bundles. Source: [pnpm-workspace.yaml:1-20]() TypeScript compilation is centralized through a base configuration that downstream packages extend, enforcing consistent module resolution and compiler options. The root `package.json` defines workspace-level scripts, release configuration, and shared devDependencies such as conventional-changelog tooling used to generate the version history observed in the releases feed. Source: [tsconfig.base.json:1-30](), Source: [package.json:40-120]() | Surface | Role | Distribution | |---|---|---| | CLI | Agent-facing memory operations, installable via npm | `npm install -g unforgit` | | API | Programmatic memory CRUD, stats, admin endpoints | Containerized service | | Web dashboard | Reviewable curation inbox and memory health views | Static assets served by the API or CDN | | Website | Marketing/docs surface with mobile bridge | Static site | Source: [docker-compose.yml:1-60]() ## 3. Architectural Layers The architecture documented in `docs/architecture.md` separates concerns into four layers: - **Persistence layer** — A relational database with full-text search (FTS) capability backs memory records. Remote FTS recall is a first-class path, and filters are applied at the database tier rather than in application code, as evidenced by the v0.8.3 fix `db: apply filters in remote FTS recall`. Source: [docs/architecture.md:1-80]() - **Service layer** — HTTP endpoints expose memory CRUD, admin user management, API key issuance, and stats aggregation. Recent bug fixes highlight robust input handling: `api: handle missing user api key body` (v0.9.3), `api: validate stats numeric query params` (v0.9.2), and `api: tolerate empty admin consolidation` (v0.9.0). Source: [docs/architecture.md:80-160]() - **Curation layer** — Introduced as the central theme of v0.8.0, this layer buffers proposed broad memory changes in a reviewable inbox where operators can approve, reject, or refine entries before they are merged into long-term storage. Dashboard actions were added in commit `337c471` (`web: add reviewable curation dashboard actions`). Source: [docs/architecture.md:160-220]() - **Presentation layer** — The web dashboard, mobile bridge (v0.9.1 `website: improve mobile bridge and dashboard sections`, `website: simplify mobile navigation`), and CLI share rendering and interaction patterns. The v0.9.0 release introduced a markdown memory bridge that lets external editors feed Markdown documents into the curation pipeline. Source: [docs/architecture.md:220-280]() ```mermaid flowchart LR CLI[CLI] --> API[API Service] Web[Web Dashboard] --> API Mobile[Mobile Bridge] --> API MD[Markdown Memory Bridge] --> Curation API --> Curation[Reviewable Curation Inbox] Curation --> Store[(DB with FTS)] API --> Store Store --> Stats[Stats & Health Views] ``` ## 4. Configuration, Deployment, and Operational Concerns Configuration is validated at load time. The v0.8.4 release shipped `config: reject malformed numeric options`, indicating that numeric configuration fields are parsed and rejected early rather than allowed to propagate invalid values into runtime behavior. Source: [package.json:120-180]() Deployment is supported through `docker-compose.yml`, which orchestrates the API service alongside its database. This composition is the recommended path for self-hosted operators who want the full dashboard and API surface; the CLI can be installed independently from npm for agent hosts. The v0.8.1 release notes a "refresh audited dependency lockfile," reflecting ongoing supply-chain hygiene for the published artifacts. Source: [docker-compose.yml:1-80]() A known operational annoyance documented in issue #64 is that the published CLI emits a transitive `prebuild-install@7.1.3` deprecation warning during global install. The CLI's native addon stack pulls in this dependency, and the project tracks its removal as part of release hygiene. Source: [package.json:60-100]() ## 5. Recent Evolution and Community Signals The release cadence between v0.8.0 and v0.9.3 (June–July 2026) shows a consistent pattern: each release strengthens either the curation safety net or the robustness of API/admin endpoints. v0.8.0 added the curation dashboard; v0.8.3 hardened FTS filtering; v0.9.0 introduced the markdown memory bridge; v0.9.2 validated stats query parameters; v0.9.3 handled missing API key bodies gracefully. The activity heatmap surfaced in v0.8.3 (`web: clarify activity heatmap scope`) gives operators a temporal view of memory health, complementing the curation inbox. Source: [README.md:40-120]() Taken together, the architecture reflects a deliberate split between **safe-by-default memory writes** (curation inbox) and **observable memory health** (stats, heatmap, API/admin tooling), with CLI, web, and mobile surfaces acting as interchangeable entry points into the same backend. --- ## Memory Lifecycle, Curation & Quality ### Related Pages Related topics: [System Overview & Architecture](#page-1), [CLI, HTTP API, Web & Admin Dashboards](#page-3)
Related Source Files The following source files were used to generate this page: - [packages/core/src/lifecycle.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/core/src/lifecycle.ts) - [packages/core/src/lifecycle-maintenance.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/core/src/lifecycle-maintenance.ts) - [packages/core/src/lifecycle-scheduler.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/core/src/lifecycle-scheduler.ts) - [packages/core/src/auto-consolidate.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/core/src/auto-consolidate.ts) - [packages/core/src/auto-consolidate-remote.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/core/src/auto-consolidate-remote.ts) - [packages/core/src/quality.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/core/src/quality.ts)
# Memory Lifecycle, Curation & Quality The Memory Lifecycle, Curation & Quality subsystem governs how memories transition through their usable states, how broad changes are reviewed before being applied, and how the health of the overall memory store is measured. It is the safeguard layer that turns Unforgit from a write-once store into a safe, daily agent memory system, addressing the **Reviewable Memory Curation** goals introduced in v0.8.0 ("make Unforgit safe and pleasant to operate as a daily agent memory system, without irreversible or invisible broad merges") `Source: [packages/core/src/lifecycle.ts:1-40]()`. ## Core Responsibilities The subsystem is responsible for five intertwined concerns: - **State management** — tracking where each memory sits in its usable lifetime (`Source: [packages/core/src/lifecycle.ts:42-110]()`). - **Scheduled maintenance** — running background checks and transitions on a deterministic cadence (`Source: [packages/core/src/lifecycle-scheduler.ts:20-90]()`). - **Quality assessment** — scoring, flagging, and surfacing memories that have degraded or duplicated (`Source: [packages/core/src/quality.ts:1-70]()`). - **Auto-consolidation** — applying reviewable merges of related memories, locally and against the remote store (`Source: [packages/core/src/auto-consolidate.ts:30-120]()`, `Source: [packages/core/src/auto-consolidate-remote.ts:25-95]()`). - **Operational hygiene** — pruning stale entries and repairing malformed records (`Source: [packages/core/src/lifecycle-maintenance.ts:15-85]()`). Together these modules implement the "reviewable curation inbox" and "visible memory health" promised by the v0.8.0 release theme. ## Lifecycle States and Transitions A memory in Unforgit moves through a small set of explicit states rather than being silently mutated. The state machine is defined in the lifecycle module and is the contract that the curation UI, the scheduler, and the consolidation engine all agree on `Source: [packages/core/src/lifecycle.ts:55-140]()`. | State | Description | Allowed transition | |-------|-------------|--------------------| | `active` | Currently trusted for recall and use | → `review` | | `review` | Awaiting human verdict in the curation inbox | → `active` / `archived` | | `archived` | Retained but excluded from recall by default | → `review` (via reactivation) | | `pruned` | Removed from the recall index; soft-deleted | terminal | Transitions are validated centrally: any writer, including the remote consolidator, must call into the lifecycle transition function, which enforces the allowed edges and records provenance for audit `Source: [packages/core/src/lifecycle.ts:150-205]()`. This guarantees that broad merges cannot bypass the review queue, satisfying the v0.8.0 goal of "no invisible broad merges" `Source: [packages/core/src/auto-consolidate.ts:120-180]()`. ## Reviewable Curation Workflow The curation pipeline is the user-facing component introduced with v0.8.0. It is the bridge between automated maintenance and operator trust. ```mermaid flowchart LR A[Auto Consolidate] -->|candidate set| B[Curation Inbox] B --> C{Operator verdict} C -->|accept| D[active] C -->|reject| E[archived] C -->|edit| F[edited -> active] D --> G[recall eligible] E --> H[excluded from recall] ``` 1. **Candidate generation** — `auto-consolidate.ts` groups near-duplicate or overlapping memories using recall indexes; it produces a *candidate set* rather than mutating in place `Source: [packages/core/src/auto-consolidate.ts:200-260]()`. 2. **Remote variants** — the same logic for clients whose primary store is remote applies filters consistently so that the dashboard does not silently drop candidates due to FTS mismatches; the v0.8.3 fix `db: apply filters in remote FTS recall` lives here `Source: [packages/core/src/auto-consolidate-remote.ts:120-180]()`. 3. **Inbox presentation** — the dashboard surfaces the candidates with the proposed merge text, the evidence links, and the affected memories; the actions that accept, reject, or edit entries were added by the v0.8.0 commit `web: add reviewable curation dashboard actions`. 4. **Application** — only after an explicit verdict does the candidate promote to the `active` state through the lifecycle transition function, preserving a revert path `Source: [packages/core/src/lifecycle.ts:210-260]()`. ## Scheduling, Quality, and Maintenance Behind the curation UI, three background systems keep the store healthy: - **Scheduler** — `lifecycle-scheduler.ts` runs maintenance passes on a fixed clock, calling into `lifecycle-maintenance.ts` for pruning and into `quality.ts` for scoring, and emits events the dashboard can observe `Source: [packages/core/src/lifecycle-scheduler.ts:90-160]()`. - **Quality signals** — `quality.ts` computes per-memory scores from freshness, recall hit rate, and duplication density; scores below a configured threshold move the memory to `review`, which is how the system makes degradation visible rather than silent `Source: [packages/core/src/quality.ts:80-150]()`. - **Maintenance** — `lifecycle-maintenance.ts` performs the actual repairs: re-encoding stale identifiers (the v0.8.0 fix `encode remote client path identifiers`), resolving orphaned references, and guaranteeing that the database and the recall index stay consistent `Source: [packages/core/src/lifecycle-maintenance.ts:95-165]()`. ## Practical Implications - Use the CLI or dashboard to clear the curation inbox regularly; letting candidates pile up defers quality improvements and keeps the scheduler busy reprocessing the same items `Source: [packages/core/src/lifecycle-scheduler.ts:170-210]()`. - Numeric configuration values — such as consolidation thresholds, quality cutoffs, and scheduler intervals — are validated strictly as of v0.8.4 (`config: reject malformed numeric options`), so passing strings where numbers are expected will return an error rather than silently defaulting `Source: [packages/core/src/lifecycle-scheduler.ts:30-70]()`. - The remote consolidator is tolerant of empty admin bodies since v0.8.5, but operators should still confirm `review` entries before bulk-accepting, because once promoted to `active`, a memory becomes the source of truth for downstream recall. When the user-reported issue #64 about a transitive `prebuild-install` deprecation is also relevant context: removing the warning keeps the operator's installation output clean, but it does not change the lifecycle semantics described above; the curation inbox remains the primary place where broad merges are gated. --- ## CLI, HTTP API, Web & Admin Dashboards ### Related Pages Related topics: [System Overview & Architecture](#page-1), [Memory Lifecycle, Curation & Quality](#page-2), [Agent Integrations, MCP, Plugins & Deployment](#page-4)
Related Source Files The following source files were used to generate this page: - [apps/cli/src/index.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/index.ts) - [apps/cli/src/utils.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/utils.ts) - [apps/cli/src/commands/add.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/add.ts) - [apps/cli/src/commands/recall.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/recall.ts) - [apps/cli/src/commands/init.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/init.ts) - [apps/cli/src/commands/dashboard.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/commands/dashboard.ts) - [apps/api/src/server.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/api/src/server.ts) - [apps/api/src/routes/memories.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/api/src/routes/memories.ts) - [apps/api/src/routes/admin.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/api/src/routes/admin.ts) - [apps/api/src/routes/stats.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/api/src/routes/stats.ts) - [apps/api/src/middleware/auth.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/api/src/middleware/auth.ts) - [apps/web/src/App.tsx](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/web/src/App.tsx) - [apps/web/src/components/CurationInbox.tsx](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/web/src/components/CurationInbox.tsx) - [apps/web/src/components/ActivityHeatmap.tsx](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/web/src/components/ActivityHeatmap.tsx) - [apps/web/src/bridges/MarkdownBridge.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/web/src/bridges/MarkdownBridge.ts) - [apps/web/src/admin/AdminLayout.tsx](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/web/src/admin/AdminLayout.tsx) - [packages/config/src/schema.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/packages/config/src/schema.ts)
# CLI, HTTP API, Web & Admin Dashboards Unforgit is a daily agent memory system that exposes its functionality through four complementary surfaces: a **CLI** for local, scripted use; an **HTTP API** for programmatic integrations; a **Web dashboard** for visual review and curation; and an **Admin dashboard** for operators. All surfaces share a common config schema and the same underlying memory store, so behavior and limits remain consistent from terminal to browser. ## CLI Surface The CLI entry point bootstraps command parsing and dispatches to per-command modules under `apps/cli/src/commands/`. - `add.ts` — persists a new memory entry (content, tags, source). Used both interactively and by agents that capture context. - `recall.ts` — performs FTS-backed recall against the local or remote store; honors filters introduced in v0.8.3 (`Source: [apps/cli/src/commands/recall.ts]()`). - `init.ts` — initializes a workspace, writes a default config file, and authenticates with the API. - `dashboard.ts` — opens the Web/Admin dashboards in the user's browser (delegates to the Web app's deep links). Shared helpers (colored output, prompt handling, HTTP client) live in `utils.ts`. The global install path was hardened in issue #64 to drop the deprecated `prebuild-install@7.1.3` warning (`Source: [apps/cli/src/index.ts]()`). ## HTTP API Surface The HTTP API is a thin, JSON-only service registered in `server.ts`. It is partitioned into three route groups. | Route group | Module | Notable endpoints | |---|---|---| | Memories | `routes/memories.ts` | `POST /memories`, `GET /memories`, `GET /memories/:id`, `POST /memories/recall` | | Stats | `routes/stats.ts` | `GET /stats/activity`, `GET /stats/summary` — numeric query params validated (v0.9.2) | | Admin | `routes/admin.ts` | `GET/POST /admin/users`, `POST /admin/consolidate`, `POST /admin/curation/*` | Auth is enforced through a single middleware that distinguishes **user API keys** from **admin tokens** (`Source: [apps/api/src/middleware/auth.ts]()`). Two recent fixes are worth noting because they affected availability: v0.9.3 made user-key endpoints tolerate a missing/empty request body, and v0.9.2 rejected non-numeric `limit`/`offset` values in stats queries with a 400 (`Source: [apps/api/src/routes/stats.ts]()`). Admin consolidation in v0.9.0 was hardened to handle an empty consolidation payload gracefully. ```mermaid flowchart LR CLI[CLI
apps/cli] -->|HTTPS JSON| API[HTTP API
apps/api] Web[Web Dashboard
apps/web] -->|HTTPS JSON| API Admin[Admin Dashboard
apps/web/admin] -->|admin token| API API --> Mem[(Memory Store
+ FTS index)] API --> Cfg[(Config Schema
packages/config)] CLI -. reads .-> Cfg ``` ## Web Dashboard The Web app is a single-page React application mounted in `App.tsx`. It is designed to make memory health **visible** before any irreversible merge, per the v0.8.0 *Reviewable Memory Curation* goals (`Source: [apps/web/src/components/CurationInbox.tsx]()`). Key components: - **CurationInbox** — shows pending memory candidates (deduplicates, conflicts, low-confidence writes) and exposes per-item *accept / merge / reject* actions wired to the admin curation API. - **ActivityHeatmap** — renders the per-day write volume returned by `/stats/activity`; the v0.8.3 fix clarified that the heatmap scope is the local agent's workspace only, not global (`Source: [apps/web/src/components/ActivityHeatmap.tsx]()`). - **MarkdownBridge** — added in v0.9.0 (issue #68), it lets users round-trip memories through markdown files for use in editors and PRs (`Source: [apps/web/src/bridges/MarkdownBridge.ts]()`). Mobile navigation was simplified in v0.9.1 to keep the bridge and dashboard sections reachable on small screens. ## Admin Dashboard The Admin dashboard shares the Web bundle but mounts under `/admin` via `AdminLayout.tsx`, which gates entry on an admin token and renders a separate navigation tree. It surfaces: - **User management** — list/create users and rotate API keys. v0.8.5 added tolerance for an empty request body when creating a user (`Source: [apps/api/src/routes/admin.ts]()`). - **Consolidation controls** — trigger or schedule merges, with safe defaults when no payload is provided. - **Curation review** — the operator-side counterpart of `CurationInbox`, used to accept or reject bulk changes before they are committed to the canonical store. ## Cross-Cutting Configuration Every surface reads from the same JSON config, validated by `packages/config/src/schema.ts`. v0.8.4 added strict rejection of malformed numeric options (e.g., `port`, `retentionDays`), preventing silent fallbacks that previously caused confusing runtime errors on the CLI and in the API (`Source: [packages/config/src/schema.ts]()`). Together, these four surfaces let operators **script** with the CLI, **integrate** via the HTTP API, **review** through the Web dashboard, and **govern** through the Admin dashboard, all backed by one memory store and one config schema. --- ## Agent Integrations, MCP, Plugins & Deployment ### Related Pages Related topics: [System Overview & Architecture](#page-1), [CLI, HTTP API, Web & Admin Dashboards](#page-3)
Related Source Files The following source files were used to generate this page: - [apps/mcp/src/index.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/mcp/src/index.ts) - [apps/cli/src/ide-integration.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/ide-integration.ts) - [apps/cli/src/cursor-rule.ts](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/src/cursor-rule.ts) - [apps/cli/server.json](https://github.com/MiguelMedeiros/unforgit/blob/main/apps/cli/server.json) - [plugins/claude-code/unforgit/.claude-plugin/plugin.json](https://github.com/MiguelMedeiros/unforgit/blob/main/plugins/claude-code/unforgit/.claude-plugin/plugin.json) - [plugins/claude-code/unforgit/.mcp.json](https://github.com/MiguelMedeiros/unforgit/blob/main/plugins/claude-code/unforgit/.mcp.json)
# Agent Integrations, MCP, Plugins & Deployment ## Overview Unforgit exposes its agent memory system to external editors and AI agents through three coordinated layers: an MCP (Model Context Protocol) server, IDE-specific integrations (Cursor and Claude Code), and a plugin manifest pair used by the Claude Code plugin loader. Together these surfaces let agents read, write, and curate unforgit memories directly from inside the user's development environment without going through the dashboard. The MCP server is the canonical transport. It wraps unforgit's CLI commands behind the `tools/list` and `tools/call` MCP methods, accepts stdio framing, and is the single integration point reused by every downstream consumer. Source: [apps/mcp/src/index.ts:1-40]() ## MCP Server The MCP entry point is registered in `apps/mcp/src/index.ts`. The server boots over stdio, advertises the unforgit memory tools, and proxies each invocation to the local CLI binary. Because the transport is stdio, the same process can be launched by any MCP-compatible host — Claude Desktop, Cursor, or a custom agent runner — without additional networking. The CLI side exposes a parallel MCP descriptor at `apps/cli/server.json`. This file is the discovery artifact that hosts read before spawning the server: it declares the server name, version, command to invoke, and the set of supported transports. Both `stdio` and `http` transports are advertised so the same descriptor can drive local editor integrations and remote agent deployments. | Artifact | Role | | --- | --- | | `apps/mcp/src/index.ts` | Runtime MCP server (stdio transport, tool routing) | | `apps/cli/server.json` | MCP descriptor (name, version, command, transports) | | `apps/cli/src/ide-integration.ts` | Helpers to detect the host editor and configure launch | Source: [apps/cli/server.json:1-20](), [apps/mcp/src/index.ts:1-60]() ## IDE Integration Layer The `ide-integration.ts` module centralizes editor detection. It inspects environment variables and process arguments to identify whether unforgit is being launched from Cursor, Claude Code, VS Code, or a generic shell, and returns the appropriate launch context. The same module writes the host-specific configuration files that point the editor at the running MCP server. `cursor-rule.ts` is the Cursor-specific companion. It materializes a `.cursorrules` entry (and supporting JSON) so that Cursor's agent mode recognizes unforgit's memory tools, applies project-level scope automatically, and surfaces reviewable curation commands in the inline suggestions. The rule file is generated idempotently, which means re-running the CLI in an existing project refreshes the rule without duplicating it. ```mermaid flowchart LR A[Host IDE / Agent] -->|stdio| B[apps/mcp/src/index.ts] B --> C[CLI bridge] C --> D[Memory store] A -.config.-> E[ide-integration.ts] E --> F[cursor-rule.ts] F --> A ``` Source: [apps/cli/src/ide-integration.ts:1-50](), [apps/cli/src/cursor-rule.ts:1-40]() ## Claude Code Plugin The Claude Code side is delivered as a plugin under `plugins/claude-code/unforgit/`. Two manifest files govern the loading: - `.claude-plugin/plugin.json` — declares the plugin metadata, entry points, and required permissions so Claude Code can register unforgit as a first-class plugin. - `.mcp.json` — points the plugin loader at the MCP server descriptor (`apps/cli/server.json`) and selects the `stdio` transport, allowing the plugin to spawn the server on demand. This two-file split keeps plugin metadata and MCP wiring independent. A maintainer can bump the MCP server version in `server.json` without touching `plugin.json`, or change the plugin's display metadata without disturbing transport configuration. Source: [plugins/claude-code/unforgit/.claude-plugin/plugin.json:1-20](), [plugins/claude-code/unforgit/.mcp.json:1-20]() ## Deployment Notes For local development, `npm link` (or `bun link`) from the repo root exposes the `unforgit` binary on the user's `PATH`; the CLI then auto-writes the IDE-specific config when run inside a project. Issue #64 tracks an unrelated npm deprecation noise from the `prebuild-install` transitive dependency, which surfaces during global installs and has been queued for removal. For hosted deployments, the same `server.json` descriptor is published to the MCP registry so remote agents can resolve the unforgit server by name. v0.9.3 hardened the API path that backs remote memory access — the fix in commit `290ca12` ensures the server tolerates a missing user API key body without crashing the descriptor lookup, which is important because plugin loaders probe the server before any user credentials are configured. Source: [apps/cli/server.json:1-30](), [apps/mcp/src/index.ts:40-80](), [community: issue #64](), [community: v0.9.3 release notes]() ## Versioned Compatibility The descriptor in `server.json` carries a version field that the CLI and the plugin both check at startup. When the plugin's `.mcp.json` requests a server version newer than the installed CLI, the IDE-integration helper prints a remediation message rather than failing silently. The v0.8.0 "Reviewable Memory Curation" milestone (issue #55) introduced additional memory-health tools that the MCP server must expose to keep dashboards and plugins in sync, which is why the version handshake is enforced explicitly. Source: [apps/cli/server.json:1-15](), [apps/cli/src/ide-integration.ts:30-70](), [community: issue #55]() --- --- ## Pitfall Log Project: MiguelMedeiros/unforgit Summary: Found 9 structured pitfall item(s), including 1 high/blocking item(s). Top priority: Security or permission risk - Security or permission risk requires verification. ## 1. Security or permission risk - Security or permission risk requires verification - Severity: high - 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/MiguelMedeiros/unforgit/issues/55 ## 2. 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/MiguelMedeiros/unforgit ## 3. 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/MiguelMedeiros/unforgit ## 4. 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/MiguelMedeiros/unforgit ## 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: downstream_validation.risk_items | https://github.com/MiguelMedeiros/unforgit ## 6. 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/MiguelMedeiros/unforgit ## 7. 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/MiguelMedeiros/unforgit/issues/64 ## 8. 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/MiguelMedeiros/unforgit ## 9. 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/MiguelMedeiros/unforgit