universal-memory

A vendor-agnostic cognitive persistence layer for AI agents. Eliminate the "repetition tax" by transporting your context, preferences, guidelines, and history seamlessly across sessions, IDEs, and LLM models.

To see the core idea visually, check out theExcalidraw designor the proposal structure:

Encapsulates complex, repetitive procedural instructions into formal Agent Skills (conforming to theagentskills.iostandard), complete with structured directories containingSKILL.mdinstructions, helperscripts/, and documentationreferences/.

[!WARNING]uvxis best for quick trials. For ongoing use, install Universal Memory as a persistent tool soumemis always available and can fully manage long-lived global memories and synced agent skills:

umem updatedoes not upgrade the Python package from PyPI. It performs local, offline maintenance for the current.umemworkspace, such as schema migrations, benchmark refreshes, and skill synchronization.

To upgrade the installedumemexecutable, use the package manager that installed it:

# If installed with uv tool uv tool upgrade universal-memory # If installed with pipx pipx upgrade universal-memory # If installed with pip python -m pip install --upgrade universal-memory # If running temporarily with uvx uvx --refresh --from universal-memory umem --version

Upgrading the executable does not silently mutate existing projects. The next time you work in an initialized project, reconcile it locally:

umem update --check umem update umem update --skills umem connect umem doctor

You do not need to runumem initagain. Local maintenance creates snapshots and audit records before UMEM-owned writes. Existing.umem/skills/use-universal-memory/trees and customized managed files are preserved; if both legacy and canonical Universal Memory skill roots exist, UMEM stops for an explicit migration decision instead of merging or deleting either tree.

Universal Memory detects the agents already used in the workspace, presents one combined confirmation, configures the best available project integration, and verifies that the agent can read project context. You do not need to choose an integration mechanism or know which instruction files it uses.

When a compatible agent needs the portable Agent Skill, UMEM discloses any network use and external project-scoped copy before confirmation, disables anonymous installer telemetry, and treats a missing prerequisite or failed installation as recoverable instead of blocking initialization.

Explicit runtime selection remains available for automation and unusual setups, but it is not required for the normal path.

UMEM resolves the detected agent's project skill directory from a reviewed catalog pinned toskills@1.5.20, runs one project-scoped installation, and validates the complete installed skill tree plus a realumem contextread. It does not install into a second project and copy the result back.

The command orchestrated by UMEM inv0.5.1is equivalent to:

DISABLE_TELEMETRY=1 npx --yes skills@1.5.20 add https://github.com/YanAmorelli/universal-memory/tree/v0.5.1/skills/universal-memory --skill universal-memory --agent pi --copy -y

Herepiis an example; UMEM supplies the detected agent ID. Node.js andnpxare optional prerequisites for this external bridge. When either is unavailable, initialization remains usable and UMEM reports a managed or manual fallback. Unknown agent IDs never executenpx.

2. Save your first preferences and facts

Tellumemwhat to keep in mind. You can target either the project scope (this folder) or the global scope (across all projects):

# Save a global preference umem remember --scope global "Yan is a solutions architect specializing in AI applications" # Save a project-specific constraint umem remember --scope project "Always use Tomllib instead of PyYAML for configuration files" --tag config

Verify the consolidated context summary generated by combining short-term facts, rules, and global preferences:

If a skill already exists, choose the safest adoption path first. Useadoptfor an existing.umem/skills/<slug>directory; useimportfor native runtime directories such as.agents/skills/<slug>and sync it back out to configured runtimes:

umem skills adopt .umem/skills/review-protocol --scope project umem skills import .agents/skills/review-protocol --scope project --sync umem skills detail review-protocol

If you are starting from scratch, draft and publish it without native side effects:

umem skills draft create \ --name "Review Protocol" \ --description "Reusable review workflow" \ --trigger "when reviewing code" umem skills draft validate review-protocol umem skills publish review-protocol --format summary

For a one-step workflow, create the canonical skill. It is canonical-only by default; request sync explicitly when native runtime targets should be written:

umem skills create \ --name "Review Protocol" \ --description "Reusable review workflow" \ --trigger "when reviewing code" \ --format summary umem skills sync review-protocol --check-gitignore --format summary

After editing.umem/skills/review-protocol/SKILL.md, refresh one runtime skill with:

UMEM deliberately separates native ownership from portable compatibility:

The maintained and named integration surfaces are:

An agent appearing in the externalskillscatalog does not make it Tier 1. Tier 1 is intentionally small and requires a maintained adapter, release evidence, and repeatable host-specific validation. See theGetting Started guidefor legacy-project behavior and the portable installation flow.

{ "mcpServers": { "universal-memory": { "command": "uvx", "args": [ "--from", "universal-memory", "umem-mcp" ] } } }

If you installed Universal Memory withuv tool install universal-memoryorpipx install universal-memory, use the stable entrypoint:

{ "mcpServers": { "universal-memory": { "command": "umem-mcp", "args": [] } } }

uvx --from universal-memory umem doctor uvx --from universal-memory umem-mcp --help

For GUI-launched MCP hosts, use the absolute path touvxif the host does not inherit your shellPATH.

- API Secret Scanner:umempasses all incoming facts through a passive scanner to block API keys, tokens, or credentials from being stored in your persistent cognitive base.
- Snapshots & Rollbacks:Every automated update to your config files (AGENTS.md,CLAUDE.md) is preceded by a snapshot backup. You can rollback anytime:

# View audit logs umem audit list --scope project # Revert last automated modification umem rollback --scope project

You can draft, create, adopt, import, validate, maintain, and sync specialized behaviors:

# List all active skills umem skills list # Inspect one skill umem skills detail review-protocol # Draft, validate, and publish without native runtime writes umem skills draft create --name "Review Protocol" --description "Reusable review workflow" umem skills draft validate review-protocol umem skills publish review-protocol # Create a new canonical skill and explicitly sync native targets umem skills create --name "Review Protocol" --description "Reusable review workflow" --sync # Adopt existing canonical work umem skills adopt .umem/skills/review-protocol --scope project # Import an existing native skill and distribute complete runtime copies umem skills import .agents/skills/review-protocol --scope project --sync # Validate and maintain canonical skills umem skills validate review-protocol umem skills canonical update review-protocol --file .umem/skills/review-protocol/SKILL.md umem skills rename review-protocol --slug review-checklist umem skills cleanup review-checklist --targets --format summary umem skills cleanup review-checklist --targets --apply umem skills repair --remove-orphan-targets --format summary # Synchronize one canonical skill into active native runtime folders umem skills sync review-protocol --check-gitignore --format summary # Synchronize all active canonical skills during maintenance umem update --skills # Track and review recurring workflow candidates umem skills track --name "Review Protocol" --description "Recurring review workflow" umem skills recommend --scope project umem skills propose <latent-skill-id> --decision yes umem skills promote <recommendation-id> --yes umem skills generate <latent-skill-id> --yes

Distributed under the Apache License 2.0. SeeLICENSEandNOTICEfor more information.

Shared memory layer for AI coding agents with dream pipeline distillation, session grounding, and multi-instance coherence.