XMemo for Claude
Durable project memory and cross-agent continuity for Claude.
Recall the context behind the work, preserve verified decisions and progress,
and hand projects across sessions without archiving raw conversations.
Quick start ·
Architecture ·
Memory workflow ·
Tool surface ·
Security ·
Validation
The XMemo Claude plugin combines a reusable memory workflow with a hosted
Model Context Protocol connection.
Claude continues to reason, inspect, implement, and validate from the live
workspace; XMemo carries only the durable context that should survive the
current conversation.
The plugin is published in the Anthropic Directory. The separate XMemo
connector listing is still under review; until it is listed, Claude adds the
plugin's XMemo server as a custom connector (see Quick start).
At a glance
| |
|---|
| Display name | XMemo |
| Plugin ID | xmemo |
| Skills | Nine professional workflows under /xmemo:* |
| Automation | Fail-open lifecycle checkpoint Hook (Claude Code and Cowork) |
| Version | 1.0.6 |
| Bundle | Claude Skill suite + checkpoint Hook + hosted MCP configuration |
| MCP endpoint | https://xmemo.dev/mcp |
| Authentication | OAuth 2.0 browser sign-in with Dynamic Client Registration |
| Requested scopes | memory:read memory:write |
| Tools | The Skills call 17 tools, only on the plugin's own OAuth connection; they use no other connection's credentials |
| MCP resources | None |
| Local Hook state | Bounded metadata only under CLAUDE_PLUGIN_DATA; no transcript content |
| License | MIT |
What it enables
- Focused recall — recover relevant project context, decisions, constraints,
TODOs, and verified progress before starting work.
- Durable outcomes — turn an important conversation into concise decisions,
approved plans, follow-up actions, and a restart-ready checkpoint.
- Plan and progress review — compare a proposal or another agent's report
against saved decisions and evidence.
- Working continuity — resume from the latest verified state instead of
replaying chat history.
- Automatic checkpoint guard — detect material implementation activity,
completed tasks, context compaction, and interrupted sessions, then ask Claude
to preserve one verified checkpoint at the right boundary.
- Cross-agent handoff — preserve provenance, blockers, remaining work, and
one exact next action for another compatible agent.
- User-controlled lifecycle — search, update, soft-delete, restore, and
explicitly hard-delete eligible memories.
Professional Skill suite
Each Skill has a distinct trigger and evidence contract. Claude can select one
from natural language, or the user can invoke the namespaced command directly.
| Skill | Professional workflow |
|---|
/xmemo:get-started | Connect XMemo, see what it already knows about the current work, seed the first durable memories, and optionally use XMemo in every session |
/xmemo:brainstorm | Recall constraints, generate distinct options, challenge assumptions, converge, and preserve only approved outcomes |
/xmemo:plan-project | Design evidence-gated PROJECT_PLAN.md and EXECUTION_PLAN.md artifacts from XMemo context and the live project |
/xmemo:review-plan | Review a proposal against saved decisions and return a formal verdict plus acceptance gate |
/xmemo:audit-progress | Separate verified work from partial, claimed, stale, conflicting, or blocked progress and optionally write a formal Markdown audit |
/xmemo:distill-session | Extract retrieval-ready decisions, context, TODOs, unresolved items, and checkpoints without archiving the transcript |
/xmemo:resume-work | Reconcile the latest checkpoint with current evidence and continue from one exact next action |
|
Quick start
You need an XMemo account and a browser for the OAuth sign-in. Plugin
availability depends on your Claude plan, workspace settings, and app version;
see Use plugins in Claude.
Claude app and Cowork
- Open Customize → Plugins, find XMemo in the Anthropic Directory, and
add it.
- Open the plugin's Connectors tab and select Connect next to
xmemo.
Until the XMemo connector is listed in the directory, Claude offers to add it
as a custom connector with https://xmemo.dev/mcp already filled in.
- Sign in to XMemo in the browser window and approve
memory:read and
memory:write.
- Start a new conversation and run
/xmemo:get-started, pick another Skill from
the / menu, or ask naturally.
The checkpoint Hook runs in Cowork but not in Claude chat, so in chat Claude
saves checkpoints only when a Skill or your request calls for one.
Claude Code
- Run
/plugin, find XMemo in the marketplace, and install it.
- Run
/mcp, select the XMemo server, and complete the browser sign-in for
memory:read and memory:write.
- Run
/xmemo:get-started to see what XMemo already knows about the current
project and seed its first memories.
- Invoke a focused workflow such as
/xmemo:resume-work, use
/xmemo:memory-steward for mixed memory work, or ask naturally:
Bring me up to speed on this project using XMemo. Show the latest verified
state, active decisions, open TODOs, blocker, and exact next action.
The checkpoint Hook needs Node.js available as node; the exec-form Hook
pattern works across Windows, macOS, and Linux.
Claude manages OAuth tokens outside this repository; no API key, client secret,
reviewer credential, or bearer token belongs in the package.
Local development
Load a working copy instead of the published plugin:
git clone https://github.com/yonro/xmemo-claude-plugin.git
claude --plugin-dir ./xmemo-claude-plugin
After local plugin changes, run /reload-plugins or restart Claude Code.
Versioning
Marketplace releases use semantic versions from
.claude-plugin/plugin.json. Because an explicit version pins Claude Code's
plugin cache, every published update must increment that value. Git tags and
GitHub Releases use the same version.
Every tag matching v*.*.* runs the release workflow. The workflow rejects a
tag that does not match the manifest version, reruns the official and package
validators plus Hook tests, then publishes an immutable plugin ZIP and SHA-256
checksum to the corresponding GitHub Release. Release archives are generated by
CI; local ZIP files under dist/ are disposable and must not be committed.
Architecture
The plugin has three complementary components:
| Component | Responsibility |
|---|
skills/*/SKILL.md | Nine focused professional workflows sharing one XMemo safety and routing contract |
hooks/hooks.json + scripts/checkpoint-hook.js | Detects checkpoint boundaries and interrupted work without reading or persisting transcripts |
.mcp.json | Declares the hosted XMemo endpoint and pins the minimum OAuth scopes |
Data path
- Claude loads the focused Skill whose description matches the workflow, or
memory-steward for mixed memory work and proactive recall or save decisions.
- In Claude Code and Cowork, the local lifecycle Hook records only bounded
activity metadata under
CLAUDE_PLUGIN_DATA and asks Claude to checkpoint
only at a material boundary.
- Claude connects to
https://xmemo.dev/mcp over HTTPS: Claude Code through
/mcp, the Claude app and Cowork through the plugin's Connectors tab.
- The server advertises OAuth metadata, and Claude registers its client and
runs the browser authorization.
- The Skills call 17 tools, only on the plugin's own OAuth connection; they
use no other connection's credentials.
- Each tool reads or writes only data authorized for the signed-in XMemo
account and requested scope.
- Claude reports the useful result without exposing tokens, internal traces,
or unnecessary identifiers.
The package contains no XMemo service implementation, production credentials,
private memories, deployment scripts, or internal runbooks.
Memory workflow
First run
/xmemo:get-started checks the connection, shows what XMemo already knows
about the current project, offers to save a few verified basics such as build
and test commands, and offers once to add a short ## XMemo memory section to
the project's CLAUDE.md so XMemo is used in every session. When the repository
should not commit a CLAUDE.md, it proposes the uncommitted CLAUDE.local.md
instead. Nothing is written
without confirmation, and a "don't ask again" choice can be saved to XMemo so
every device respects it.
At task start
- Recall only context that could materially change the current work, such as
prior decisions, preferences, constraints, open TODOs, or the last checkpoint.
- Prefer bounded project context or a restart checkpoint over broad history.
- Treat the live workspace and current evidence as canonical when memory is
stale or conflicts with reality.
During work
- Separate tentative ideas from confirmed decisions.
- When the user states a lasting preference or settles a decision, offer to
save it; save directly only when the user asked.
- Save durable conclusions, not verbose reasoning or raw transcripts.
- Record unresolved choices as pending decisions.
- Maintain the active objective, verified state, blocker, and next action.
- Update existing memory instead of creating near-duplicates.
Getting better with use
Claude applies saved preferences and decisions without being asked again and
says so in one line, updates a memory when the user corrects it, completes
TODOs and resolves pending decisions as work happens, and offers to clean up
duplicates or stale items it finds during recall. Because memory lives in the
XMemo service, the same context follows the user across sessions, devices,
and compatible agents.
Automatic checkpoint guard
The Hook runs in Claude Code and Cowork. It does not write a memory after every
tool call. It marks local activity and asks Claude to continue once when one of
these boundaries is reached:
- a tracked task is completed;
- context is about to be compacted;
- verified implementation work has reached a material stage;
- sustained work crosses the activity or time threshold;
- the previous session ended or failed with unsaved work.
Claude then decides from the current verified context whether update_state is
warranted. A successful update_state call from any connected XMemo server
clears the pending marker. record_event remains reserved for significant
milestones and handoffs. If XMemo is unavailable or no durable change exists,
the Hook fails open and never fabricates a save.
The Hook never opens transcript_path, does not inspect prompt, message, or tool
response content, and never persists source contents, credentials, or raw
transcripts.
When XMemo is not connected
Every Skill checks for XMemo tools before reporting a disconnection. If none are
available, Claude says that nothing was read or written and points to /mcp in
Claude Code or the plugin's Connectors tab in the Claude app and Cowork. It
never asks for credentials in the conversation.
At handoff
- Preserve what changed and what was actually verified.
- Include decisions, artifacts, constraints, remaining work, and blockers.
- Finish with one exact next action another session or agent can execute.
Tool surface
The Skills call these 17 tools, only on the plugin's own OAuth connection, and
use no other connection's credentials:
| Area | Tools |
|---|
| Identity | get_mcp_identity |
| Recall and explanation | recall, search_memory, recall_context, explain_memory, read_memory |
| Memory lifecycle | remember, update_memory, forget, restore_memory |
| Project context | get_project_context, project |
| Decisions | create_pending_decision, resolve_decision |
| Work tracking | todo, update_state, record_event |
The Skills use no other tools, MCP resources, widget UI, bulk TODO deletion, or
hidden legacy aliases.
Capabilities and boundaries
| Capability | Included | Boundary |
|---|
| Hosted XMemo MCP connection | Yes | Requires user OAuth authorization |
| Professional memory Skill suite | Yes | Nine focused workflows activate only for relevant requests |
| Proactive recall and save offers | Yes | Recall only when saved context could change the result; durable saves need a user request or confirmation |
| Automatic checkpoint guard | Yes | Claude Code and Cowork only; lifecycle metadata only; semantic writes remain Skill-governed |
| Recall and search | Yes | Limited to the signed-in account and scopes |
| Durable writes and working state | Yes | Performed only when requested by the user or active workflow |
| Project creation | Yes | Only after an explicit formal-project request |
| Project changes | Yes | Memories, decisions, document and conversation links, and settings of an authorized project; documents can be linked, not created |
| Recoverable deletion | Yes | forget is soft delete by default |
| Permanent deletion | Yes | Requires an explicit irreversible request and exact target |
| Cross-agent continuity | Yes | Other agents require their own authorized XMemo connection |
| Custom UI or widgets | No | The plugin is Skill + MCP only |
| Local memory database | No | Memory remains in the XMemo service |
| Private service code | No | This repository is intentionally reviewable |
Package contents
.claude-plugin/plugin.json Claude plugin manifest
.github/workflows/validate.yml Deterministic package validation
.mcp.json Hosted XMemo OAuth MCP connection
assets/icon.png Official XMemo icon
assets/claude-memory-flow.png Rendered README architecture diagram
assets/claude-memory-flow.svg Editable architecture diagram source
examples/workflow-prompts.md Synthetic evaluation prompts
scripts/validate-package.py Zero-dependency package validator
scripts/checkpoint-hook.js Cross-platform checkpoint lifecycle coordinator
scripts/test-checkpoint-hook.js Deterministic Hook regression tests
hooks/hooks.json Claude Code lifecycle Hook configuration
skills/get-started/SKILL.md First-run connection, seeding, and every-session setup
skills/brainstorm/SKILL.md Memory-grounded ideation and convergence
skills/plan-project/SKILL.md Project and execution-plan design
skills/review-plan/SKILL.md Formal plan review and acceptance gates
skills/audit-progress/SKILL.md Evidence-based progress audit
skills/distill-session/SKILL.md Important-session distillation
skills/resume-work/SKILL.md Deterministic recovery and continuation
skills/handoff-work/SKILL.md Cross-session and cross-agent handoff
skills/memory-steward/SKILL.md Mixed workflow, proactive memory, and lifecycle safety policy
skills/plan-project/assets/ Project and execution-plan templates
skills/plan-project/references/ Plan quality and evidence gates
skills/audit-progress/assets/ Development-progress audit template
skills/memory-steward/references/ Tool routing, connection rule, and focused playbooks
PRIVACY.md Data-flow and user-control summary
SECURITY.md Credential and review boundaries
CHANGELOG.md Release history
LICENSE MIT license
Only plugin.json lives inside .claude-plugin/. Skills, MCP configuration,
assets, examples, and public documentation remain at the plugin root.
Validation
Run the repository validator:
python scripts/validate-package.py
It verifies:
- manifest identity, display name, SemVer, and package paths;
- hosted endpoint and exact OAuth scope pin;
- the 17-tool Skill routing contract;
- the exact nine-Skill suite, frontmatter, workflow markers, templates, and referenced playbooks;
- required public documents and parseable assets;
- exact Hook lifecycle events, exec-form command safety, and no transcript/network access;
- common committed-secret patterns.
Run the deterministic Hook tests:
node scripts/test-checkpoint-hook.js
Then run Claude Code's official strict validator from the repository root:
claude plugin validate . --strict
Synthetic evaluation prompts are maintained in
examples/workflow-prompts.md.
Security and privacy
- OAuth tokens stay in Claude's credential storage.
- The repository contains no password, API key, bearer token, OAuth code,
cookie, reviewer credential, or private memory.
- The plugin pins
memory:read memory:write rather than relying on broader
discovered scopes.
- The Hook uses the official exec-form
node pattern, is fail-open, opens no
network connection, spawns no subprocess, and keeps only bounded local state.
- The Hook does not inspect or store Claude transcripts or tool responses.
- Retrieved memory is treated as context to verify, not unquestionable truth.
- Hard deletion is never inferred from ambiguous language.
- Demos and review evidence must use synthetic data.
Read the package documents:
Canonical service policies:
Release status
- Plugin: published in the Anthropic Directory.
- XMemo connector: separate listing under review.
- Nine-Skill professional workflow bundle: present.
- Seven-event checkpoint Hook and regression tests: present.
- OAuth MCP configuration: present.
- The Skills call 17 tools, only on the plugin's own OAuth connection: verified.
- MCP resources and widget UI: absent.
- Package validator and CI: present.
- Synthetic workflow prompts: present.
Agent-readable metadata
| Field | Value |
|---|
| Package repository | yonro/xmemo-claude-plugin |
| Runtime | Claude Code, Claude app, Cowork |
| Plugin ID | xmemo |
| Display name | XMemo |
| Skill commands | /xmemo:get-started, /xmemo:brainstorm, /xmemo:plan-project, /xmemo:review-plan, /xmemo:audit-progress, /xmemo:distill-session, /xmemo:resume-work, /xmemo:handoff-work, /xmemo:memory-steward |
| Role | Professional Skill suite + checkpoint Hook + hosted MCP |
| Service | https://xmemo.dev |
| MCP endpoint | https://xmemo.dev/mcp |
| Authentication | OAuth 2.0 + Dynamic Client Registration |
| Scopes | memory:read memory:write |
| Tools | Skills call 17, only on the plugin's own OAuth connection; no other connection's credentials |
| Repository | https://github.com/yonro/xmemo-claude-plugin |
| Directory state | Plugin published; connector under review |
Links
License
MIT © 2026 Yonro.
