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.
Important
This repository is a public plugin review candidate. It does not claim approval or availability in Anthropic's official plugin directory.
| Display name | XMemo |
| Plugin ID | xmemo |
| Skills | Eight professional workflows under /xmemo:* |
| Automation | Fail-open lifecycle checkpoint Hook |
| Version | 1.0.0 |
| Bundle | Claude Skill suite + checkpoint Hook + hosted MCP configuration |
| MCP endpoint | https://xmemo.dev/mcp |
| Authentication | OAuth 2.0 with Dynamic Client Registration |
| Requested scopes | memory:read memory:write |
| Tool profile | Signed Claude Code profile, exactly 16 tools |
| MCP resources | None |
| Local Hook state | Bounded metadata only under CLAUDE_PLUGIN_DATA; no transcript content |
| License | MIT |
- 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.
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: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 |
/xmemo:handoff-work |
Prepare or receive evidence-based handoffs across Claude sessions and compatible agents |
/xmemo:memory-steward |
Coordinate mixed workflows and memory lifecycle operations under the shared safety policy |
Prerequisites:
- A current Claude Code release with plugin lifecycle Hooks and
PostToolBatch. - Node.js available as
node; the official exec-form Hook pattern works across Windows, macOS, and Linux. - An XMemo account.
- A browser for the OAuth authorization flow.
Clone and launch the plugin:
git clone https://github.com/yonro/xmemo-claude-plugin.git
claude --plugin-dir ./xmemo-claude-pluginInside Claude Code:
- Run
/mcpand select XMemo. - Complete browser-based OAuth authorization for
memory:readandmemory:write. - Invoke a focused workflow such as
/xmemo:resume-work, use/xmemo:memory-stewardfor 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.
After local plugin changes, run /reload-plugins or restart Claude Code.
Claude Code manages OAuth tokens outside this repository; no API key, client
secret, reviewer credential, or bearer token belongs in the package.
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; the first stable public release is v1.0.0.
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.
The plugin has three complementary components:
| Component | Responsibility |
|---|---|
skills/*/SKILL.md |
Eight 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 |
- Claude loads the focused Skill whose description matches the workflow, or
memory-stewardfor mixed memory and lifecycle work. - The local lifecycle Hook records only bounded activity metadata under
CLAUDE_PLUGIN_DATAand asks Claude to checkpoint only at a material boundary. - Claude Code connects to
https://xmemo.dev/mcpover HTTPS. - The server advertises OAuth metadata and Claude Code performs Dynamic Client Registration plus browser authorization.
- The signed OAuth client identity selects XMemo's isolated 16-tool Claude Code profile.
- 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.
- Recall only context that could materially change the current work.
- 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.
- Separate tentative ideas from confirmed decisions.
- 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.
The Hook 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 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.
- 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.
The signed Claude Code profile exposes exactly 16 tools:
| Area | Tools |
|---|---|
| Identity | get_mcp_identity |
| Recall and explanation | recall, search_memory, recall_context, explain_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 profile exposes zero MCP resources and no widget UI. It excludes Ledger, aggregate analytics, ChatGPT widgets, bulk TODO deletion, and hidden legacy aliases. The separately submitted Claude Directory Connector has an independent 19-tool contract and is not changed by this plugin.
| Capability | Included | Boundary |
|---|---|---|
| Hosted XMemo MCP connection | Yes | Requires user OAuth authorization |
| Professional memory Skill suite | Yes | Eight focused workflows activate only for relevant requests |
| Automatic checkpoint guard | Yes | 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 |
| 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 |
| Official directory approval | No | Pending official review |
.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/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 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 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.
Run the repository validator:
python scripts/validate-package.pyIt verifies:
- manifest identity, display name, SemVer, and package paths;
- hosted endpoint and exact OAuth scope pin;
- the signed 16-tool routing contract;
- the exact eight-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.jsThen run Claude Code's official strict validator:
claude plugin validate D:\repos\xmemo-claude-plugin --strictSynthetic evaluation prompts are maintained in examples/workflow-prompts.md.
- OAuth tokens stay in Claude Code'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:writerather than relying on broader discovered scopes. - The Hook uses the official exec-form
nodepattern, 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:
This repository is prepared for public validation and future official plugin review. Release claims remain evidence-based:
- plugin manifest: present;
- eight-Skill professional workflow bundle: present;
- seven-event checkpoint Hook and regression tests: present;
- OAuth MCP configuration: present;
- isolated 16-tool server contract: verified;
- MCP resources and widget UI: absent;
- package validator and CI: present;
- synthetic workflow prompts: present;
- official directory approval: not claimed.
| Field | Value |
|---|---|
| Package repository | yonro/xmemo-claude-plugin |
| Runtime | Claude Code |
| Plugin ID | xmemo |
| Display name | XMemo |
| Skill commands | /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 |
| Tool profile | claude-plugin — 16 tools, 0 resources |
| Repository | https://github.com/yonro/xmemo-claude-plugin |
| Review state | Candidate; no official approval claim |
- Product: https://xmemo.dev/product/mcp
- Documentation: https://xmemo.dev/docs
- Support: https://xmemo.dev/support
- Privacy: https://xmemo.dev/legal/privacy
- Terms: https://xmemo.dev/legal/tos
MIT © 2026 Yonro.