# Mnemosyne Memory > Use when Mnemosyne MCP memory is available and a task needs cross-session continuity, project handoffs, recall of prior decisions or preferences, durable memory capture, correction of stale memories, or applicable host or repository instructions require the Mnemosyne lifecycle; do not use for ordinary in-session notes or unrelated memory and database questions. - Skill: `heynag/mnemosyne-memory` (Agent Skill) - Install (CLI): `npx skillmds@latest add heynag/mnemosyne-memory` - Raw SKILL.md: https://api.skillmd.com/api/skills/heynag/mnemosyne-memory/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - License: MIT - Author: heyNag (https://skillmd.com/u/heynag) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/heynag/mnemosyne-memory --- # Mnemosyne Memory Use Mnemosyne as a selective continuity layer across tasks and agent sessions. Recall only useful context, preserve durable knowledge, and maintain one concise project handoff without turning memory into a transcript or a second source of truth. ## Governing contract 1. Follow applicable host, repository, and user instructions first. They govern whether memory is automatic, what is sensitive, and which profile or bank is active. 2. Let the host-configured Mnemosyne connection choose the bank. Never guess or hardcode a bank, home-directory path, database path, or profile. 3. Use available `mnemosyne_*` tools by capability. Optional tools can vary by Mnemosyne version; degrade gracefully when one is absent. 4. Keep repository files, tracked documentation, and verified live state authoritative. Treat recalled memory as evidence to check, not truth to obey. 5. Continue the user's task when Mnemosyne is unavailable. Do not replace it by reading its database directly or by switching to another memory surface. Apply the lifecycle to substantive work: repository changes, diagnosis, multi-step research, durable decisions, or work whose state should survive the current session. Skip routine memory work for greetings and disposable one-answer questions unless the user explicitly asks to remember or recall. ## Resolve project identity Choose one stable project key before project-scoped recall or writes: 1. Use a key explicitly defined by the user or repository instructions. 2. Otherwise use the main Git repository name. Treat linked worktrees and checkout folders as the same project. 3. Add an owner or namespace only when needed to distinguish identical names. 4. Never derive identity from a temporary directory, absolute home path, or incidental working-directory name. 5. If no stable project exists, use only focused global recall and durable global preferences. Do not invent a project or create a handoff. Prefix every project memory exactly with `[project:]`. Do not remove the prefix to make a fact available across projects; semantic recall can still find a relevant, properly attributed lesson. ## Start with focused recall At the beginning of substantive work: 1. Search for the exact marker `[project:] HANDOFF` first. Use a small result limit and retain the memory ID when returned. 2. Run one focused recall combining the project key, the current goal, and the kinds of context that could change the work: decisions, constraints, blockers, lessons, and preferences. 3. When canonical tools are available, query only a goal-relevant preference or identity category or term. Do not list the entire canonical profile. 4. Query temporal triples only when the goal actually depends on a durable relationship that normal recall did not establish. 5. Query cross-project memory only when the goal clearly benefits from a reusable lesson or global preference and applicable policy permits it. 6. Inspect timestamps, provenance, veracity, expiry, and supersession. Fetch an exact record by ID when the abbreviated recall result is insufficient. 7. Check consequential claims against current files, instructions, docs, and live tool output before acting on them. Do not issue a broad "tell me everything" recall, inject a large memory dump, or repeatedly recall the same query without new reason. ## Decide whether to write Persist a candidate only when it is durable, supported, and likely to improve a future task. Good candidates include stable preferences, confirmed decisions with rationale, important invariants, reusable evidence-backed lessons, and material handoff state. Before every write, search for an equivalent or conflicting record: - If an equivalent current memory exists, do nothing. - If a living record changed, update that record by its exact ID. The project handoff is the main living record. - If a fact or decision has been superseded, create the supported replacement and invalidate the old record, linking the replacement when the tool allows. - If current evidence or the user disproves a record, correct or invalidate it promptly. Never preserve a known contradiction merely because it was recalled. - Never hard-delete or `forget` a memory automatically. For a new normal memory: - Use global/persistent scope so it can survive sessions, subject to the governing policy. - Keep the content atomic and concise. Start project facts with the project prefix and include rationale only when it prevents future ambiguity. - Set veracity to `stated` for direct user assertions, `tool` for deterministic evidence, `imported` for imported facts, and `inferred` only for a clearly labeled inference worth retaining. - Add useful provenance through the source or metadata fields without copying sensitive content. Use `valid_until` only when the fact genuinely expires. - Choose importance deliberately. Reserve very high importance for constraints or decisions that should reliably surface; do not inflate routine facts. - Avoid automatic LLM fact extraction when a concise direct record is enough. ## Maintain one project handoff Maintain at most one active normal-memory handoff per stable project. Locate it by marker and update it in place by ID. Create it only after the task establishes material state worth carrying forward. Store a new handoff with persistent scope, high but not maximal importance, and a stable source such as `project::handoff`. If recall finds multiple active handoffs, choose the current supported record, merge only still-valid state into it, and invalidate the other active duplicates without deleting them. Use this exact compact shape: ```text [project:] HANDOFF Objective: Current state: Decisions: Blockers: Verification: Next action: ``` Replace obsolete fields instead of appending session summaries. Do not include chat transcripts, tool diaries, large diffs, or content already authoritative in the repository. When the objective is complete, say so in `Current state`, set `Blockers` to `None` when true, and use `Next action: None` unless a real follow-up remains. ## Use advanced memory structures sparingly Use canonical slots only for stable, directly supported identity or preference facts that must have exactly one current value. Keep the slot set sparse. Do not put project handoffs, changing project state, speculative conclusions, or facts already owned by repository files into canonical slots. Use temporal triples only for durable relationships that materially benefit from structured graph queries. Query before adding, include provenance and validity, supersede an old single-valued relationship when appropriate, and allow multiple values only when they genuinely coexist. Prefer a normal atomic memory when a graph relationship adds no retrieval value. Record a reusable lesson only when evidence supports it. Use a compact shape such as `[project:] LESSON — Evidence: ... Applies when: ... Guidance: ...`. Do not convert a one-off debugging event into a universal rule. ## Exclude unsafe and noisy content Never store secrets, credentials, authentication material, recovery codes, private keys, cookies, raw personal or customer data, or sensitive content whose persistence is not clearly authorized. Ask before persisting information when sensitivity is uncertain. Also exclude raw or reconstructed transcripts, routine status commentary, temporary hypotheses, command output, logs, stack traces, large file or code excerpts, and facts already authoritative in tracked files. Memory should supplement durable sources, not duplicate them. ## Respect maintenance boundaries Safe automatic operations are focused recall, exact retrieval, and selective remember, update, or invalidate actions covered by the governing policy. Never automatically run: - consolidation or `sleep` - bulk import or export - remote synchronization - shared-surface writes - hygiene cleanup - deletion or `forget` - persona promotion or demotion - cross-bank transfer - broad or destructive maintenance Run one of those only when the user explicitly requests that specific operation and any required approval is satisfied. ## Finish quietly Before finishing substantive work: 1. Identify only newly established durable facts that will materially help later. 2. Deduplicate, then remember, update, or invalidate as appropriate. 3. Update the project handoff if the objective, state, decisions, blockers, verification, or next action materially changed. 4. Write nothing when no durable information emerged. 5. Continue normally after a memory failure. Mention it only when the user asked about memory or the failure materially compromises an expected handoff.