purmemo

Promote a draft snapshot to canonical. Supersedes the prior canonical for this topic.

If gate blockers exist (conflicts detected, tier downgrade, or first canonical), returns them for review. Pass force: true to approve and promote anyway.

Persist a commitment-shaped artifact (PRD, ADR, spec, OKR) as a memory with intent='commitment'.

WHEN TO USE: This is the write primitive for /prd, /decide, /spec, /commit slash commands. Call after the artifact is fully drafted in the conversation. Send the COMPLETE artifact verbatim — do NOT summarize.

INSERT-only. Each call creates a new memory; supersede prior versions by recency, never overwrite. No conversationId parameter (intentional — see ADR-034).

QUERYABLE: GET /api/v1/commitments/?type=<type> returns all commitments of a given type, filterable by target_date and sorted by recency.

EXAMPLES:

• commit(title="ADR-035 - Foo - Bar - 2026-04-28", type="ADR", content="<full ADR markdown>", key_result="single-sentence chosen-option statement")
• commit(title="PRD - Email verification flow", type="PRD", content="<full PRD>", target_date="2026-05-15")

Mark a project task as done and close the Jered Loop for this session.

Sets status='done', records completion_summary, clears active_session_id. Returns the next pending task so you know what comes next before closing.

Call this BEFORE ending a session — Jered's rule: consciously close each task.

RETURNS:

• completed — the task that was just finished
• next_task — { id, sequence, title } of next pending task, or null if all done
• message — "Task complete. N tasks remaining." or "Task complete. All tasks done!"

CROSS-PLATFORM DISCOVERY: Find related conversations across ALL AI platforms.

Uses Purmemo's semantic clustering to automatically discover conversations about similar topics, regardless of which AI platform was used (ChatGPT, Claude Desktop, Gemini, etc).

WHAT THIS DOES:

• Searches for memories matching your query
• Uses AI-organized semantic clusters to find related conversations
• Groups results by topic cluster with platform indicators
• Shows conversations you may have forgotten about on other platforms

EXAMPLES: User: "Show me all conversations about the marketing project" → Finds conversations across ChatGPT, Claude, Gemini automatically

User: "What have I discussed about licensing requirements?" → Discovers related discussions from all platforms, grouped by semantic similarity

User: "Find everything about React hooks" → Returns conversations from any platform where you discussed React hooks

RESPONSE FORMAT: Shows memories grouped by semantic cluster with platform badges (ChatGPT, Claude, Gemini) Each cluster represents conversations about similar topics across all platforms

Generate a surgical context brief for a new AI session. Instead of re-explaining your context, the AI already knows where you left off.

Uses a 5-layer compaction hierarchy to maximize signal in ~2,000 tokens:

1. Intent — What you were trying to accomplish (never cut)
2. Decisions — What was decided and completed
3. Open Loops — Blockers, unresolved items, active todos
4. Context — Technologies, entities, project details
5. Content — Brief excerpts (trimmed to fit budget)

Call this at the start of a new session or when switching projects to give the AI instant context. No new data is generated — composes from your existing V2 intelligence extraction data.

Fetch open and acknowledged errors waiting for AI investigation.

Returns errors with status 'open' or 'acknowledged' — all errors needing attention. Each error includes recent_occurrences[] with per-request context (user_id, path, method) for investigation.

USAGE:

• Call this when user says "investigate errors" or "/investigate-errors"
• Errors are sorted by occurrence count (most frequent first)
• Each result includes recent_occurrences[] for per-request investigation context

QUERY PARAMETERS:

• limit: Max errors to return (default: 10)
• level_filter: Filter by level - 'all', 'critical', 'error', 'warning' (default: 'all')
• min_occurrences: Only errors with occurrence_count >= this (default: 1)

EXAMPLE: get_acknowledged_errors(limit=5, level_filter="error", min_occurrences=3) → Returns top 5 error-level issues that occurred 3+ times

RETURNS:

• acknowledged_errors: Array of error objects (open + acknowledged)
• total_count: Number of errors returned
• filters_applied: Summary of filters used

List artifacts linked to a parent conversation. Pairs with save_artifact.

List error investigation results (admin). Pairs with save_investigation_result.

Get complete details of a specific memory, including all linked parts if chunked

Get the next pending task for a project and mark it active.

Fetches the lowest-sequence pending task from the project_tasks queue, sets its status to 'active', and returns the task details plus a brief from the linked PRD memory.

NOTE: project_tasks is a structured work queue — separate from recall_memories todos. Tasks are created explicitly via the task management workflow, not auto-populated from saved conversations. If this returns "no pending tasks", the project queue is empty — use recall_memories to find work items in saved conversations instead.

Call this at the start of a work session to pick up where you left off. When done, call complete_task({ task_id, verification_summary }) to close the loop.

RETURNS:

• task.id — use this in complete_task
• task.sequence — task order number
• task.title — what to do
• task.description — how to do it
• task.acceptance_criteria — how to know it's done
• task.context_brief — first 500 chars of the PRD for context
• task.total_remaining — pending tasks left (including this one)

Retrieve the FULL content of a public or unlisted memory by ID.

WHEN TO USE:

• After recall_public returns a preview and you need the complete content
• When a user wants to read or implement from a shared community memory
• When you have a public memory ID and need the full text

This is the tool that closes the loop: recall_public finds memories, this tool retrieves them in full. No authentication required — public knowledge is free.

EXAMPLE: get_public_memory({ memory_id: "abc-123-def-456" })

RETURNS: Full memory content, observations, entities, tags, author attribution, and metadata.

Read an existing canonical snapshot into context. Fast — no LLM calls.

WHEN TO USE: When you need the current canonical state document for a topic (e.g. architecture, auth, glossary) without generating a new one.

List recent test results for a project, newest first.

Pairs with save_test_result — use this to recall past test outcomes without having to query the conversational memory layer.

USAGE:

• Latest 50 results: get_test_results({ project_name: "polymathematics" })
• Only failures: get_test_results({ project_name, passed: false })
• Custom limit: get_test_results({ project_name, limit: 10 })

RETURNS:

• results[] — each with id, test_suite, passed, failure_details, updated_at

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

Browse the memory map. With NO arguments, returns the user's PROJECT -> THEME hierarchy with member counts (the "galaxy" as text) — use this to show "what projects/topics do I have?". With cluster="<title or UUID>", OPENS that cluster and lists its member memories (a project title pulls every memory across all its themes; a theme title pulls that theme). Pair with recall_memories(cluster=...) to then semantically search inside a cluster. Read-only.

List all available Purmemo workflows — structured, memory-powered processes you can run.

WHEN TO USE THIS TOOL:

• User asks "what can you help me with?" or "what workflows do you have?"
• User wants to see available capabilities before choosing one
• User says "show me what's available" or "list workflows"

Returns the full catalog of workflows organized by category with descriptions.

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-qu

Search public memories shared by all Purmemo users. This is the community knowledge base.

WHEN TO USE:

• User asks "what have other people saved about X?"
• User wants to explore community knowledge
• User asks to search public/shared memories
• Looking for solutions others have found

DOES NOT COUNT AGAINST RECALL QUOTA — public knowledge is free.

FILTERS:

• query: Semantic search query (uses vector similarity)
• tag: Filter by tag
• platform: Filter by source platform
• sort: "recent" or "popular" (by recall count)

EXAMPLE: recall_public({ query: "MCP server testing best practices" })

RETURNS: List of public memories with author attribution, relevance scores, and recall counts.

Report a public memory for inappropriate content.

WHEN TO USE:

• User encounters spam, misleading, or inappropriate public content
• User wants to flag content that contains personal information

REASONS: spam, inappropriate, misleading, personal_info, other

After 3 reports, a memory is automatically hidden from public view pending admin review.

EXAMPLE: report_memory({ memory_id: "abc-123", reason: "spam", description: "Promotional content" })

Run a Purmemo workflow — structured, memory-powered processes for product, engineering, business, and operations tasks. Your relevant memories and identity are automatically loaded to personalize every workflow.

WHEN TO USE THIS TOOL:

• User wants to write a PRD, debug an issue, plan a sprint, review code, or any structured task
• User describes a goal but doesn't know the exact process ("I want to ship a feature")
• User asks for strategic advice, design guidance, or operational help
• User says "help me", "guide me", "walk me through", or describes a business/product/engineering need

AVAILABLE WORKFLOWS (pass the workflow name, or describe what you need): Product: prd, roadmap, story, design, feedback Strategy: ceo, growth, metrics, intel Engineering: debug, review, deploy, incident Operations: sprint Content: copy

EXAMPLES: run_workflow(workflow="prd", input="notification system for mobile app") run_workflow(workflow="debug", input="TypeError: Cannot read property 'map' of undefined in Timeline") run_workflow(input="production is down, users can't save memories") → auto-routes to incident run_workflow(input="what should I focus on this week?") → auto-routes to sprint run_workflow(input="how's the business doing?") → auto-routes to metrics

DO NOT use this tool for: simple memory recall (use recall_memories), saving conversations (use save_conversation), or finding related discussions (use discover_related_conversations).

If no specific workflow is named, the system auto-routes based on the user's intent.

Save a single artifact (research report, table, framework, spec, code) linked to a conversation memory.

WHEN TO USE: After calling save_conversation for a session that produced artifacts. Call this ONCE PER ARTIFACT with the full verbatim content — do NOT summarize or truncate.

WHY: Artifacts are the highest-value output of research sessions. Saving them separately ensures complete preservation. Each artifact becomes a first-class searchable object linked to its parent conversation.

FLOW:

1. save_conversation(title="Research Session", conversationId="my-research") → saves the conversation transcript
2. save_artifact(conversationId="my-research", title="Competitive Analysis", type="research", content="<FULL artifact>")
3. save_artifact(conversationId="my-research", title="Ranking Table", type="table", content="<FULL table>")

IMPORTANT: Send the COMPLETE artifact content in the content field. The entire point of this tool is to preserve artifacts that would otherwise be lost or summarized. Minimum 100 characters.

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 (

--- UPDATE <ISO8601> ---

) — 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.

Save AI investigation results for an error incident.

Used to store investigation results for audit trail and learning from past fixes. Call this after investigating an error and proposing/deploying a fix.

USAGE:

• Call after completing investigation and deploying fix
• Stores root cause analysis, research sources, proposed changes
• Creates audit trail for learning from past investigations

REQUEST FIELDS:

• incident_id: UUID of the error incident (from get_acknowledged_errors)
• root_cause_analysis: Your analysis of what caused the error
• similar_incidents_analyzed: Array of similar incident IDs found
• research_sources: Array of URLs used (search_web_ai, Context7 docs)
• fix_type: Type of fix - 'code_change', 'config_update', 'deployment', 'migration', 'documentation'
• proposed_changes: Object with file paths and changes made
• confidence_score: Your confidence in the fix (0.0-1.0)
• risk_level: Risk assessment - 'low', 'medium', 'high'
• test_plan: How you tested the fix
• rollback_plan: How to roll back if needed
• deployment_commit_hash: Git commit hash of the fix
• deployment_results: Object with deployment success/failure details

EXAMPLE: save_investigation_result({ incident_id: "550e8400-e29b-41d4-a716-446655440000", root_cause_analysis: "Timeout set to 5s, too short for slow networks", fix_type: "code_change", confidence_score: 0.85, risk_level: "low", deployment_commit_hash: "abc123def456" })

RETURNS:

• investigation_id: UUID of saved investigation
• incident_id: UUID of the error incident
• investigation_status: 'in_progress' or 'completed'
• deployment_status: 'not_started', 'in_progress', 'completed'
• success: true if saved successfully

Persist your synthesized snapshot content as a draft. Step 3 of the MCP snapshot path (ADR-032 Amendment A).

Call this after synthesizing from snapshot_sources(). Backend derives evidence_tier from cited_ids — not caller-controlled. Runs claim verification on your content.

Save a test result memory for a project, linked to the current active task.

Call this after running tests — pass or fail — to record the outcome. Saves a memory with category='test_result' and links it to the most recent active task. Re-running with the same test_suite name updates the existing memory (living document).

USAGE:

• After a passing test run: save_test_result({ project_name, passed: true, test_suite })
• After a failing run: save_test_result({ ..., passed: false, failure_details: "..." })

RETURNS:

• memory_id — UUID of the saved test result memory
• status — "PASSED" or "FAILED"
• linked_task — the active task this result is associated with (if any)

Set the visibility of a memory you own.

VISIBILITY LEVELS:

• private: Only you can see it (default)
• unlisted: Anyone with the direct link can view it
• public: Discoverable in the community tab by all users

WHEN TO USE:

• User says "share this memory" or "make this public"
• User wants to share knowledge with the community
• User wants to generate a shareable link

QUOTA:

• Free tier: 5 shares/month
• Pro/Teams: Unlimited

EXAMPLE: share_memory({ memory_id: "abc-123", visibility: "public" })

RETURNS: Updated visibility status and confirmation message.

Generate a state-shaped artifact for a topic from your saved memories.

WHEN TO USE: When you want a current-state document derived from saved conversations — architecture map, glossary, runbook, manifesto, project state. The slash command /snapshot calls this.

HOW IT WORKS:

1. Queries memories matching the topic (fuzzy match against tags + title), recency-weighted.
2. Builds a draft snapshot via the deterministic baseline generator (concatenates source memories — Phase 1 baseline; Gemini integration ships later).
3. Computes evidence_tier (A/B/C, deterministic) and grounded_ratio (claim verification).
4. Persists as status='draft'. Promotion to canonical requires explicit POST /api/v1/snapshots/{id}/accept per ADR-032.

INSERT-only — each call creates a new draft (versioned). Two snapshots of the same topic both exist; supersede via /accept.

EXAMPLES:

• snapshot(topic: "architecture") — gathers all memories tagged or titled with "architecture"
• snapshot(topic: "auth") — pulls everything auth-related, recency-weighted

Fetch citation bundle + conflict detection for a topic so YOU can synthesize the snapshot in-context. Step 1 of the MCP snapshot path (ADR-032 Amendment A).

WHEN TO USE: When you want to generate a snapshot from inside Claude. Returns source memories + conflicts so you synthesize, then call save_snapshot() to persist.

FLOW:

1. snapshot_sources(topic) → sources returned to you
2. You synthesize a current-state document from the sources
3. save_snapshot(topic, content, cited_ids) → persists your synthesis as a draft
4. accept_snapshot(snapshot_id) → promotes to canonical