Doramagic Project Pack · Human Manual

purmemo-mcp

Pūrmemo MCP integrates a persistent memory backend with AI coding agents through three coordinated surfaces: MCP tools callable from the model, session-start hooks injected into agent runt...

Installation, Sign-in & Auth Recovery

Related topics: MCP Tools, Hooks & Slash Commands, Architecture & Key Design Decisions

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: MCP Tools, Hooks & Slash Commands, Architecture & Key Design Decisions

Installation, Sign-in & Auth Recovery

pūrmemo's installation and authentication layer is designed around a single principle: a new user should reach a working memory in one command, and a returning user should never see a stack trace when their token goes stale. This page documents the install path, the OAuth/sign-in flow, and the recovery mechanisms that keep the CLI self-healing across hostile environments (macOS hostname drift, stale tokens, unreadable disk state).

Installation

The repository ships platform-specific installer scripts that bootstrap the CLI and register it with supported MCP clients (Claude Code, Codex, Gemini CLI). On POSIX systems the entry point is scripts/install.sh; on Windows it is scripts/install.ps1. Both scripts resolve dependencies, write the configured MCP entry into the host agent, and emit a short next-step hint Source: README.md:1-80. New users see a README that "gets out of their way" — the happy path is a single shell invocation that ends with the browser sign-in window already opening Source: scripts/install.sh:1-120.

For users who already have a partial install, the install scripts are idempotent: re-running them does not clobber an existing token, only refreshes the binary and hook configuration Source: scripts/install.sh:120-200. The PowerShell variant mirrors this contract Source: scripts/install.ps1:1-150.

Sign-in & OAuth Flow

After install, purmemo init triggers the sign-in path. The CLI delegates to oauth-manager.ts, which starts a local callback listener, opens the browser to the pūrmemo authorization page, and exchanges the returned code for an OAuth token Source: src/auth/oauth-manager.ts:1-180. The token is then handed to token-store.ts for at-rest encryption before persisting to disk Source: src/auth/token-store.ts:1-90.

Since v15.7.20, the CLI is no longer the only entry into this flow. If any later command detects a stale or missing token, it auto-launches the same browser sign-in with a one-line explanation instead of erroring out Source: src/cli/init.ts:1-140. This change collapsed two user-visible states ("installed but not signed in" and "was signed in, token expired") into one self-healing path.

Token Storage & Encryption Key

Tokens are encrypted with an OpenSSL symmetric cipher whose key is derived from local host identifiers via SHA-256(os.hostname() + os.userInfo().username) in legacy mode, or read from a persisted key file in current mode Source: src/auth/key-derivation.ts:1-110. The persisted-key mode was introduced in v15.7.18 to fix silent token corruption on macOS: when users switched Wi-Fi networks, toggled a VPN (NordVPN, etc.), or sleep/woke the laptop, os.hostname() flipped because of DHCP and Bonjour re-advertisement, producing a different key and an unreadable token Source: docs/ADR/039-token-storage-fallback.md:1-60.

The fallback strategy (ADR-039) lets the store try the persisted key first, then the legacy hostname-derived key, so a single hostname change does not brick the install Source: src/auth/token-store.ts:90-180.

Auth Recovery

Two distinct failure modes each have a dedicated recovery path, surfaced through recover.ts:

FailureTriggerRecovery actionIntroduced
Bad decrypt (recoverable)hostname/key mismatch on a still-valid token storere-derive with legacy key, keep goingv15.7.20
Bad decrypt (unrecoverable)both persisted and legacy keys fail, hostname drifted past the fallback windowauto-launch browser sign-in, replace tokenv15.7.19

Before v15.7.19, an unrecoverable decrypt surfaced as a raw OpenSSL error (error:1C80006...) and left the user effectively bricked, with no path back except a manual uninstall Source: src/cli/recover.ts:1-160. The current implementation catches that error class, deletes the unreadable ciphertext, and re-enters the OAuth flow without requiring the user to type purmemo init again Source: src/cli/recover.ts:160-260.

The same recovery entry point is reused by the install scripts, so a user who upgrades a bricked install gets the browser sign-in automatically on the next tool call instead of seeing an exception in their MCP client Source: src/auth/oauth-manager.ts:180-260.

Operational notes

  • Idempotent installs: re-running scripts/install.sh or scripts/install.ps1 preserves the token store; only binary and hook assets are refreshed.
  • Self-healing CLI: every command that needs the token funnels through token-store.ts, which is the single integration point for all three recovery paths above.
  • macOS users: prefer a stable hostname (disable Bonjour name randomization) if you cannot rely on the persisted-key file being readable across sessions.
  • Debug signal: a visible browser window opening unprompted means the recovery path fired — this is expected behavior, not a regression.

Source: https://github.com/purmemo-ai/purmemo-mcp / Human Manual

MCP Tools, Hooks & Slash Commands

Related topics: Installation, Sign-in & Auth Recovery, Architecture & Key Design Decisions

Section Related Pages

Continue reading this section for the full explanation and source context.

Section Tool registry and dispatch

Continue reading this section for the full explanation and source context.

Section Read and write tools

Continue reading this section for the full explanation and source context.

Section Handoff tool

Continue reading this section for the full explanation and source context.

Related topics: Installation, Sign-in & Auth Recovery, Architecture & Key Design Decisions

MCP Tools, Hooks & Slash Commands

Overview

Pūrmemo MCP integrates a persistent memory backend with AI coding agents through three coordinated surfaces: MCP tools callable from the model, session-start hooks injected into agent runtimes, and slash commands surfaced to the user. Together they let the agent read prior context at the start of a session, write new memory mid-session, and hand off work across sessions.

The MCP server registers its tool surface in src/server.ts, dispatches incoming tool calls to a handler registry in src/tools/handlers.ts, and delegates the heavier memory orchestration to src/intelligent-memory.ts and src/workflows/engine.ts. Hook installation for each supported agent (Claude Code, Gemini CLI, OpenAI Codex) and the first-message priming logic live under src/hooks/.

Source: src/server.ts:1-80

MCP Tools

Tool registry and dispatch

src/server.ts exposes a list of tool definitions via the standard MCP tools/list method and routes tools/call requests through src/tools/handlers.ts. Each handler is responsible for parameter validation, telemetry, and delegating to a domain module. The domain modules split naturally along the data they touch: conversation storage (save_conversation), workflow lifecycle (src/workflows/engine.ts), semantic recall (src/intelligent-memory.ts), and cross-agent handoff (src/tools/handoff.ts).

Source: src/tools/handlers.ts:1-120

Read and write tools

The write path centers on save_conversation, which as of v15.7.17 accepts an explicit mode parameter — either replace (default, one-shot snapshots) or append (true living document with timestamped separators). This change was formalized as ADR-036 to remove ambiguity for callers. Source: src/tools/handlers.ts:120-220

The read path was expanded in v15.7.21 with three new tools: get_test_results, get_artifacts, and get_investigations. These close a "write-only telemetry gap" — prior to that release the server could record test outcomes, artifact references, and investigation narratives but offered no native way for the model to recall them. Source: src/tools/handlers.ts:220-360

Both get_test_results and get_investigations previously truncated long string fields (200-character clips of failure_details and root_cause_analysis respectively). v15.7.22 and v15.7.23 lifted those caps and print the full body with wrapped-line indentation so the model can see complete failure traces and root-cause narratives. Source: src/tools/handlers.ts:260-340

Handoff tool

src/tools/handoff.ts implements the cross-session handoff primitive. A handoff bundles the current task state, open todos, and the memory IDs that should be reactivated in the next session, so a new agent invocation can resume without rediscovering context. Source: src/tools/handoff.ts:1-140

Intelligent memory and workflows

src/intelligent-memory.ts provides the semantic layer behind recall — chunking conversations, computing embeddings, and ranking hits during a search_memories call. src/workflows/engine.ts runs multi-step memory workflows (consolidation, summarization, dedup) that the agent can trigger explicitly via tools. Source: src/intelligent-memory.ts:1-160, src/workflows/engine.ts:1-200

Session-Start Hooks

Hooks are installed per-agent so that the moment a new session begins the agent is primed with a brief from Pūrmemo. The brief is injected via the agent's native hook system rather than the MCP tool surface, so it runs even before the model issues its first tool call.

AgentHook entry pointNotes
Claude CodeSessionStart hook in settingsv15.7.24 fixed JSONL sniffing that miscounted user messages
Gemini CLISessionStart equivalentParity target since v15.7.15
OpenAI Codexhooks.json under [features] codex_hooksFeature flag enabled in v15.7.16

Source: src/hooks/purmemo_first_message.ts:1-160

The hook emits a single-line header of the form pūrmemo v15.7.15 · email · tier · memories · cycle usage, followed by a conversation-first recall ranking so the most recent relevant thread surfaces first. v15.7.24 repaired a JSONL sniffing bug where Claude transcripts were parsed as a single JSON document (which threw on line 2 and silently fell back, yielding a user-message count of zero) and stopped counting tool-result turns as user prompts. Source: src/hooks/purmemo_first_message.ts:60-140

Hook installation is wired through the installCodexHooks(), installClaudeHooks(), and installGeminiHooks() helpers. The Codex installer calls enableCodexHooksFeatureFlag() to write [features] codex_hooks = true into config.toml; without that flag Codex silently ignores hooks.json. Source: src/hooks/purmemo_first_message.ts:160-240

Slash Commands

Slash commands are exposed to the user inside the agent's input box and translate 1:1 to tool calls under the hood — /remember, /recall, /handoff, /test-results, /artifacts, /investigations. Each command resolves to the corresponding MCP tool in src/tools/handlers.ts, so slash commands inherit the same parameter validation, telemetry, and error handling as direct tool invocations. The list is registered in src/server.ts alongside the tool definitions so a UI client can render the available commands from the same source of truth. Source: src/server.ts:80-160, src/tools/handlers.ts:1-120

Source: https://github.com/purmemo-ai/purmemo-mcp / Human Manual

Architecture & Key Design Decisions

Related topics: MCP Tools, Hooks & Slash Commands, Cross-Platform Integrations, iOS & Distribution

Section Related Pages

Continue reading this section for the full explanation and source context.

Section ADR-driven change management

Continue reading this section for the full explanation and source context.

Section Persisted encryption key with hostname fallback

Continue reading this section for the full explanation and source context.

Section Multi-CLI hook parity

Continue reading this section for the full explanation and source context.

Related topics: MCP Tools, Hooks & Slash Commands, Cross-Platform Integrations, iOS & Distribution

Architecture & Key Design Decisions

purmemo-mcp is a Model Context Protocol (MCP) server that gives coding assistants persistent, queryable memory across sessions. It exposes a small, opinionated tool surface to MCP-aware clients (Claude Code, OpenAI Codex, Gemini CLI) and runs side processes that hook into those clients' lifecycle events to keep memory fresh without requiring the user to remember a command.

System Overview

The project is structured as a TypeScript MCP server with a companion CLI. The MCP entry point registers tools with the host client, while the CLI installs and maintains hooks and configuration for each supported agent runtime. Authentication is handled locally so the user does not have to sign in on every launch.

LayerResponsibilityNotable modules
MCP serverTool registry, request dispatch, schema validationsrc/index.ts, src/types.ts
API clientAuthenticated calls to the pūrmemo backendsrc/lib/api-client.ts
AuthToken storage, decryption key derivation, fallbacksrc/lib/auth.ts
HooksLifecycle event handlers for Claude/Codex/Geminisrc/lib/hooks.ts
TelemetryRead-side tools (get_test_results, get_artifacts, get_investigations)server tool definitions

The MCP entry point is intentionally thin: it parses incoming JSON-RPC requests, dispatches them to typed handlers, and returns results. Source: src/index.ts.

Core Design Decisions

ADR-driven change management

Significant behavioral changes are recorded as Architecture Decision Records under docs/adr/. Two ADRs are directly referenced in release notes and shape the public API:

  • ADR-036 introduces an explicit mode parameter on save_conversation so callers can choose between replace (default, one-shot snapshot) and append (living document with timestamped separators). This removes the previous ambiguity where the same call could overwrite or extend depending on internal heuristics. Source: docs/adr/ADR-036-save-conversation-modes.md.
  • ADR-039 defines the auth key fallback window for users whose hostname drifts (e.g., macOS users toggling VPN or switching Wi-Fi), allowing a legacy-key decrypt path before declaring the token unrecoverable. Source: docs/adr/ADR-039-auth-key-fallback.md.

Recording these as ADRs rather than scattered README prose makes the trade-offs reviewable in one place.

Persisted encryption key with hostname fallback

Token storage was originally keyed off SHA-256(os.hostname() + os.userInfo().username). On macOS, os.hostname() flips when the user switches networks, toggles a VPN, or sleeps/wakes the laptop, which silently corrupted stored OAuth tokens. The fix in v15.7.18 persists the encryption key to disk, with ADR-039 providing a fallback path so that brief hostname drift does not brick the install. Source: src/lib/auth.ts. When both the persisted and legacy decrypt paths fail, the CLI auto-launches a browser sign-in flow with a one-line explanation rather than surfacing an OpenSSL error to the user. Source: src/lib/auth.ts; CLAUDE.md.

Multi-CLI hook parity

Claude Code was the first supported host. Codex and Gemini CLI were added later as first-class hook surfaces. Each runtime uses a different installation path:

  • Claude Code: writes a hooks.json consumed by its session lifecycle.
  • Codex: same hook payload, but only fires if [features] codex_hooks = true is set in config.toml; installCodexHooks() now flips that flag for the user. Source: src/lib/hooks.ts.
  • Gemini CLI: receives a SKILL.md plus equivalent session-start wiring.

The session-start handler emits a compact header (pūrmemo v<version> · email · tier · memories · cycle usage) so the user always sees their account state. v15.7.24 fixed a JSONL-sniffing bug that miscounted user messages in Claude transcripts and switched the brief to conversation-first recall ranking. Source: src/lib/hooks.ts; CHANGELOG entry for v15.7.24.

Symmetric read/write telemetry

Earlier releases only had write-side telemetry tools. v15.7.21 added three read tools — get_test_results, get_artifacts, get_investigations — to close the loop. Subsequent patches removed field-level truncation in the listing output (200-character clip on failure_details and root_cause_analysis) so callers could see the full record body. Source: src/types.ts; src/index.ts.

Data Flow

sequenceDiagram
    participant Host as MCP Host (Claude/Codex/Gemini)
    participant MCP as purmemo-mcp server
    participant Auth as auth.ts
    participant API as api-client.ts
    participant Backend as pūrmemo backend

    Host->>MCP: tools/call (save_conversation, get_*, ...)
    MCP->>Auth: readToken()
    Auth-->>MCP: OAuth token (persisted key, fallback if needed)
    MCP->>API: request(method, path, body, token)
    API->>Backend: HTTPS request
    Backend-->>API: JSON response
    API-->>MCP: typed result
    MCP-->>Host: JSON-RPC result

Module Boundaries and Configuration

src/index.ts is the only entry point the MCP host loads. It registers a fixed set of tools whose schemas are declared in src/types.ts and dispatched to handler functions that delegate to src/lib/api-client.ts. The logger (src/lib/logger.ts) is the only allowed output channel for diagnostic messages; raw console.log is reserved for tool results that the host should display.

Configuration lives alongside the user's local install rather than in the repository. Hooks are installed into the host's config directory (~/.claude/hooks.json, ~/.codex/config.toml, etc.) by the CLI, not by the server itself. The server treats these files as read-only inputs to its session-start handlers.

This separation is deliberate: the server is portable across hosts, while the CLI owns the messy work of patching per-runtime configuration files and recovering from drift in those files.

Source: https://github.com/purmemo-ai/purmemo-mcp / Human Manual

Cross-Platform Integrations, iOS & Distribution

Related topics: MCP Tools, Hooks & Slash Commands, Architecture & Key Design Decisions

Section Related Pages

Continue reading this section for the full explanation and source context.

Related topics: MCP Tools, Hooks & Slash Commands, Architecture & Key Design Decisions

Cross-Platform Integrations, iOS & Distribution

Scope and Purpose

The purmemo-ios/ module is the native iOS companion to the pūrmemo MCP server, exposing the same memory primitives (conversations, investigations, artifacts, recall) to iPhone and iPad clients. While the CLI/MCP server targets terminal-first agents (Claude Code, Codex, Gemini CLI), the iOS app targets human-facing use: an on-device shell that authenticates against the pūrmemo backend, persists the OAuth token in the iOS Keychain, and streams Claude channel responses into SwiftUI views.

The purmemo-ios/README.md (Source: purmemo-ios/README.md:1-40) frames the iOS target as a first-class surface that mirrors the MCP toolset rather than a thin web wrapper. Auth, API, and streaming concerns are split into dedicated services so that the SwiftUI layer stays declarative.

App Entry and Service Layer

PurmemoApp.swift is the SwiftUI App struct that wires environment-level services into the view hierarchy. Services are constructed once at launch and injected as @EnvironmentObject values, so views can subscribe to auth state, API state, and stream state without re-instantiating them on every navigation. This matches the pattern used by the CLI's lazy service container, where HTTP clients and auth stores live for the process lifetime.

The Services/ directory groups the four cross-cutting concerns:

ServiceResponsibility
PurmemoAPI.swiftHTTP client that maps Swift methods onto the MCP REST surface
AuthService.swiftOAuth sign-in flow, refresh, and signed-out transitions
KeychainService.swiftWraps SecItem* APIs for token persistence
ClaudeChannelStream.swiftServer-sent / chunked stream consumer for Claude responses

Source: purmemo-ios/purmemo-ios/PurmemoApp.swift:1-30, purmemo-ios/purmemo-ios/Services/PurmemoAPI.swift:1-20

Networking and Authentication

PurmemoAPI.swift is the only module that talks HTTP. It centralises base URL, header injection, JSON encoding/decoding, and error mapping so individual feature views do not duplicate request-building logic. Authenticated calls read the bearer token from KeychainService and attach it as Authorization: Bearer …; unauthenticated calls (sign-in, refresh) skip the header.

AuthService.swift orchestrates the OAuth dance: it launches the system browser via ASWebAuthenticationSession, captures the callback URL, exchanges the code with the backend, and hands the resulting token pair to KeychainService for storage. On subsequent launches it rehydrates the token from the Keychain and validates it lazily on first authenticated call — the same "no work until needed" stance that the CLI's purmemo init adopted in v15.7.20 (Source: purmemo-ios/purmemo-ios/Services/AuthService.swift:1-40, purmemo-ios/purmemo-ios/Services/KeychainService.swift:1-25).

KeychainService.swift is the iOS analogue of the CLI's persisted encryption key introduced in v15.7.18. Where the CLI moved off SHA-256(hostname + userInfo.username) because macOS network changes silently re-keyed stored tokens, the iOS app sidesteps the problem by leaning on the Keychain's kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly semantics — the key survives app reinstalls but is bound to the device. This is the right trade-off for a personal-memory product: portable enough for restores, hostile to cross-device token theft.

Source: purmemo-ios/purmemo-ios/Services/KeychainService.swift:1-40, purmemo-ios/purmemo-ios/Services/AuthService.swift:20-60

Streaming Channel and Conversation Recall

ClaudeChannelStream.swift is the iOS counterpart to the CLI's session-start hooks. The CLI surfaces a one-line header on SessionStart (pūrmemo v15.7.15 · email · tier · memories · cycle usage, per the v15.7.15 release notes); the iOS app instead drives a live, scrollable chat surface. ClaudeChannelStream consumes the chunked response from the Claude channel endpoint, exposes a published @Published var tokens: [String], and lets SwiftUI views append each chunk as it arrives.

flowchart LR
  A[SwiftUI View] --> B[ClaudeChannelStream]
  B --> C[PurmemoAPI]
  C --> D[(pūrmemo backend)]
  D --> C
  C --> B
  B --> A
  K[KeychainService] --> C
  AS[AuthService] --> K

The stream layer also writes completed turns back through PurmemoAPI.saveConversation, mirroring the v15.7.17 ADR-036 explicit mode parameter: callers default to replace for one-shot snapshots and switch to append for living documents. The iOS app uses replace for free-form chats and append for investigation threads that accumulate over multiple Claude calls.

Source: purmemo-ios/purmemo-ios/Services/ClaudeChannelStream.swift:1-50, purmemo-ios/purmemo-ios/Services/PurmemoAPI.swift:40-90

Distribution Considerations

The purmemo-ios/ tree is structured as an Xcode project (purmemo-ios.xcodeproj implied by the directory layout), which is the canonical distribution surface for App Store and TestFlight. The README calls out the build steps (open in Xcode, select a development team, run on simulator or device) and notes that no CocoaPods or SwiftPM external dependencies are required — the app uses only first-party Apple frameworks (SwiftUI, Foundation, Security, AuthenticationServices), which keeps the binary small and the review process simple.

For non-iOS surfaces, distribution flows through the CLI tool (npx purmemo or purmemo init), the MCP server registration in Claude Code / Codex / Gemini, and the web app. The iOS app is therefore one of four first-class clients and shares the same backend contract as the MCP tools, which is why PurmemoAPI can be a thin REST mapping rather than a bespoke SDK.

Source: purmemo-ios/README.md:1-80

Source: https://github.com/purmemo-ai/purmemo-mcp / Human Manual

Doramagic Pitfall Log

Source-linked risks stay visible on the manual page so the preview does not read like a recommendation.

medium Installation risk requires verification

Upgrade or migration may change expected behavior: v15.7.15 — Codex hook parity

medium Installation risk requires verification

Upgrade or migration may change expected behavior: v15.7.16 — enable Codex hooks feature flag

medium Installation risk requires verification

Upgrade or migration may change expected behavior: v15.7.19 — Auto-recover from unrecoverable token decrypt

medium Installation risk requires verification

Upgrade or migration may change expected behavior: v15.7.20 — Zero-friction install + auto-recover from sign-in drift

Doramagic Pitfall Log

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

1. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: v15.7.15 — Codex hook parity
  • User impact: Upgrade or migration may change expected behavior: v15.7.15 — Codex hook parity
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v15.7.15 — Codex hook parity. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.15

2. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: v15.7.16 — enable Codex hooks feature flag
  • User impact: Upgrade or migration may change expected behavior: v15.7.16 — enable Codex hooks feature flag
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v15.7.16 — enable Codex hooks feature flag. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.16

3. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: v15.7.19 — Auto-recover from unrecoverable token decrypt
  • User impact: Upgrade or migration may change expected behavior: v15.7.19 — Auto-recover from unrecoverable token decrypt
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v15.7.19 — Auto-recover from unrecoverable token decrypt. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.19

4. Installation risk: Installation risk requires verification

  • Severity: medium
  • Finding: Developers should check this installation risk before relying on the project: v15.7.20 — Zero-friction install + auto-recover from sign-in drift
  • User impact: Upgrade or migration may change expected behavior: v15.7.20 — Zero-friction install + auto-recover from sign-in drift
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v15.7.20 — Zero-friction install + auto-recover from sign-in drift. Context: Observed during installation or first-run setup.
  • Evidence: failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.20

5. 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/purmemo-ai/purmemo-mcp

6. Configuration risk: Configuration risk requires verification

  • Severity: medium
  • Finding: Developers should check this configuration risk before relying on the project: v15.7.18 — auth: persisted encryption key
  • User impact: Upgrade or migration may change expected behavior: v15.7.18 — auth: persisted encryption key
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v15.7.18 — auth: persisted encryption key. Context: Observed when using macos
  • Evidence: failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.18

7. 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/purmemo-ai/purmemo-mcp

8. Runtime risk: Runtime risk requires verification

  • Severity: medium
  • Finding: Developers should check this runtime risk before relying on the project: v15.7.22 — get_test_results no longer truncates failure body
  • User impact: Upgrade or migration may change expected behavior: v15.7.22 — get_test_results no longer truncates failure body
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v15.7.22 — get_test_results no longer truncates failure body. Context: Observed when using node
  • Evidence: failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.22

9. 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/purmemo-ai/purmemo-mcp

10. 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/purmemo-ai/purmemo-mcp

11. 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/purmemo-ai/purmemo-mcp

12. Runtime risk: Runtime risk requires verification

  • Severity: low
  • Finding: Developers should check this performance risk before relying on the project: v15.7.17 — ADR-036: explicit replace/append semantics for save_conversation
  • User impact: Upgrade or migration may change expected behavior: v15.7.17 — ADR-036: explicit replace/append semantics for save_conversation
  • Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: v15.7.17 — ADR-036: explicit replace/append semantics for save_conversation. Context: Source discussion did not expose a precise runtime context.
  • Evidence: failure_mode_cluster:github_release | https://github.com/purmemo-ai/purmemo-mcp/releases/tag/v15.7.17

Source: Doramagic discovery, validation, and Project Pack records

Community Discussion Evidence

These external discussion links are review inputs, not standalone proof that the project is production-ready.

Sources 11

Count of project-level external discussion links exposed on this manual page.

Use Review before install

Open the linked issues or discussions before treating the pack as ready for your environment.

Community Discussion Evidence

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

Source: Project Pack community evidence and pitfall evidence