@pcircle/memesh 4.9.4 → 4.10.2

package/skills/memesh/SKILL.md

@@ -28,14 +28,14 @@ All examples below use CLI. MCP tools accept the same parameters as JSON objects
 | Tool | Purpose |
 |---|---|
 | `work_package` | Prepare one bounded untrusted `digest` (calendar cluster) or `transcript` package from the newest Claude Code session under the client's single matching MCP workspace root; submit exactly one strict result or defer. Submit only stages pending human review and retains bounded redacted source turns for comparison; agents cannot apply or reject. No hidden reasoning, raw transcript, transcript path, API key, LLM, embedding, or vector data is exposed or used; hashes identify freshness and workspace scope rather than authentication. |
-| `remember` | Store knowledge as an entity with observations, tags, and relations |
+| `remember` | Store knowledge as an entity with observations, tags, and relations; `note` (free text) derives title/observations/name; `replace: true` rewrites a named memory, keeping history |
 | `recall` | Search stored knowledge; empty query lists recent memories |
 | `forget` | Archive an entity or remove one exact observation |
 | `export` | Export memories as portable JSON |
 | `import` | Import a JSON export with the required skip, append, or overwrite strategy |
 | `learn` | Record a structured lesson with error, fix, root cause, and prevention |
 | `task_state` | Read or update user-stated goal, next step, blocker, and finished work |
-| `briefing` | Assemble the current project's work topology |
+| `briefing` | Assemble the current project's work topology, closing, by default, with a capped index of its durable memories (the `briefing` setting — `minimal` / `standard` / `full` — controls how much is assembled) |
 | `user_patterns` | Analyze work schedule, tool preferences, and focus areas |
 | `improvement` | Propose an evidence-linked product improvement or read its status; only a human may accept or reject it |
 | `message` | Discover live agents in one project, then contact one exact recipient with a bounded, untrusted payload. Native size and availability failures are distinct; acceptance, discovery, polling, and fetching do not acknowledge |
@@ -98,15 +98,22 @@ Durable audit does not mean unbounded silent growth. Owners can inspect it with
 
 **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.
+work topology: this project's decisions and direction, lessons not to repeat,
+what is known, and recent activity always; where the work was left off (goal /
+next / blocked / done) too at `standard`/`full` (the `briefing` setting's
+default and above).
 One call is cheaper than re-exploring the repo to reconstruct the same picture.
-Generic briefing and SessionStart context do not report unread durable messages:
-they have no recipient identity. If you already know the exact logical
-recipient, pass `recipient` with `project` (MCP) or use
+`memesh briefing --index` returns only the index of durable memories — what is
+known here, one line each, without the ranked sections.
+Generic briefing does not report unread durable messages: it has no recipient
+identity. The session-start hook and each prompt do report them, but only when
+the session declared who it is by starting with `MEMESH_RECIPIENT=<id>`. If you
+already know the exact logical recipient, pass `recipient` with `project` (MCP) or use
 `memesh briefing --project <name> --recipient <id>`. The scoped line names the
 project and recipient and directs you to `message poll` first, then `message
-fetch` each returned `message_id`; fetching does not acknowledge. At zero
+fetch` each returned `message_id`, then record `intake` for it (the session-start
+and prompt reminders repeat until you do; fetching alone does not acknowledge).
+At zero
 unread it also says so explicitly if that exact recipient id has never been
 seen in this project at all — treat that as a probable typo in `--recipient`,
 not as an empty, healthy inbox.
@@ -120,15 +127,18 @@ 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.
+Record ONLY what the user actually said. Fresh state is injected at the top
+of the next session at `standard`/`full` (default and above) and read as
+fact — a goal you guessed from which files were edited reaches that session
+with nothing to correct it; `minimal` never shows a fresh state, but a
+stale or unknown-age one still gets a one-line flag at every level. 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.
+`memesh task` (no flags) always shows the complete stored state — not
+necessarily what the next session will be told, which depends on freshness
+and the `briefing` level. 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
@@ -149,18 +159,19 @@ With the Claude Code plugin, the first eight rows happen **without any action fr
 
 | Hook | When | What it does |
 |------|------|-------------|
-| **SessionStart** | Every session begins | Injects the briefing: task state → lessons → project memories → recent activity |
+| **SessionStart** | Every session begins | Injects the briefing when the configured level has something to show (an empty project at `minimal` injects nothing) — decisions, lessons and recent activity always; task state and the durable-memory index too at `standard`/`full` (default and above) |
 | **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 |
 | **PostToolUse (ExitPlanMode/AskUserQuestion)** | A plan is approved or you answer a question | Reminds Claude to `remember` the decision if it's worth keeping — once per tool per session |
-| **Stop** | Session ends | Auto-captures session knowledge and applies the configured update policy |
+| **Stop** | Session ends | Auto-captures session knowledge, ingests the project's Claude Code memory directory (frontmatter notes → `source:note-file` memories), shows one line when the turn made a decision-shaped move and stored no memory, and applies the configured update policy. The two writes (session capture, note-directory ingestion) stop when auto-capture is off (`memesh config set autoCapture false` / `MEMESH_AUTO_CAPTURE=false`); the advisory line still runs |
 | **PreCompact** | Before context compaction | Saves important knowledge before history is compressed |
 | **PreToolUse (Bash)** | Before a command runs | Fires accepted lesson-guards — warns when a recorded mistake is about to repeat |
 | **SessionStart/SessionEnd (Codex)** | An ordinary Codex CLI plugin session starts, resumes, or ends | Launches the detached exact-thread companion, replaces its generation on resume, and retires it after the bounded idle queue window; a matching owner-private config may override its project/principal |
 
 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
+session start — whatever the configured level has to show 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.
@@ -174,7 +185,8 @@ and retiring outdated info.
 | 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"` |
+| Design decision made | `memesh remember "Use OAuth 2.0 with PKCE for the API" --type decision --tags "project:myapp"` (or `remember({ note })` over MCP) |
+| A stored memory is wrong | `memesh remember --name "auth-choice" --obs "the corrected fact" --replace` — the memory keeps its type and the old version moves to `metadata.replaced_history` (add `--type` only to reclassify it) |
 | Bug fixed | `memesh learn --error "what broke" --fix "what fixed it" --root-cause "why" --severity major` |
 | Starting work on a feature | `memesh recall "feature-name" --json` |
 | User asks "what did we decide?" | `memesh recall "topic" --tag "project:myapp"` |
@@ -211,7 +223,13 @@ memesh remember \
 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"`.
+an older decision, add `--supersedes "old-db-choice"`. To correct it instead
+of adding to it, repeat the call with `--replace`.
+
+Quicker when the text is all you have: `memesh remember "SQLite for local-first
+storage"` (MCP: `remember({ note: "…" })`). The first line becomes the title,
+each following paragraph an observation, and the name is derived from the text,
+so repeating the same text does not create a duplicate.
 Types: `decision` `pattern` `lesson_learned` `bug_fix` `architecture` `convention` `feature` `best_practice` `concept` `tool` `note`
 
 ### You need context on a specific topic
@@ -239,15 +257,19 @@ human review. Do not hand-compress memories yourself.
 ```bash
 memesh export --tag "project:myapp" > memories.json
 memesh import memories.json --merge skip     # skip | overwrite | append
+# append/overwrite leave a memory you archived (forgot) alone; --merge append|overwrite --restore-archived brings it back
 memesh status                                # version, install channel, update state
 memesh reindex --fts                         # rebuild the local keyword index
 ```
 
 ## 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.
+1. **Stable names append — unless you ask to replace.** Remembering under an
+   existing name adds observations and dedupes tags by default. Pass
+   `replace: true` (CLI: `--replace`) to rewrite the entity's observations,
+   tags and title instead — the previous version moves to
+   `metadata.replaced_history`, not lost. Reuse the name to grow or correct
+   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.