Related Pages

Related topics: Memory Lifecycle, Curation & Quality, CLI, HTTP API, Web & Admin Dashboards

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

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

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 [email protected] 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.

Related Pages

Related topics: System Overview & Architecture, CLI, HTTP API, Web & Admin Dashboards

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.

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.

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.

Related Pages

Related topics: System Overview & Architecture, Memory Lifecycle, Curation & Quality, Agent Integrations, MCP, Plugins & Deployment

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 [email protected] 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.

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.

flowchart LR
  CLI[CLI<br/>apps/cli] -->|HTTPS JSON| API[HTTP API<br/>apps/api]
  Web[Web Dashboard<br/>apps/web] -->|HTTPS JSON| API
  Admin[Admin Dashboard<br/>apps/web/admin] -->|admin token| API
  API --> Mem[(Memory Store<br/>+ FTS index)]
  API --> Cfg[(Config Schema<br/>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.

Related Pages

Related topics: System Overview & Architecture, CLI, HTTP API, Web & Admin Dashboards

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.

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.

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

Doramagic Pitfall Log

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

2. 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/MiguelMedeiros/unforgit

3. 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/MiguelMedeiros/unforgit

4. 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/MiguelMedeiros/unforgit

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: downstream_validation.risk_items | https://github.com/MiguelMedeiros/unforgit

6. 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/MiguelMedeiros/unforgit

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

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

8. 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/MiguelMedeiros/unforgit

9. 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/MiguelMedeiros/unforgit

Community Discussion Evidence

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

• Remove deprecated prebuild-install warning from global CLI install - github / github_issue
• v0.8.0 Reviewable Memory Curation - github / github_issue
• v0.9.3 - github / github_release
• v0.9.2 - github / github_release
• v0.9.1 - github / github_release
• v0.9.0 - github / github_release
• v0.8.5 - github / github_release
• v0.8.4 - github / github_release
• v0.8.3 - github / github_release
• v0.8.2 - github / github_release
• v0.8.1 - github / github_release
• v0.8.0 - github / github_release