memesh

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.
user-invocable	true

MeMesh — AI Memory Management

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 + (opt-in) agentic-orchestration banner
PreToolUse (Edit)	Before editing files	Injects memories related to the file or project
PreToolUse (Bash)	Before bash commands	(Opt-in) Nudges Claude to dispatch high-verifiability commands as background agents
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
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 (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)

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

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

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.

A decision was just made

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_learned bug_fix architecture convention feature best_practice concept tool note

Old info needs updating

memesh forget --name "old-auth-approach"                    # archive entire entity
memesh forget --name "auth-approach" --observation "Use JWT" # remove one fact only

Archives (soft-delete). Never permanently removes.

Memories are getting verbose

memesh dream run --project myapp   # propose digests for clusters of noisy memories
memesh dream list                  # review what it proposed
memesh dream accept <id>           # apply one, or: memesh dream reject <id>

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.

memesh consolidate was retired: it rewrote a memory with an LLM summary and deleted the originals on the spot, with no review step.

Backup or share memories

memesh export --tag "project:myapp" > memories.json
memesh import memories.json --merge skip    # skip | overwrite | append

Check MeMesh health

memesh status                               # version, search level, embeddings
memesh config list                          # current configuration

Regenerate embeddings after provider change

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.