memesh

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 temporal validity.

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 consolidate --name "entity-with-many-observations"
memesh consolidate --tag "project:myapp" --min-obs 5

Compresses observations using LLM. Requires Smart Mode configured.

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.