@pcircle/memesh 4.5.1 → 4.6.0

package/skills/memesh/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: memesh
-description: Use MeMesh to remember, recall, and manage AI knowledge across sessions. Triggers when the user asks to remember something, recall past decisions, forget outdated info, learn from mistakes, or analyze work patterns. Also triggers proactively when you make important decisions, fix bugs, or learn lessons worth preserving.
+description: Use MeMesh to remember, recall, and manage AI knowledge across sessions. Triggers when the user asks to remember something, recall past decisions, forget outdated info, learn from mistakes, or analyze work patterns. Also triggers when the user asks "what do you remember", "where did we leave off", or wants to catch up on a project; when a session starts and project context is needed; and proactively when you make important decisions, fix bugs, or learn lessons worth preserving.
 user-invocable: true
 ---
 
 # MeMesh — AI Memory Management
 
-Persistent memory layer for AI agents. Remember decisions, recall context, learn from mistakes — across sessions.
+Persistent memory for AI agents. The point is continuity: the next session starts where this one stopped, instead of re-spending thousands of tokens re-discovering project state — and the human never has to re-explain it.
 
 ## How to Access (auto-detect)
 
@@ -23,39 +23,74 @@ Persistent memory layer for AI agents. Remember decisions, recall context, learn
 
 All examples below use CLI. MCP tools accept the same parameters as JSON objects.
 
+## The Loop
+
+Four moments. Everything else in this file is detail.
+
+**SESSION START → load the briefing (once).**
+Call the `briefing` MCP tool or run `memesh briefing`. It returns the assembled
+work topology: where the work was left off (goal / next / blocked / done),
+decisions and direction, lessons not to repeat, what is known, recent activity.
+One call is cheaper than re-exploring the repo to reconstruct the same picture.
+Exception: under Claude Code the session-start hook has ALREADY injected this
+exact block — do not call it again (see "What's Already Automatic").
+
+**USER STATES a goal, next step, or blocker → record it immediately.**
+```bash
+memesh task --goal "Ship the work-topology injection" --next "Open the PR once CI is green"
+memesh task --blocked "Waiting on the Windows runner"
+memesh task --blocked ""      # blocker resolved — empty string clears the field
+```
+Fields: `--goal` `--next` `--blocked` `--done` (MCP tool: `task_state`).
+Record ONLY what the user actually said. This state is injected at the top of
+the next session and read as fact — a goal you guessed from which files were
+edited reaches that session with nothing to correct it. If it was not said,
+leave the field out.
+
+**SESSION END or milestone → make the task state match reality.**
+`memesh task` (no flags) shows exactly what the next session will be told.
+If "next" is now done, record what is actually next; if the blocker cleared,
+clear it.
+
+**USER ASKS "what do you remember / where were we" → briefing, then relay.**
+Run `memesh briefing` (or `--project <name>`) and answer from it. For specific
+follow-up questions, use `recall`.
+
 ## What's Already Automatic (Claude Code Plugin Hooks)
 
 If MeMesh is installed as a Claude Code plugin, these happen **without any action from you**:
 
 | Hook | When | What it does |
 |------|------|-------------|
-| **SessionStart** | Every session begins | Auto-recalls top memories for current project + surfaces lesson warnings |
-| **PreToolUse (Edit)** | Before editing files | Injects memories related to the file or project |
-| **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages: en, es, fr, pt, zh-TW) and reminds Claude to use memesh |
-| **PostToolUse (Commit)** | After `git commit` | Auto-tracks commit with diff stats as a memory entity |
+| **SessionStart** | Every session begins | Injects the briefing: task state → lessons → project memories → recent activity |
+| **PreToolUse (Edit/Write)** | Before editing files | Injects memories related to the file or project |
+| **UserPromptSubmit** | When you submit a prompt | Detects "remember this" intent (5 languages) and reminds Claude to use memesh |
+| **PostToolUse (Bash)** | After `git commit` | Auto-tracks the commit with diff stats as a memory entity |
 | **Stop** | Session ends | Auto-captures session knowledge + runs LLM failure analysis → lessons |
-| **PreCompact** | Before context compaction | Saves important knowledge before conversation history is compressed |
+| **PreCompact** | Before context compaction | Saves important knowledge before history is compressed |
 
-**You do NOT need to manually:**
-- Recall at session start (SessionStart hook does it)
-- Remember commits (PostToolUse hook does it)
-- Summarize sessions (Stop hook does it)
-- Remember when you say "記下來" / "remember this" (UserPromptSubmit hook reminds Claude)
+Because of the SessionStart hook: **in Claude Code, do NOT call `briefing` at
+session start — it is already in your context.** Call it only mid-session
+(context was compacted, or the user asks what you remember) or on hosts
+without these hooks (other MCP clients, shell-only agents). Double-injection
+spends the very tokens this system exists to save.
 
-**You DO need to manually** use the commands below for intentional knowledge management.
+Hooks capture what *happened*. You still act manually for what they cannot
+know: what the user **meant** (task state), deliberate decisions and lessons,
+and retiring outdated info.
 
-## When to Use
-
-### Proactive triggers — do these WITHOUT being asked
+## Proactive triggers — do these WITHOUT being asked
 
 | Situation | Action |
 |-----------|--------|
+| User states what they're working on / what's next / what's blocking | `memesh task --goal "…"` / `--next "…"` / `--blocked "…"` |
 | Design decision made | `memesh remember --name "auth-choice" --type decision --obs "Use OAuth 2.0 with PKCE" --tags "project:myapp"` |
 | Bug fixed | `memesh learn --error "what broke" --fix "what fixed it" --root-cause "why" --severity major` |
-| Pattern established | `memesh remember --name "validation-pattern" --type pattern --obs "Always use Zod"` |
 | Starting work on a feature | `memesh recall "feature-name" --json` |
 | User asks "what did we decide?" | `memesh recall "topic" --tag "project:myapp"` |
-| Info is outdated | `memesh forget --name "old-decision"` |
+| User asks "where did we leave off?" | `memesh briefing` → relay it |
+| Info is outdated | New memory with `--supersedes "old-name"`, or `memesh forget` |
+| Context about the user's work habits needed | `user_patterns` MCP tool (MCP/HTTP only — no CLI command) |
 
 ### When NOT to remember
 - Trivial implementation details (variable names, import paths)
@@ -69,83 +104,69 @@ If MeMesh is installed as a Claude Code plugin, these happen **without any actio
 memesh learn \
   --error "SIGSEGV when running vitest with threads" \
   --fix "Use pool: 'forks' instead of 'threads' for native modules" \
-  --root-cause "better-sqlite3 native module is not thread-safe" \
-  --prevention "Check if test framework supports native modules before choosing pool" \
+  --root-cause "the native module is not thread-safe" \
+  --prevention "Check if the test framework supports native modules before choosing pool" \
   --severity major
 ```
-This creates a `lesson_learned` entity. Lessons are surfaced as **proactive warnings** at next session start.
-
-### You need context before working
-```bash
-memesh recall "authentication" --json
-memesh recall --tag "project:myapp" --limit 10
-memesh recall --cross-project                # search across all projects
-```
-Results are ranked by relevance, recency, frequency, confidence, and recall impact.
+Creates a `lesson_learned` entity. Lessons are surfaced as **proactive warnings** at the next session start.
 
 ### A decision was just made
 ```bash
 memesh remember \
-  --name "db-choice-2026" \
-  --type decision \
+  --name "db-choice" --type decision \
+  --title "SQLite for local-first storage" \
   --obs "Use SQLite for local-first" "Rejected PostgreSQL due to deployment complexity" \
   --tags "project:myapp" "topic:database"
 ```
+Use a **stable name** (`db-choice`, not `db-choice-2026-08-16`): reusing the
+name appends to the same entity instead of scattering duplicates. `--title` is
+the human-readable headline; the name stays the machine key. If this replaces
+an older decision, add `--supersedes "old-db-choice"`.
 Types: `decision` `pattern` `lesson_learned` `bug_fix` `architecture` `convention` `feature` `best_practice` `concept` `tool` `note`
 
-### Old info needs updating
+### You need context on a specific topic
 ```bash
-memesh forget --name "old-auth-approach"                    # archive entire entity
-memesh forget --name "auth-approach" --observation "Use JWT" # remove one fact only
+memesh recall "authentication" --json
+memesh recall --tag "project:myapp" --limit 10
+memesh recall --cross-project                # search across all projects
 ```
-Archives (soft-delete). Never permanently removes.
+Query words are OR-ed and ranked by relevance — a naturally phrased question
+works; extra words narrow the ranking, not the result set.
 
-### Memories are getting verbose
+### Old info needs updating
 ```bash
-memesh dream run --project myapp   # propose digests for clusters of noisy memories
-memesh dream run --from-transcripts # OR: mine this project's Claude Code sessions for memory
-memesh dream list                  # review what it proposed
-memesh dream show <id>             # inspect one proposal in full before accepting
-memesh dream accept <id>           # apply one, or: memesh dream reject <id>
+memesh forget --name "auth-approach" --observation "Use JWT"   # remove one fact only
+memesh forget --name "old-auth-approach"                       # archive the whole entity
 ```
-Nothing changes until a proposal is accepted, and sources are archived rather
-than deleted. Requires Smart Mode configured. Works on episodic memories
-(commits, session notes) — lessons, decisions, architecture notes and pinned
-entities are never touched.
+Both are soft (recoverable) — nothing is permanently removed.
 
-`memesh consolidate` was retired: it rewrote a memory with an LLM summary and
-deleted the originals on the spot, with no review step.
+### Memories are getting verbose or stale
+Use the **memesh-review** skill: it analyzes health, finds stale, conflicting
+and redundant memories, and proposes cleanup (including `memesh dream`, the
+reviewed digest pipeline). Do not hand-compress memories yourself.
 
-### Backup or share memories
+### Backup, share, health
 ```bash
 memesh export --tag "project:myapp" > memories.json
-memesh import memories.json --merge skip    # skip | overwrite | append
-```
-
-### Check MeMesh health
-```bash
-memesh status                               # version, search level, embeddings
-memesh config list                          # current configuration
+memesh import memories.json --merge skip     # skip | overwrite | append
+memesh status                                # version, search level, embeddings
+memesh reindex                               # rebuild embeddings after provider change
 ```
 
-### Regenerate embeddings after provider change
-```bash
-memesh reindex                              # rebuild all embeddings
-memesh reindex --namespace personal         # reindex only one namespace
-memesh reindex --json                       # structured progress output
-```
-Use this when you change embedding provider (e.g., Ollama → OpenAI) or dimension. The database auto-drops old embeddings on provider change, but you need to run `reindex` to regenerate them for existing memories.
-
-## MCP-Only Features
-
-These require MCP tools or the HTTP API (`memesh serve` + REST calls):
-
-- **user_patterns** — Analyzes work patterns (schedule, tool preferences, strengths) from existing memories. Categories: `workSchedule`, `toolPreferences`, `strengths`, `focusAreas`.
-
-## Best Practices
-
-1. **Be specific** — "Use OAuth 2.0 with PKCE" not "auth stuff decided"
-2. **Tag by project** — Always include `project:<name>` tag
-3. **Use `--json`** — When you need to parse output programmatically
-4. **Learn from every bug** — Every fix is a future warning. Use `learn`, not just `remember`.
-5. **Don't over-remember** — Decisions that took > 5 minutes. Patterns worth preserving. Not trivia.
+## Memory hygiene
+
+1. **Stable names append.** Remembering under an existing name adds
+   observations and dedupes tags — it never replaces the entity. Reuse the
+   name to grow one memory; do not mint `-v2` / dated variants of it.
+2. **`supersedes` retires the loser.** When a new memory replaces an old one,
+   record it with `--supersedes <old-name>` (MCP: a relation of type
+   `supersedes`). The old entity is archived — recoverable, out of recall.
+3. **`contradicts` flags real conflicts.** When two memories cannot both be
+   true and neither is clearly wrong yet, link them with `--contradicts`
+   (MCP: relation type `contradicts`). Both surface as a conflict on every
+   recall until someone resolves it.
+4. **Prefer observation-level forgetting.** `forget --observation "…"` removes
+   one wrong fact and keeps the entity. Plain `forget` archives the whole
+   entity out of visibility — use it only when everything in it is dead.
+5. **Tag by project** (`project:<name>`) and **be specific** — "Use OAuth 2.0
+   with PKCE", not "auth stuff decided".