use-universal-memory

Use Universal Memory

Purpose

Universal Memory (umem) is the repository memory and skill layer. This skill is the single UMEM guide and router: use it to load current memory context, interpret UMEM state, decide whether deeper instructions are needed, and route directly to the focused reference for the task.

Keep this as one guide-style skill. Do not split UMEM into separate skills for startup, facts, host sync, or skill lifecycle work unless the user explicitly approves that design change.

Desired Outcomes

• Agents begin repository work with current UMEM context and relevant active skills.
• Users get behavior informed by durable project facts and global preferences without host files becoming memory dumps.
• Memory mutations are deliberate, safe, scoped correctly, and synced when they should affect future host instructions.
• References are loaded only on demand, preserving Agent Skills progressive disclosure.

Data Sources

• .umem/ project storage and generated project skills.
• AGENTS.md and CLAUDE.md managed UMEM bootstrap instructions.
• CLI output from umem bootstrap and targeted read or mutation commands.
• MCP tool results when available; treat them as equivalent automation surfaces over the CLI behavior contract.
• references/ files in this skill for deeper task-specific procedures.

Mandatory Startup

At the start of a conversation or session, load UMEM context before planning, editing, investigating, reviewing, or activating another workflow:

umem bootstrap --format json

Then inspect any relevant active skill:

umem skills detail <skill-id-or-name> --format json

Prefer MCP bootstrap() when it is available; otherwise use the CLI command above. Use the CLI examples in the references as the canonical behavior contract.

Workflow And State Interpretation

• If bootstrap reports UMEM unavailable or the project uninitialized, say so explicitly and continue without external memory instead of inventing context.
• Treat data.context as active repository guidance for the current work session.
• Treat global context as cross-project user preference; do not let it override explicit project constraints or user instructions for the current task.
• Treat data.skills.list as discovery metadata. Inspect only relevant active skills with skills detail, and load deeper skill files only when the current task calls for them.
• Do not repeat the full startup sequence on every user message in the same conversation; query only the specific UMEM state needed after the initial preflight.
• Preserve relative paths in specs, docs, code, and reports.