# purmemo [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/purmemo-ai/purmemo-mcp  
**GitHub Stars:** 2  
**npm Downloads (last month):** 1280  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/purmemo

## Description
AI memory across Claude, ChatGPT, Gemini, and Cursor. Save, search, and recall context everywhere.

## Tools
Capabilities this server exposes over MCP:

- **save_conversation** — Save complete conversations as memory. REQUIRED: Send COMPLETE conversation in 'conversationContent' parameter (minimum 100 chars, should be thousands). Include EVERY message verbatim - NO summaries or partial content.

    Intelligently tracks context, extracts project details, and routes to a single memory per conversation topic.

    HOW SAVES TARGET MEMORIES:
    - conversationId is auto-generated from title slug (e.g., "MCP Tools" → "mcp-tools")
    - Same title (or explicit conversationId) → targets the existing memory
    - The 'mode' parameter controls what happens to that existing memory:
      • mode='replace' (default): overwrites the existing content with what you send
      • mode='append': concatenates new content below existing with a timestamped separator
        (\n\n--- UPDATE <ISO8601> ---\n\n) — preserves all prior history in the live row
    - The /save skill sets mode='append' automatically for living-document use
    - For one-shot snapshots, ad-hoc captures, or explicit overwrite: pass mode='replace'

    PRIOR CONTENT IS NEVER LOST:
    - Even with mode='replace', prior content is snapshotted to memory_events audit log on every update
    - Recovery from overwrites requires a one-off script (out-of-band)
    - Use mode='append' if you want history to remain visible inline in the live memory

    INTELLIGENT EXTRACTION (independent of mode):
    - Auto-extracts project context (name, component, feature being discussed)
    - Detects work iteration and status (planning/in_progress/completed/blocked)
    - Generates smart titles like "Purmemo - Timeline View - Implementation"
    - Tracks technologies, tools used, identifies relationships/dependencies

    SERVER AUTO-CHUNKING:
    - Large conversations (>15K chars) automatically split into linked chunks
    - Small conversations (<15K chars) saved directly as single memory
    - You always send complete content — server handles chunking
    - APPEND + CHUNKING: append mode works only for content <15K chars. Saves >15K
      with mode='append' are rejected with a clear error — appending to chunked
      storage would double each chunk's content on re-save. For long-running living
      docs, send only the new delta since the last save (keep it <15K) or use
      mode='replace' for full re-saves.
    - KNOWN CAVEAT: a doc that is saved small (single memory) and later grows past 15K
      transitions to chunked storage at a new conversation_id space — the original
      single memory becomes orphaned. Tracked under ADR-038 (uniform namespace).

    EXAMPLES:
    User: "Save progress" via /save skill
    → /save sets mode='append'; new content is appended below prior content

    User: "Save this snapshot" (one-shot capture)
    → mode='replace' default; current content overwrites any existing memory at this title

    User: "Save as conversation react-hooks-guide" with explicit append
    → save_conversation(conversationId="react-hooks-guide", mode="append")
    → Appends to existing memory at that ID (or creates if new)

    WHAT TO INCLUDE (COMPLETE CONVERSATION REQUIRED):
    - EVERY user message (verbatim, not paraphrased)
    - EVERY assistant response (complete, not summarized)
    - ALL code blocks with full syntax
    - ALL artifacts with complete content (not just titles/descriptions)
    - ALL file paths, URLs, and references mentioned
    - ALL system messages and tool outputs
    - EXACT conversation flow and context
    - Minimum 500 characters expected - should be THOUSANDS of characters

    FORMAT REQUIRED:
    === CONVERSATION START ===
    [timestamp] USER: [complete user message 1]
    [timestamp] ASSISTANT: [complete assistant response 1]
    [timestamp] USER: [complete user message 2]
    [timestamp] ASSISTANT: [complete assistant response 2]
    ... [continue for ALL exchanges]
    === ARTIFACTS ===
    [Include ALL artifacts with full content]
    === CODE BLOCKS ===
    [Include ALL code with syntax highlighting]
    === END ===

    IMPORTANT: Do NOT send just "save this conversation" or summaries. If you send less than 500 chars, you're doing it wrong. Include the COMPLETE conversation with all details.

    ARTIFACT PRESERVATION (ADR-025):
    If this conversation produced artifacts (research reports, tables, frameworks, specs, design documents),
    save them SEPARATELY using save_artifact after this call.
    Flow: save_conversation first, then save_artifact for each artifact.
    This ensures artifacts are preserved in full — do not try to embed large artifacts in conversationContent.
- **recall_memories** — Search and retrieve saved memories with intelligent semantic ranking.

🎯 BASIC SEARCH:
  recall_memories(query="authentication")
  → Returns all memories about authentication, ranked by semantic relevance

🔍 FILTERED SEARCH (Phase 2 Knowledge Graph Intelligence):
  Use filters when you need PRECISION over semantic similarity:

  ✓ entity="name" - Find memories mentioning specific people/projects/technologies
    Example: entity="purmemo" → Only memories discussing purmemo

  ✓ has_observations=true - Find substantial, fact-dense conversations
    Example: has_observations=true → Only high-quality technical discussions

  ✓ initiative="project" - Scope to specific initiatives/goals
    Example: initiative="Q1 OKRs" → Only Q1-related memories

  ✓ intent="type" - Filter by conversation purpose
    Options: decision, learning, question, blocker
    Example: intent="blocker" → Only conversations about blockers

💡 WHEN TO FILTER:
  - Use entity when user asks about specific person/project by name
  - Use has_observations for "detailed" or "substantial" requests
  - Use initiative/stakeholder for project-specific searches
  - Use intent when user asks for decisions, learnings, or blockers

📝 COMBINED EXAMPLES:
  recall_memories(query="auth", entity="purmemo", has_observations=true)
  → Find detailed technical discussions about purmemo authentication

  recall_memories(query="blockers", intent="blocker", stakeholder="Engineering")
  → Find engineering team blockers
- **what_changed** — TIMELINE OF A THING: what facts about an entity (a project, machine, person, product) were TRUE and then REPLACED by newer facts, with dates — plus any open contradictions. Served by the purmemo-next ledger, which knows when a fact became true and when it stopped; plain search cannot answer this.

WHEN TO USE: "what changed about X", "what used to be true about X", "when did X move/switch/get renamed", "is this fact still current", or before relying on an older memory about X.

EXAMPLES:
  what_changed({ entity: "purmemo-next" }) → e.g. "2026-08-10 [hosting]: database stayed on Supabase → now: migrated to the Mac mini"
  what_changed({ entity: "clo-mini", limit: 20 })

Returns: current-fact count, superseded facts newest-first with what replaced each, open contradictions, and the entity id. Read-only.
- **get_memory_details** — Get complete details of a specific memory, including all linked parts if chunked
- **get_user_context** — Get the current user's cognitive identity and active session context.

Call this at the START of a conversation to understand who you're talking to —
their role, expertise, current project, and recent memory themes.

This is the core of Purmemo's identity layer: once set in the dashboard,
your identity travels silently to every AI session so you're never explaining
yourself from scratch again.

WHAT IT RETURNS:
- identity: role, expertise areas, primary domain, work style, preferred tools
- current_session: what the user is working on right now (project, focus)
- memory_summary: 2-3 sentence synthesis of the user's most recent memory themes

WHEN TO CALL:
- At the start of every new session (add to Claude system prompt)
- When user says "load my context" or "what do you know about me?"
- Before making recommendations that depend on knowing the user's background

EXAMPLE USAGE:
→ User starts new Claude session
→ Claude calls get_user_context automatically
→ Response: { role: "founder", expertise: ["product", "fullstack"],
              project: "purmemo", focus: "identity layer",
              memory_summary: "Chris has been building Purmemo's..." }
→ Claude responds with full context already loaded — no re-explaining needed

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "purmemo": {
    "command": "npx",
    "args": ["-y","purmemo-mcp@latest"],
    "env": {
      "PURMEMO_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `PURMEMO_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What purmemo does

purmemo provides shared memory for AI-assisted work. Conversations can be saved and later searched using natural-language topics, while user context such as a role, projects, or technology stack can be loaded at the start of a session. The service also reports how information about a person, project, or other subject changed over time.

The connector is designed for use across supported MCP clients, so memories are available beyond a single conversation or application. A dashboard at app.purmemo.ai can be used to view and manage stored memories. The platform offers a free plan with 50 recalls per month and unlimited saves, plus a paid plan with unlimited recalls and saves.

## How it works

The server can run locally through the `purmemo-mcp` npm package or connect through purmemo's hosted streamable HTTP endpoint. Local operation authenticates with a purmemo API key; the hosted Claude Desktop configuration uses OAuth during first use. The installation script can install Node.js when needed, configure the `purmemo` command, and guide sign-in through a browser.

Five tools are enabled by default: saving a conversation, recalling memories, retrieving memory details, checking what changed, and loading user context. The package also supports slash-command-style workflows such as `/save`, `/recall <topic>`, and `/context` when used through a compatible client experience.

## Setup and configuration

For macOS or Linux, run the install script with `curl -fsSL https://app.purmemo.ai/install | sh`. Windows users can run the PowerShell installer with `irm https://app.purmemo.ai/install.ps1 | iex`. Then run `purmemo`, complete browser sign-in, and restart Claude Desktop or Claude Code.

With Node.js already installed, install the package globally using `npm install -g purmemo-mcp && purmemo`, or initialize it once with `npx purmemo-mcp@latest init`.

Claude Desktop can use the hosted endpoint `https://mcp.purmemo.ai/mcp/messages` with the `streamable-http` transport. For local configurations, run `npx -y purmemo-mcp` and provide `PURMEMO_API_KEY`. The README includes equivalent local configuration examples for Cursor, Windsurf, and Zed.

Optional flags extend the exposed tool set. `PURMEMO_SESSIONS_BETA=1` adds `search_past_sessions`, which searches raw transcripts through the configured purmemo-next service. `PURMEMO_ADMIN=1` adds investigation and acknowledged-error tools. `PURMEMO_LEGACY_TOOLS=1` exposes paused legacy tools that respond with replacement guidance.

## Tools and capabilities

The default MCP tool set includes:

- `save_conversation` for storing a conversation.
- `recall_memories` for searching saved memories.
- `get_memory_details` for retrieving a specific memory.
- `what_changed` for viewing dated changes to a subject.
- `get_user_context` for loading identity and current-work context.

The sessions beta adds `search_past_sessions` for transcript searches. Admin mode adds `get_acknowledged_errors`, `save_investigation_result`, and `get_investigations`. Legacy mode exposes paused tools such as artifact, snapshot, workflow, sharing, task, and test-result operations; those tools indicate what to use instead.

The MCP connector code is MIT licensed, while the purmemo platform, API, and backend are proprietary.

_Full upstream README: https://allmcps.com/mcp/purmemo/readme_