memoir

memoir

English | 中文

Memory lifecycle management for Claude Code and DeepSeek Harness agents.

Built-in memory answers "should I save this fact?" memoir answers "is this fact still relevant? should it grow, fade, merge, or retire?"

One repo, two install paths: a Claude Code skill, and a DeepSeek Harness bundle carrying the same spec.

Install

Claude Code

/plugin marketplace add Sevan7-Kalo10/memoir
/plugin install memoir

The SessionStart hook loads your startup files; the Stop hook reminds you to run maintenance as the session closes. Point MEMOIR_STORE at your memory directory.

DeepSeek Harness

Search for memoir in the desktop app's Plugins page. CLI:

dsh plugin --profile web add github:Sevan7-Kalo10/memoir

That registers /memoir-status. The skill itself is discovered from the filesystem, not from the package manifest (dsh.skills has no consumer in current builds), so copy SKILL.md, references/, and templates/ into a discovery root — ~/.dsh/skills/memoir/ or <project>/.dsh/skills/memoir/. A CLI-installed package can also be linked once:

ln -s "$DSH_HOME/profiles/web/node_modules/dsh-memoir" "$DSH_HOME/skills/memoir"

New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.dsh\skills\memoir" `
  -Target "$env:USERPROFILE\.dsh\profiles\web\node_modules\dsh-memoir"

Project-scoped alternative: link into <project>/.dsh/skills/memoir.

git clone https://github.com/Sevan7-Kalo10/memoir.git

Copy or symlink the repo directory to ~/.claude/skills/memoir/.

What it does

memoir splits memory into two layers by one question: will this still matter in six months?

• Hot layer (HOT-MEMORY.md, ~2000 tokens): narrative of recent events, active projects, current behavioral rules. Updated at session close. Answers "what do I need to know when I wake up?"
• Cold layer (memory/*.md): permanent insights about the user — identity, values, preferences, patterns. The criterion is not "did we discuss this?" but "does this reveal who they are?"

Every memory carries two independent axes — importance (1-5) and recency — plus a lifecycle state:

seedling → active → stable → fading → archived
               ↑                      |
               |______ restore _______|

The session-close workflow is the engine: update hot memory, scan the conversation for permanent insights, run maintenance (decay, merge proposals, archive candidates), audit gaps, back up. The agent proposes; the user confirms.

Behavioral corrections ("don't do X", "from now on, Y") become structured feedback files: incident → root cause → fix → how to apply. Always importance 5.

What v2.1 adds

• references/spec-migration.md — the v0.1.x → v2 frontmatter migration this repo had been linking to since 2.0.0 without the file existing. Field mapping plus the two gotchas that made old stores unmigratable: metadata.type is not layer, and file mtimes are bulk-write artifacts.
• Wall-clock maintenance trigger — a last-maintained date stamp beats session counting. A store can go months between sessions or have ten in a day.
• DeepSeek Harness bundle — same specs, one /memoir-status command.
• The tooling actually run — scripts/memoir_due.py (SessionStart overdue check), memoir_maintain.py (proposal list, --apply for transitions only), memoir_index.py (rebuild the MEMORY.md index), memoir_recall.py (opt-in recall hook). Python stdlib only.

Commands

On DeepSeek Harness the slash commands come from the skill text (the agent reads SKILL.md); /memoir-status is also registered natively by the bundle.

Layout

Design rationale

Why memoir is a skill and not a Python CLI, what went wrong with v0.1.x, and where the patterns actually came from: docs/design-rationale.md.