@pcircle/memesh 3.2.1 → 4.0.1

package/skills/memesh/SKILL.md

@@ -1,73 +1,131 @@
 ---
 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, or manage their memory. 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 proactively when you make important decisions, fix bugs, or learn lessons worth preserving.
 user-invocable: true
 ---
 
 # MeMesh — AI Memory Management
 
-You have access to MeMesh, a persistent memory layer with 6 tools. Use them to remember important knowledge across sessions.
-
-## When to Use (Proactive)
-
-**Remember automatically when:**
-- A design decision is made ("let's use OAuth" → remember it)
-- A bug is fixed (root cause + fix → remember as lesson)
-- A pattern is established ("we always use Zod for validation" → remember as pattern)
-- Architecture changes ("moved from monolith to microservices" → remember)
-- The user explicitly says "remember this" or "don't forget"
-
-**Recall automatically when:**
-- Starting work on a feature that might have prior decisions
-- The user asks "what did we decide about X?"
-- You need context about a project's conventions
-
-**Forget when:**
-- A decision is superseded by a new one (use `supersedes` relation)
-- The user says "forget about X" or "that's outdated"
-
-## Tools Reference
-
-### remember
-```json
-{
-  "name": "auth-decision",
-  "type": "decision",
-  "observations": ["Use OAuth 2.0 with PKCE for authentication"],
-  "tags": ["project:myapp", "topic:auth"],
-  "relations": [{"to": "old-auth", "type": "supersedes"}]
-}
+Persistent memory layer for AI agents. Remember decisions, recall context, learn from mistakes — across sessions.
+
+## How to Access (auto-detect)
+
+```
+1. MCP tools available? (remember, recall, forget, learn in your tool list)
+   → YES: use MCP tools directly (fastest, structured I/O)
+   → NO: continue to step 2
+
+2. CLI available? Run: memesh status
+   → Works: use CLI commands below
+   → "command not found": Run: npx @pcircle/memesh status
+   → Works: use npx @pcircle/memesh <command> for all commands below
+```
+
+All examples below use CLI. MCP tools accept the same parameters as JSON objects.
+
+## 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 |
+| **PostToolUse** | After `git commit` | Auto-tracks 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 |
+
+**You do NOT need to manually:**
+- Recall at session start (hook does it)
+- Remember commits (hook does it)
+- Summarize sessions (hook does it)
+
+**You DO need to manually** use the commands below for intentional knowledge management.
+
+## When to Use
+
+### Proactive triggers — do these WITHOUT being asked
+
+| Situation | Action |
+|-----------|--------|
+| 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"` |
+
+### When NOT to remember
+- Trivial implementation details (variable names, import paths)
+- Anything that took < 5 minutes to decide
+- Information already in the codebase (comments, README, config)
+
+## Common Scenarios
+
+### You just fixed a bug
+```bash
+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" \
+  --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 temporal validity.
+
+### A decision was just made
+```bash
+memesh remember \
+  --name "db-choice-2026" \
+  --type decision \
+  --obs "Use SQLite for local-first" "Rejected PostgreSQL due to deployment complexity" \
+  --tags "project:myapp" "topic:database"
 ```
-Types: `decision`, `pattern`, `lesson`, `bug_fix`, `architecture`, `convention`
+Types: `decision` `pattern` `lesson_learned` `bug_fix` `architecture` `convention` `feature` `best_practice` `concept` `tool` `note`
 
-### recall
-```json
-{"query": "authentication", "tag": "project:myapp", "limit": 10}
+### Old info needs updating
+```bash
+memesh forget --name "old-auth-approach"                    # archive entire entity
+memesh forget --name "auth-approach" --observation "Use JWT" # remove one fact only
 ```
-Omit query to list recent memories. Results are ranked by relevance, recency, and access frequency.
+Archives (soft-delete). Never permanently removes.
 
-### forget
-```json
-{"name": "outdated-design"}
+### Memories are getting verbose
+```bash
+memesh consolidate --name "entity-with-many-observations"
+memesh consolidate --tag "project:myapp" --min-obs 5
 ```
-Archives the entity (soft-delete). Add `"observation": "specific text"` to remove just one fact.
+Compresses observations using LLM. Requires Smart Mode configured.
 
-### consolidate
-```json
-{"name": "auth-history", "min_observations": 5}
+### Backup or share memories
+```bash
+memesh export --tag "project:myapp" > memories.json
+memesh import memories.json --merge skip    # skip | overwrite | append
 ```
-Compresses verbose memories using LLM. Requires Smart Mode configured.
 
-### export / import
-```json
-{"tag": "project:myapp"}
+### Check MeMesh health
+```bash
+memesh status                               # version, search level, embeddings
+memesh config list                          # current configuration
 ```
-Export memories as JSON for sharing. Import with merge strategies: `skip`, `overwrite`, `append`.
+
+## 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 relations** — Link related decisions with `related-to`, replace old ones with `supersedes`
-4. **Type correctly** — Use the right type (decision/pattern/lesson) for better search
-5. **Don't over-remember** — Skip trivial things. Remember decisions that took > 5 minutes to make.
+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.

package/skills/memesh-review/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: memesh-review
-description: Review and clean up the MeMesh memory database. Find stale, contradicting, or redundant memories and suggest cleanup actions. Use when asked to "review memories", "clean up knowledge", or "what's in my memory".
+description: Review and optimize the MeMesh memory database. Analyzes health score, finds stale/conflicting/redundant memories, shows work patterns, and suggests cleanup actions. Use when asked to "review memories", "check memory health", "clean up knowledge", or "what's in my memory".
 user-invocable: true
 ---
 
@@ -8,47 +8,90 @@ user-invocable: true
 
 Review the memory database and provide actionable cleanup recommendations.
 
+## How to Access
+
+Use CLI (works everywhere) or MCP tools (if available). See the `memesh` skill for auto-detect instructions.
+
 ## Process
 
-1. **Recall recent memories** — use `recall` with no query to see what's stored
-2. **Check for staleness** — identify memories not accessed in 30+ days
-3. **Check for conflicts** — look for `contradicts` relations or opposing observations
-4. **Check for verbosity** — entities with 5+ observations that could be consolidated
-5. **Report findings** with specific actions
+### Step 1: Gather data
+
+```bash
+# Get system health
+memesh status
+
+# Get all recent memories (structured output for analysis)
+memesh recall --limit 50 --json
 
-## Steps
+# Get memories by type for quality analysis
+memesh recall --tag "type:decision" --json
+memesh recall --tag "type:lesson_learned" --json
+memesh recall --tag "type:session_keypoint" --json
+```
 
-### Step 1: Load overview
+If MCP `user_patterns` tool is available, also run it for work pattern analysis:
 ```json
-recall: {"limit": 50}
+user_patterns: {}
 ```
 
 ### Step 2: Analyze and report
 
-Present findings in this format:
+From the recalled data, compute and present:
 
-```
-## Memory Review
+```markdown
+## Memory Health Report
+
+### Overview
+- Total entities: N
+- Last 30 days active: N (N%)
+- Knowledge types: N decisions, N patterns, N lessons, N auto-tracked
+
+### Health Score: N/100
+- Activity: N% (accessed in last 30 days)
+- Quality: N% (high confidence, well-tagged)
+- Freshness: N% (new this week)
+- Self-Improvement: N% (lessons learned ratio)
 
-### Summary
-- Total memories recalled: N
-- Active: N | Archived: N
+### Quality Issues Found
 
-### Stale (not accessed in 30+ days)
-- "entity-name" — last observation: "..." — Suggest: archive or keep?
+**Stale (not accessed 30+ days, low confidence)**
+- "entity-name" — confidence: N% — Suggest: archive?
 
-### Could be consolidated (5+ observations)
-- "entity-name" (8 observations) — Suggest: run consolidate
+**Verbose (5+ observations, needs consolidation)**
+- "entity-name" (N observations) — Suggest: `memesh consolidate --name "entity-name"`
 
-### Potential conflicts
-- "use-jwt" vs "no-jwt" — contradicting auth decisions
+**Potential conflicts**
+- "entity-A" vs "entity-B" — contradicting decisions
 
-### Recommended actions
-1. Archive "old-design" (superseded by "new-design")
-2. Consolidate "auth-history" (12 observations → ~3)
-3. Review conflict between "X" and "Y"
+**Noise ratio**
+- N% auto-tracked (session_keypoint, commit) vs N% intentional knowledge
+- If noise > 80%: recommend more deliberate `memesh remember` usage
+
+### Recommended Actions
+1. `memesh forget --name "old-design"` (superseded)
+2. `memesh consolidate --name "auth-history"` (12 obs → ~3)
+3. `memesh remember ...` (knowledge gap in [area])
 ```
 
 ### Step 3: Execute approved actions
 
-After presenting the report, ask the user which actions to execute. Then use `forget`, `consolidate`, or `remember` with `supersedes` accordingly.
+Present the report first. Ask which actions to execute. Then run the commands:
+
+```bash
+memesh forget --name "outdated-entity"
+memesh consolidate --name "verbose-entity"
+memesh remember --name "missing-knowledge" --type decision --obs "..."
+```
+
+### Step 4: Verify
+
+```bash
+memesh recall --limit 5 --json    # confirm changes took effect
+```
+
+## Tips
+
+- Run every 1-2 weeks to keep memory healthy
+- Health score < 50 → too many stale or low-quality memories
+- Noise > 80% → encourage deliberate `memesh remember` for decisions
+- Dashboard available at: http://localhost:3737/dashboard (run `memesh serve` first)