Related Pages

Related topics: Search Tools, MCP & Data Pipeline, Multi-IDE Adapters & Provider Extensibility, Server-Beta Runtime, Telemetry & Operations

Overview & System Architecture

Claude-Mem is a persistent memory compression system built for Claude Code. It preserves context across sessions by automatically capturing tool-usage observations, generating semantic summaries, and re-injecting relevant memories into new sessions. This page documents the high-level architecture that makes that work end-to-end.

Purpose and Scope

The system targets a specific problem: Claude Code's per-session context window is ephemeral, so projects lose continuity whenever a session ends or reconnects. Claude-Mem solves this by sitting between the host IDE (Claude Code, Gemini CLI, OpenCode, or Codex) and an LLM observer, capturing raw tool events, compressing them into structured XML observations, and replaying them at the start of future sessions.

The product is published on npm as claude-mem (v13.8.0 at the time of writing). The repository explicitly notes that npm install -g claude-mem installs only the SDK — the working plugin requires npx claude-mem install or the in-Code /plugin commands to register hooks and the worker service. Source: README.md:1-50

The license is Apache-2.0 to make the agentic-memory core embeddable in developer tools, MCP servers, and production agent harnesses. The ragtime/ subdirectory carries its own LICENSE. Source: README.md:1-50, package.json:1-40

High-Level Architecture

Claude-Mem is composed of three layers: a host-IDE hook layer that captures events, a worker service that persists and serves memory, and a generation/serving layer that produces the structured observations. The hook layer is the only part that runs inside the host CLI; everything else is a long-lived HTTP daemon.

flowchart LR
    A["Host IDE<br/>(Claude Code, Gemini CLI,<br/>OpenCode, Codex)"] -->|lifecycle events| B["Hook Layer<br/>plugin/hooks/*.json<br/>+ scripts/*.cjs"]
    B -->|HTTP POST 37777| C["Worker Service<br/>plugin/scripts/worker-service.cjs"]
    C --> D[("SQLite<br/>sessions, observations,<br/>summaries")]
    C --> E[("Chroma<br/>vector index<br/>(optional)")]
    C -->|context injection| A
    C <-. MCP .-> F["MCP Search Tools<br/>plugin/scripts/mcp-server.cjs"]
    C --> G["Web Viewer UI<br/>http://localhost:37777"]
    C --> H["OpenClaw Gateway<br/>openclaw/src/"]

Key architectural facts:

• Six hook scripts are wired through plugin/hooks/hooks.json and plugin/hooks/codex-hooks.json for the five lifecycle stages (SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd) plus a cached dependency checker. Source: README.md:1-100
• The worker service listens on TCP port 37777 by default and exposes an HTTP API plus the web viewer. Source: README.md:1-100
• Storage is a local SQLite database (sessions, observations, summaries). Source: README.md:1-100
• A Chroma vector database is optional (CLAUDE_MEM_CHROMA_ENABLED) and provides hybrid semantic + keyword search. Source: README.md:1-100
• Search is exposed as 4 MCP tools following a token-efficient 3-layer workflow (search → timeline → get_observations). Source: README.md:1-100

Core Subsystems

Hook Layer

The hook layer is the only component that lives inside the host CLI. It shells out to the worker over HTTP, which keeps the hooks themselves small, fast, and easy to reason about. The hooks trigger context generation on session start, surface observations on prompts, capture tool results on PostToolUse, and finalize on stop and end.

The codex-hooks.json file is the Codex-CLI equivalent of hooks.json and is validated at build time against the list of event names that Codex supports; a recent regression in Codex 0.140.0 stemmed from a root-level description field that the build validator now enforces against. Source: plugin/hooks/codex-hooks.json

Worker Service and HTTP API

The worker is the long-lived backbone. It accepts observation submissions, runs FTS5 keyword search and Chroma semantic search, and serves a React-based viewer at http://localhost:37777. The server also exposes a small allow-list of operations and topics to keep the LLM-facing tool surface tight. Source: src/services/server/allowed-constants.ts:1-10

export const ALLOWED_OPERATIONS = [
  'search', 'context', 'summarize', 'import', 'export'
];
export const ALLOWED_TOPICS = [
  'workflow', 'search_params', 'examples', 'all'
];

Source: src/services/server/allowed-constants.ts:1-10

Observation Generation

When the worker batches raw tool events, it calls into a provider-agnostic prompt builder that constructs an XML schema (<observation> blocks containing <title>, <subtitle>, <facts>, <narrative>, <concepts>, <files_read>, <files_modified>). The generator also runs privacy scrubbing via stripTags() on the payload and bails out with a single <skip_summary /> element when nothing durable remains. Source: src/server/generation/providers/shared/prompt-builder.ts:1-100

The SDK mirrors this XML output schema in src/sdk/prompts.ts, including per-field character budgets that elide oversized content with explicit <elided ... /> markers so the observer model cannot fabricate detail about missing ranges. Source: src/sdk/prompts.ts:1-80

Output Fidelity and Recovery

The observer SDK is expected to emit <observation>/<summary> XML, but it sometimes returns conversational prose, an idle/empty string, or a "session exhausted" closure string. An ObserverOutputClass classifier in src/sdk/output-classifier.ts splits those failure modes into xml | idle | prose | poisoned so the pipeline can log a visible preview, avoid respawn churn on benign idle output, and trigger recovery when the SDK session is wedged. Source: src/sdk/output-classifier.ts:1-60

OpenClaw Gateway

openclaw/ is a separate gateway service that consumes the observation feed and forwards important entries to downstream channels (e.g. Discord). The test suite in openclaw/src/index.test.ts confirms that important-feed tagged observations are sent with full narrative, facts, and concepts, and that non-observation events are filtered out. Source: openclaw/src/index.test.ts:1-50

Data Flow

1. A user prompt or tool result fires an IDE lifecycle event.
2. The matching hook script sends the payload to http://localhost:37777.
3. The worker batches events, scrubs <private>-tagged content, and calls the observer LLM.
4. The observer returns XML observations; the output classifier routes xml to storage, idle/prose to a diagnostic log, and poisoned to a session-respawn path.
5. Observations are written to SQLite and (optionally) embedded into Chroma.
6. On the next SessionStart, the worker injects the most relevant observations back into the new context window, using context-generator.cjs and the 3-layer search / timeline / get_observations MCP tools.

Known Failure Modes and Community Hot Spots

Several recurring issues stem from the architecture's assumptions about the host environment:

• Windows port contention: A stale worker holding port 37777 combined with an aggressive spawn cooldown can block prompts for ~15 minutes. Source: issue #2996
• Windows IPv4/IPv6 split: The worker binds to 127.0.0.1 only; on some Windows hosts localhost resolves to ::1 first, causing the 29-second hook timeout. Source: issue #2992
• Chroma subprocess leak on macOS: CLAUDE_MEM_CHROMA_ENABLED=true (default) has been observed to leave uv+python3.13 zombie pairs accumulating across sessions. Source: issue #2950
• CLAUDE.md filesystem pollution: Earlier modes created CLAUDE.md files in every touched directory; the project now supports disabling this, but long-time users still surface it as a complaint. Source: issue #609, issue #632
• server-beta runtime gaps: When CLAUDE_MEM_RUNTIME=server-beta, several endpoints (/api/logs, /stream, /api/observations) are not registered, breaking the viewer UI; SessionStart injection is also not runtime-aware and pulls stale/empty context. Sources: issue #2989, issue #2991, issue #2987
• Custom API endpoints: Only the bundled providers are wired in, so LiteLLM/ANTHROPIC_BASE_URL proxies require manual configuration. Source: issue #943

Telemetry itself has been deliberately compressed: as of v13.6.2, high-volume session_compressed and context_injected events are aggregated into 5-minute rollups (observer_turn_rollup, context_injected_rollup) before being forwarded to PostHog, dropping roughly 45M individual events per month to ~20K rollup records. Source: v13.6.2 release notes

See Also

• Hooks Reference — all seven hook scripts
• Worker Service — HTTP API & Bun management
• Database — SQLite schema & FTS5 search
• Search Architecture — hybrid search with Chroma
• Configuration — environment variables & settings
• Troubleshooting — common issues & solutions

Related Pages

Related topics: Overview & System Architecture, Multi-IDE Adapters & Provider Extensibility, Server-Beta Runtime, Telemetry & Operations

Search Tools, MCP & Data Pipeline

Overview

Claude-Mem exposes project memory to Claude Code (and compatible agents such as Gemini CLI and OpenCode) through a small, well-defined surface: a set of MCP search tools that query a data pipeline rooted in lifecycle hooks, a local HTTP worker, and a SQLite/vector storage layer. The goal is to let agents retrieve *durable* observations from past sessions without re-reading entire transcripts — trading full-text scans for token-efficient, progressively disclosed results. Source: README.md.

The project is published as version 13.8.0 (per package.json → "version": "13.8.0") and requires Node >=20.12.0 and Bun >=1.0.0 (see package.json → engines). The plugin bundle in plugin/ is what npx claude-mem install ultimately registers; the dist/ artifact is the SDK/library only and does not wire the worker or hooks. Source: README.md.

MCP Search Tools (3-Layer Workflow)

Claude-Mem's contract with the agent is a token-efficient three-layer pattern. Rather than dumping observation bodies into context, the model first requests a compact index, then drills down only for IDs it cares about:

Source: README.md (MCP Search Tools section).

A typical sequence is:

// Layer 1: cheap recall
search(query="authentication bug", type="bugfix", limit=10)
// Layer 2: orient around the most relevant IDs
timeline(anchor=<id from search>)
// Layer 3: fetch full payloads only for the keepers
get_observations(ids=[123, 456])

The advertised benefit is ~10x token savings by filtering before fetching details. The MCP tool surface lives behind the mem-search skill, which is split from the data-mutation surface (see Architecture Evolution and src/services/worker/README.md → "MCP vs Direct DB Split"). Source: src/services/worker/README.md.

Server-side Instruction Routing

The shared server component exposes a constrained instruction API for the search surface. Only a whitelist of operations and topics is accepted, which limits what the agent (or a third-party caller) can request through the search/help endpoints. Source: src/services/server/allowed-constants.ts.

The server extracts the relevant section of an embedded help document based on the requested topic (e.g., workflow → between ## The Workflow and ## Search Parameters). Source: src/services/server/Server.ts → extractInstructionSection / extractBetween.

flowchart LR
    Agent[Claude Code / Agent] -->|MCP call| MS[mem-search MCP Server]
    MS -->|HTTP| Worker[Worker Service :37777]
    Worker -->|query| DB[(SQLite + FTS5)]
    Worker -->|embed+query| CH[(Chroma Vector DB)]
    DB --> Worker
    CH --> Worker
    Worker -->|index/IDs| MS
    MS -->|get_observations| DB
    Agent -->|Layer 2 timeline| Worker

Data Pipeline (Hooks → Worker → Storage → Search)

The pipeline that feeds the search tools is entirely hook-driven. Five lifecycle hooks capture work as it happens, then hand it to a local worker that persists observations and (optionally) embeds them:

1. Capture — SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd emit agent events. A Smart Install pre-hook checks cached dependencies (it is not a lifecycle hook itself). Source: README.md → "How It Works".
2. Persist — The HTTP worker on port 37777 writes observations to a SQLite database and (when enabled) pushes embeddings to a Chroma vector store. Source: README.md.
3. Search — Subsequent sessions hit the same worker via MCP; hybrid search combines SQLite FTS5 results with Chroma semantic results, ranked and returned through the three-layer tools.

The worker is a Phase 1 refactor that "extracted route handlers from a WorkerService.ts monolith" into logical route classes, with all behavior preserved. The split — *search via MCP, data ops via direct DB access through a service layer* — is inherited from earlier phases and is expected to converge in Phase 2, when "the worker becomes a pure HTTP → MCP proxy". Source: src/services/worker/README.md.

Observation Generation Prompts

The pipeline is only as good as the observations it persists. Generation is provider-agnostic and emits structured <observation> XML blocks containing a title, subtitle, facts, narrative, concepts, and file lists. Sources: src/sdk/prompts.ts and src/server/generation/providers/shared/prompt-builder.ts.

The shared prompt builder in prompt-builder.ts wraps each PostgresAgentEvent in an <agent_event> block (with id, event_type, source_adapter, occurred_at), strips <private> tags, truncates oversized payloads, and then asks the LLM to produce one or more <observation> blocks. If nothing is worth recording, the model returns a self-closing <skip_summary /> tag — the empty result is itself a valid pipeline outcome. Source: src/server/generation/providers/shared/prompt-builder.ts → buildEventBlock, escapeXml, observation output schema.

Known Failure Modes & Community Pain Points

Several recurring issues shape how the search/pipeline surface behaves in practice:

• server-beta: stale/empty SessionStart context — The SessionStart hook unconditionally targets the local worker's GET /api/context/inject even under CLAUDE_MEM_RUNTIME=server-beta, so shared-mode sessions get stale or empty context. Source: issue #2991.
• server-beta: viewer UI routes missing — ServerViewerRoutes serves the shared viewer but does not register /api/logs, /stream, or /api/observations, leaving the "Loading more..." spinner stuck. Source: issue #2989.
• server-beta: observation_add / memory_add 400s — Both MCP tools fail with ValidationError against the server-beta backend, breaking live capture. Source: issue #2987.
• chroma-mcp subprocess leak on macOS — When CLAUDE_MEM_CHROMA_ENABLED=true (default), zombie uv + python3.13 pairs accumulate across sessions, growing the vector process footprint. Source: issue #2950.
• Windows IPv4/IPv6 mismatch — localhost resolves to ::1 first but the worker only binds 127.0.0.1, so the 29-second hook timeout fires. Source: issue #2992.
• Windows stale port + cooldown — A 3-failure "fail-loud" threshold combined with a fixed worker port lets one orphan hold the port for ~15 minutes under concurrent sessions. Source: issue #2996.
• OpenCode automatic capture does not initialize — The plugin loads and manual search works, but the chat.message hook is outdated, so auto-capture never starts. Source: issue #2986.

For users who want to keep the outputs of this pipeline (compacted memory) without running the worker, the community has explored plain-Markdown, repo-isolated indexes read at session start as an alternative — a useful fallback if the server/hooks surface is unavailable in a given environment. Source: issue #2982.

See Also

• Architecture Overview
• Worker Service
• Search Architecture
• Hooks Architecture
• Configuration
• Troubleshooting

Related Pages

Related topics: Overview & System Architecture, Search Tools, MCP & Data Pipeline, Server-Beta Runtime, Telemetry & Operations

Multi-IDE Adapters & Provider Extensibility

Overview

Claude-Mem is a persistent memory compression system that captures, summarizes, and re-injects project context across coding sessions. Because the agent ecosystem is heterogeneous — Claude Code, Gemini CLI, OpenCode, Codex, Cursor, and Windsurf all expose different hook payloads, transport mechanisms, and permission semantics — the project normalizes these differences through a small Platform Adapter contract. A separate Generation Provider abstraction handles the equally heterogeneous LLM landscape (claude, gemini, openrouter, and OpenAI-compatible proxies such as LiteLLM). Together, these two extension points let a single worker service speak to many IDEs and many model backends without forking the core capture-and-store pipeline. Source: src/cli/types.ts:30-44, README.md, package.json:1-25.

Platform Adapter Architecture

The contract that every IDE integration must satisfy is declared in src/cli/types.ts:

export interface PlatformAdapter {
  normalizeInput(raw: unknown): NormalizedHookInput;
  formatOutput(result: HookResult): unknown;
}

Two supporting types make the contract concrete. NormalizedHookInput is the canonical, IDE-agnostic shape of a hook event — sessionId, cwd, toolName, toolInput, toolResponse, transcriptPath, lastAssistantMessage, permissionMode, agentId, etc. — so downstream services never see vendor-specific JSON. HookResult is the inverse: a uniform outbound envelope carrying hookSpecificOutput.additionalContext, permissionDecision, systemMessage, or a blocking decision: "block" reason. Source: src/cli/types.ts:1-44.

EventHandler.execute(input) consumes the normalized input and returns a HookResult, which the adapter's formatOutput() then re-projects into the IDE's native response schema. This two-step shape — *normalize on the way in, project on the way out* — is what makes the worker transport-portable and is described as the Phase 2 target in src/services/worker/README.md:1-40, where the worker ultimately becomes a pure HTTP → MCP proxy.

Supported Adapters

The src/cli/adapters/index.ts barrel is the single registration point; adding a new IDE means writing a new file that implements PlatformAdapter and re-exporting it from the index.

Generation Provider Extensibility

Beyond IDE integration, the *summarization* path is also provider-pluggable. Generation providers share a common prompt builder that produces an XML-framed observation record (<title>, <subtitle>, <facts>, <narrative>, <concepts>, <files_read>, <files_modified>), with escapeXml() ensuring payload safety across all backends. Source: src/server/generation/providers/shared/prompt-builder.ts:1-40.

Downstream, processGeneratedResponse.ts records the originating provider label alongside each parsed observation, denormalizing identity context (source_adapter, actor_id, api_key_id) for audit traceability. Source: src/server/generation/processGeneratedResponse.ts:1-40.

Known Provider Gaps (community-reported)

• Custom endpoints / LiteLLM proxy — Issue #943 requests support for ANTHROPIC_BASE_URL-style overrides so users running LiteLLM, AWS Bedrock via LiteLLM, or claude-code-router can route summarization through their own gateways. Currently only the three named providers are wired in. Source: issue #943.
• Reasoning toggle for OpenRouter — Issue #2995 reports that OpenRouter's reasoning_effort field is forwarded even when the user wants raw, non-reasoning completions, producing empty or off-policy responses. A reasoning: false switch per provider is the requested mitigation. Source: issue #2995.
• OpenCode hook drift — Issue #2986 notes that the OpenCode adapter still subscribes to the legacy chat.message event after the upstream rename, so automatic capture fails to initialize even though the plugin loads and manual search still works. Source: issue #2986.

flowchart LR
  A[IDE Native Hook] --> B[Platform Adapter<br/>normalizeInput]
  B --> C[EventHandler.execute]
  C --> D[HookResult]
  D --> E[Platform Adapter<br/>formatOutput]
  E --> F[IDE Native Response]
  C --> G[Worker Service :37777]
  G --> H[Generation Provider<br/>claude / gemini / openrouter / proxy]
  H --> I[(SQLite + Chroma)]

Adding a New Adapter or Provider

1. New IDE: Create src/cli/adapters/<name>.ts implementing PlatformAdapter; map every IDE event to NormalizedHookInput; project HookResult back; export from src/cli/adapters/index.ts; add the install target to the npx claude-mem install --ide <name> switch.
2. New generation provider: Implement the provider interface used by processGeneratedResponse.ts (input shape: providerLabel, modelId, optional sourceAdapter/actorId/apiKeyId); route its requests through the shared prompt-builder; register any required environment variables in Configuration. The audit trail will automatically pick up provider and api_key_id once the response is processed.

Always validate the new adapter end-to-end: the worker must remain a single source of truth, and the adapter must round-trip both normalizeInput and formatOutput without losing fields like permissionMode, stopHookActive, or sessionSource (see the NormalizedHookInput shape). Source: src/cli/types.ts:1-29.

See Also

• Architecture Overview
• Hooks Architecture
• Worker Service
• Configuration
• Troubleshooting

Related Pages

Related topics: Overview & System Architecture, Search Tools, MCP & Data Pipeline, Multi-IDE Adapters & Provider Extensibility

Server-Beta Runtime, Telemetry & Operations

The server-beta runtime is the multi-tenant, long-lived service mode of Claude-Mem that runs the worker, HTTP API, job queue, generation workers, and viewer UI from a single Node process. It is selected by setting CLAUDE_MEM_RUNTIME=server-beta and is intended to replace the per-session local worker that ships as the default. This page documents its components, telemetry surface, and the operational issues that surfaced during community testing in v13.6.x and v13.8.x.

1. Runtime Components & Wiring

The runtime is composed in src/server/runtime/create-server-beta-service.ts, which assembles the following collaborators:

• ServerBetaService.ts — the top-level service that exposes start/stop lifecycle hooks and owns the Express HTTP server. It registers route modules and binds the configured port.
• ActiveServerBetaQueueManager.ts — a BullMQ-backed queue (bullmq ^5.76.6) used to serialize observation/summarization jobs across concurrent sessions sharing the singleton worker.
• ActiveServerBetaGenerationWorkerManager.ts — manages the spawned observer/summarizer SDK processes that consume queued jobs and emit XML <observation>/<summary> blocks built by src/server/generation/providers/shared/prompt-builder.ts.
• ServerViewerRoutes.ts — mounts the shared web viewer UI assets on the same HTTP port. The viewer expects backend routes such as /api/logs, /stream, and /api/observations to be registered alongside it.
• ServerJobQueue.ts — the queue definition, job schemas, and processor functions.

flowchart LR
    Hook[Lifecycle Hook<br/>SessionStart/PostToolUse] -->|POST job| QM[ActiveServerBetaQueueManager]
    QM -->|BullMQ| JQ[ServerJobQueue]
    JQ -->|consume| GWM[ActiveServerBetaGenerationWorkerManager]
    GWM -->|SDK call| SDK[Observer/Summarizer SDK]
    SDK -->|XML output| OC[output-classifier.ts]
    OC -->|storage| DB[(SQLite)]
    OC -->|SSE broadcast| Viewer[ServerViewerRoutes]
    Hook -.->|context inject| ServerBetaService

The architecture is intentionally a superset of the per-session worker described in src/services/worker/README.md: the local worker routes are still registered, but they are now multiplexed across all Claude Code sessions connected to the same server.

2. Output Classification & Job Pipeline

The generation worker pumps raw agent output through the classifier in src/sdk/output-classifier.ts. It returns one of four classes — xml, idle, prose, or poisoned — based on marker phrases like session exhausted, prompt is too long, or session closed. This decision drives whether jobs are stored, dropped with a logged preview, or trigger a worker respawn (source: src/sdk/output-classifier.ts:POISONED_MARKERS).

Batches that survive produce XML observation blocks via the prompt template in src/server/generation/providers/shared/prompt-builder.ts. The builder strips <private> tags, truncates payloads, and emits <observation>/<summary> elements that the storage layer persists and broadcasts over SSE from src/services/worker/agents/index.ts (broadcastObservation, broadcastSummary).

3. Telemetry: Rollups & Cost Reduction

Telemetry is a first-class concern of the server-beta runtime because all sessions funnel through it. Release v13.6.2 introduced TelemetryBuffer rollup windows that aggregate high-volume events:

v13.6.1 backfilled inferred generation-cost economics into anonymized daily rollups (#2934). v13.8.0 extended observer_turn_rollup to carry observations_created and the obs_type_* family (bugfix, discovery, etc.) so cache-value KPIs survive the migration off the legacy per-occurrence streams.

4. Known Operational Issues

Community testing has surfaced several server-beta-specific failures tracked in the issue tracker:

• #2987 — observation_add and memory_add MCP tools fail with 400 ValidationError in server-beta mode because the runtime forwards requests to the storage layer with a payload shape that the upstream validator does not accept.
• #2989 — The viewer UI is broken on the server-beta port: ServerViewerRoutes mounts the UI but the backend routes /api/logs, /stream, and /api/observations are not registered, so the "Loading more…" spinner never resolves.
• #2991 — SessionStart context-injection is not runtime-aware; the hook unconditionally calls the local worker's GET /api/context/inject even when running under CLAUDE_MEM_RUNTIME=server-beta, producing stale or empty context.
• #2996 — On Windows, a stale port holder combined with an aggressive spawn cooldown (fail-loud threshold = 3) blocks prompts for ~15 minutes.
• #2992 — On Windows, localhost resolves to ::1 (IPv6) first while the worker binds only to 127.0.0.1 (IPv4), causing 29s hook timeouts.

These are tracked alongside non-server-beta issues such as #2950 (Chroma subprocess leak on macOS) and #2995 (disabling reasoning for OpenRouter providers), all of which affect what users see when running the runtime.

5. Configuration

The runtime is selected via the CLAUDE_MEM_RUNTIME environment variable. Telemetry rollups, queue concurrency, port binding, and chroma subprocess management are configured alongside the rest of the worker settings documented in the main Configuration guide. The plugin package itself is published from package.json (v13.8.0 at the time of writing), which also pins bullmq ^5.76.6, pg ^8.20.0, and posthog-node ^5.36.15 as the transport dependencies for the queue, Postgres backend, and telemetry sink respectively.

See Also

• Architecture Overview
• Worker Service
• Hooks Architecture
• Configuration
• Troubleshooting

Doramagic Pitfall Log

Found 38 structured pitfall item(s), including 6 high/blocking item(s). Top priority: Installation risk - Installation risk requires verification.

1. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/thedotmack/claude-mem/issues/2982

2. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/thedotmack/claude-mem/issues/2986

3. Installation risk: Installation risk requires verification

• Severity: high
• Finding: Project evidence flags a installation risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/thedotmack/claude-mem/issues/2972

4. Configuration risk: Configuration risk requires verification

• Severity: high
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: community_evidence:github | https://github.com/thedotmack/claude-mem/issues/3016

5. 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/thedotmack/claude-mem/issues/2999

6. 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/thedotmack/claude-mem/issues/2950

7. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: OpenCode plugin loads but automatic capture does not initialize (outdated OpenCode hook: chat.message)
• User impact: Developers may fail before the first successful local run: OpenCode plugin loads but automatic capture does not initialize (outdated OpenCode hook: chat.message)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: OpenCode plugin loads but automatic capture does not initialize (outdated OpenCode hook: chat.message). Context: Observed when using windows
• Evidence: failure_mode_cluster:github_issue | https://github.com/thedotmack/claude-mem/issues/2986

8. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: Windows: stale port holder + aggressive spawn cooldown blocks prompts for ~15 min (fail-loud threshold 3 too low)
• User impact: Developers may fail before the first successful local run: Windows: stale port holder + aggressive spawn cooldown blocks prompts for ~15 min (fail-loud threshold 3 too low)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: Windows: stale port holder + aggressive spawn cooldown blocks prompts for ~15 min (fail-loud threshold 3 too low). Context: Observed when using node, windows
• Evidence: failure_mode_cluster:github_issue | https://github.com/thedotmack/claude-mem/issues/2996

9. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: observation_add / memory_add fail with 400 in server-beta mode
• User impact: Developers may fail before the first successful local run: observation_add / memory_add fail with 400 in server-beta mode
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: observation_add / memory_add fail with 400 in server-beta mode. Context: Observed when using node, linux
• Evidence: failure_mode_cluster:github_issue | https://github.com/thedotmack/claude-mem/issues/2987

10. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: server-beta viewer UI broken: missing /api/logs, /stream, /api/observations routes
• User impact: Developers may fail before the first successful local run: server-beta viewer UI broken: missing /api/logs, /stream, /api/observations routes
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: server-beta viewer UI broken: missing /api/logs, /stream, /api/observations routes. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/thedotmack/claude-mem/issues/2989

11. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: server-beta: SessionStart context injection is not runtime-aware (injects stale/empty context)
• User impact: Developers may fail before the first successful local run: server-beta: SessionStart context injection is not runtime-aware (injects stale/empty context)
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: server-beta: SessionStart context injection is not runtime-aware (injects stale/empty context). Context: Observed when using python
• Evidence: failure_mode_cluster:github_issue | https://github.com/thedotmack/claude-mem/issues/2991

12. Installation risk: Installation risk requires verification

• Severity: medium
• Finding: Developers should check this installation risk before relying on the project: tracking: Codex 0.140.0 rejects codex-hooks.json due to unsupported root description field
• User impact: Developers may fail before the first successful local run: tracking: Codex 0.140.0 rejects codex-hooks.json due to unsupported root description field
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: tracking: Codex 0.140.0 rejects codex-hooks.json due to unsupported root description field. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | https://github.com/thedotmack/claude-mem/issues/2972

Community Discussion Evidence

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

• Bug: ENV_PROXY_VARS stripped instead of preserved in sanitizeEnv() - github / github_issue
• chroma-mcp MCP-stdio child processes leak (one spawned per backfill, nev - github / github_issue
• Observation generation stuck in a self-sustaining poison→respawn loop: b - github / github_issue
• Windows: failed worker recycle on version bump leaves a zombie process h - github / github_issue
• Configurable embedding function (custom / OpenAI-compatible endpoint) - github / github_issue
• Addressing session-level context drift and vector bloat via local reposi - github / github_issue
• tracking: Codex 0.140.0 rejects codex-hooks.json due to unsupported root - github / github_issue
• Windows: stale port holder + aggressive spawn cooldown blocks prompts fo - github / github_issue
• Feature request: support disabling reasoning for OpenRouter / OpenAI-com - github / github_issue
• server-beta: SessionStart context injection is not runtime-aware (inject - github / github_issue
• server-beta viewer UI broken: missing /api/logs, /stream, /api/observati - github / github_issue
• observation_add / memory_add fail with 400 in server-beta mode - github / github_issue