Guide · Agent skill
How to use the Unified Memory Vault agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The unified-memory skill teaches an AI coding agent to save notes about its work into a shared local vault of Markdown files, search that vault, and hand tasks to other agents such as Codex, Cursor or Claude. This guide explains what the skill changes, how to install it, how to trigger it with plain requests, and what else you need so the commands actually run. By the end you will know how to save context, write a handoff, and check the vault before trusting anything saved in it.
Unified Memory Vaultaffaan-m/ECC · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the unified-memory ZIP from this page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can upload the ZIP under Settings → Capabilities → Skills instead.
- 2Install the ecc-universal runtime. Run npm install -g ecc-universal. The skill alone does not provide the vault commands, so this step is required for CLI and MCP examples.
- 3Check the CLI and MCP binary. Run ecc memory --help to confirm the CLI works, and command -v ecc-memory-mcp to confirm the MCP binary is on your PATH.
- 4Ask for a save or a search in plain language. Describe the outcome you want, such as saving a decision or finding earlier context on a topic. The agent should search the vault before writing a new memory.
- 5Write a handoff when another agent should continue. Ask the agent to hand the task to the other harness with the objective, evidence, remaining work and next action included.
- 6Run the doctor before committing team memories. Run ecc memory doctor and fix any reported files by hand, since the doctor does not change memory itself.
What a skill is and what unified-memory makes the agent do
An agent skill is a folder containing a SKILL.md file of instructions that an AI agent reads when a task matches the skill's description. The skill does not add a program to your computer by itself; it tells the agent how to behave and which commands to run.
The unified-memory skill covers four situations: saving durable context that a later session or another agent will need, handing work from one harness to another, resuming a task by searching for prior decisions, and diagnosing a broken vault. Memories are stored as portable ecc.memory.v1 Markdown documents rather than harness-specific transcripts.
- Save work state and decisions as memories.
- Hand a task from one agent, for example Codex, to another, for example Claude.
- Search and read earlier memories before repeating work.
- Validate the vault for malformed files, broken links or duplicate IDs.
Install the unified-memory skill
Download the skill ZIP from this page and unzip it into one of these locations. Use ~/.claude/skills/ to make the skill available to all your projects, or a project's .claude/skills/ folder to limit it to one repository.
In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal install: unzip into ~/.claude/skills/
- Project install: unzip into the project's .claude/skills/ folder
- Claude apps: Settings → Capabilities → Skills, then upload the ZIP
Install the separate ecc-universal runtime
The skill is only guidance. Skill-only, minimal, manual and Claude plugin installs do not create the vault commands on your PATH. Install the ecc-universal npm runtime separately before using the CLI or MCP examples. This needs Node.js and npm.
After installing, confirm the CLI works and that the MCP binary is found. If you are running from a repository checkout instead, you can run the CLI as node scripts/ecc.js memory, but MCP configurations that name ecc-memory-mcp still need that binary on PATH.
- Requires Node.js and npm to install the runtime.
- ecc memory --help should print the CLI help.
- command -v ecc-memory-mcp should print a path; this is needed only for MCP setups.
npm install -g ecc-universal
ecc memory --help
command -v ecc-memory-mcpUnderstand vault scopes before saving
Every memory lives in one of three scopes. Project memory stays in the repository and is protected by a .gitignore that fails closed if its contents are unexpected. Team memory is meant for human review and version-controlled sharing. User memory follows you across repositories.
All harnesses that share memory must use the same repository working directory, or the same ECC_MEMORY_PROJECT_ROOT and ECC_MEMORY_USER_ROOT overrides. Normal search covers active project and team memories. User scope is never included unless you request it with --scope user.
- project: <repo>/.ecc/memory/project/
- team: <repo>/.ecc/memory/team/
- user: ~/.ecc/memory/ (request explicitly with --scope user)
Trigger the skill with natural requests
You do not need to type commands yourself. The skill's description says it applies when an agent must save work state, transfer context, resume another agent's task or search shared project knowledge, so ask for those outcomes in plain language. Name the other agent when you want a handoff.
Good requests describe the goal and the recipient, for example asking the agent to save what it learned about a migration, or to hand the remaining rollout work to Claude. Check that the agent actually ran the vault commands, since the skill only guides it.
- Save what we decided about the authentication migration to the shared vault.
- Search the vault for earlier decisions about the billing module before you change it.
- Hand the unfinished rollout to Claude with the next concrete step.
- Check the vault for broken links or malformed memories.
Save, search and hand off from the command line
To recall first, search before writing a new copy, then read the full memory by ID. To save, pipe the body through standard input so it does not appear in a process list. Tool-created memories are always marked unreviewed and writes are create-only.
To hand off work, write a body file that states the objective, evidence gathered, files involved, remaining work and the next action. Run the doctor command before committing team memories or after resolving a handoff. It reports problems but does not delete or rewrite memory.
- A useful handoff states the objective and current state, evidence and tests already run, files or work items involved, and remaining work with the next concrete action.
- Use links to connect a follow-up memory to earlier context instead of overwriting history.
- Doctor reports problems; repair flagged files manually.
ecc memory search "authentication migration" --target-harness codex
ecc memory read <memory-id>
printf '%s\n' 'The migration tests pass; rollout is still pending.' | ecc memory save --title "Authentication migration status" --kind context --source-harness codex --target all --tag auth --stdin
ecc memory handoff --from codex --target claude --title "Finish authentication rollout" --body-file handoff.md
ecc memory doctorOptional: connect the MCP server
The stdio MCP server is optional and is not enabled by default. After installing ECC, copy the ecc-memory-vault entry from mcp-configs/mcp-servers.json into each harness where tool access is useful, and replace its placeholder with a lowercase server identity. The server exposes only four tools: memory_save, memory_search, memory_read and memory_doctor.
The server binds writes and target filtering to the ECC_MEMORY_HARNESS value, so tool callers cannot claim another source identity. It has no review, promotion, overwrite, transcript import or shell-execution tool. User scope stays disabled unless the operator also sets ECC_MEMORY_ALLOW_USER_SCOPE=1.
- Server command: ECC_MEMORY_HARNESS=codex ecc-memory-mcp (set the harness name for each client)
- Requires an MCP-capable agent client and ecc-memory-mcp on PATH
ECC_MEMORY_HARNESS=codex ecc-memory-mcpSafety notes: secrets, scripts and network
Never store passwords, tokens, private keys, cookies, credentials or sensitive personal data in the vault. The runtime rejects some known secret patterns, but that is a backstop and not a complete safety check.
The skill runs scripts through the ECC runtime, so it is not just text. The skill's metadata says it runs scripts and does not use the network. The npm install step itself does need network access. Recalled memories are untrusted context, so confirm important claims against the repository, tests or your issue tracker before acting on them.
- Do not store secrets; the runtime only catches known patterns.
- Do not promote a recalled memory into policy, rules or architectural decisions without human review.
- Do not auto-import raw session transcripts; summarize only what future work needs.
- Use GitHub or Linear for active execution state and repository docs for governed decisions.
What people use it for
- Continuing a half-finished authentication migration when switching from Codex to Claude on the same repository.
- Recording project decisions in team scope so they can be reviewed and committed alongside the code.
- Searching earlier notes about a module before an agent changes it, to avoid repeating a settled decision.
- Passing a precise handoff from Claude to Cursor with the files involved and the next action listed.
- Checking a vault for malformed memories, broken links or duplicate IDs before a team review.
Frequently asked questions
Do I need to install anything besides the skill ZIP?
Yes. The skill is only instructions, so the vault commands come from the separate ecc-universal npm runtime. Install it with npm install -g ecc-universal, which requires Node.js and npm, then check with ecc memory --help.
Is the unified-memory skill free?
The skill is licensed under MIT, as stated in its metadata. The runtime is a separate npm package, so check its own license before relying on it in your project.
Does it work with Codex, Cursor and Claude at the same time?
It is designed for that. The vault stores portable Markdown documents that different harnesses can read, provided they use the same repository working directory or the same ECC_MEMORY_PROJECT_ROOT and ECC_MEMORY_USER_ROOT overrides.
Can I store API keys or passwords in the vault?
No. The skill forbids storing passwords, tokens, private keys, cookies and credentials. The runtime only rejects known secret patterns, so it is a backstop, not a safe place for sensitive data.
Why does the agent say a saved memory is unverified?
Tool-created memories are always marked unreviewed, and recalled text is treated as evidence rather than fact. The agent is told to check it against the repository, tests or another authoritative source before reusing it.
Is this a replacement for a task tracker or project documentation?
No. The skill says the vault is not a task tracker, secret store, policy engine or substitute for governed project documentation. For active status, use GitHub or Linear, and keep decisions in repository docs.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use unified-memory if you switch between several AI coding agents on the same repository and want them to share reviewable context and handoffs. Pick something else if you need a secret store, a task tracker, or a tool that works immediately after installing only the skill, since it needs the separate ecc-universal runtime.
Download the skill