Claude Code

Claude Code integration provides persistent memory through a direct MCP connection plus instruction-based memory rules. The current approach (v0.8.0+) relies on Claude’s judgment guided by rules in CLAUDE.md rather than automated capture hooks. No background processes, no queue files.

Two installation paths:

1. Plugin installation (recommended) — native Claude Code plugin via /plugin install
2. CLI installation — manual configuration via npx

---

Installation

Method 1: Plugin Installation (Recommended)

/plugin install @verygoodplugins/automem

This installs the plugin to ~/.claude/plugins/automem@marketplace-name/ with the following structure:

~/.claude/plugins/automem@marketplace-name/
├── .claude-plugin/
│   └── plugin.json          # Plugin metadata
├── .mcp.json                # MCP server configuration
├── commands/
│   ├── memory-health.md
│   ├── memory-recall.md
│   └── memory-store.md
├── hooks/
│   └── hooks.json           # SessionStart hook config
├── scripts/
│   └── session-start.sh     # Session initialization script
└── skills/
    └── memory-management/
        ├── SKILL.md
        └── patterns.md

The plugin registers three slash commands and configures the MCP server automatically.

Method 2: CLI Installation

Step 1: Register the MCP server

Edit ~/.claude.json to add the AutoMem server:

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_ENDPOINT": "http://127.0.0.1:8001",
        "AUTOMEM_API_KEY": "your-token-here"
      }
    }
  }
}

For local development (no API key needed):

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@verygoodplugins/mcp-automem"],
      "env": {
        "AUTOMEM_ENDPOINT": "http://127.0.0.1:8001"
      }
    }
  }
}

Step 2: Add tool permissions

Run the CLI installer to merge permissions into ~/.claude/settings.json:

npx @verygoodplugins/mcp-automem claude-code

This adds the following to permissions.allow (assuming server named "memory"):

{
  "permissions": {
    "allow": [
      "mcp__memory__store_memory",
      "mcp__memory__recall_memory",
      "mcp__memory__associate_memories",
      "mcp__memory__update_memory",
      "mcp__memory__delete_memory",
      "mcp__memory__check_database_health"
    ]
  }
}

Pre-authorizing tools prevents Claude Code from asking permission on every tool use.

Step 3: Add memory rules to CLAUDE.md

Append the memory rules template to ~/.claude/CLAUDE.md:

# The CLI installer prints the rules — append them manually, or:
npx @verygoodplugins/mcp-automem claude-code
# Then follow the instructions to append to ~/.claude/CLAUDE.md

Step 4: Restart Claude Code

claude  # Restart to pick up new MCP server and permissions

---

Tool Naming

The server name in ~/.claude.json determines the tool prefix format: mcp__<server_name>__<tool_name>.

With server named "memory":

• mcp__memory__store_memory
• mcp__memory__recall_memory
• mcp__memory__associate_memories
• mcp__memory__update_memory
• mcp__memory__delete_memory
• mcp__memory__check_database_health

Plugin installations may use a different server name (e.g., plugin_automem_memory). Use Claude Code’s tool list as the source of truth for exact names, then update the CLAUDE.md rules to match.

---

Memory Rules System

The ~/.claude/CLAUDE.md file instructs Claude when and how to use memory tools. The rules define a two-phase recall strategy:

Two-Phase Recall at Session Start

Phase 1 — Tag-only preference recall:

recall_memory(tags: ["preference"], limit: 10)

Preferences are stable knowledge that doesn’t expire. Tag-only queries return clean results without semantic noise.

Phase 2 — Semantic + time-limited recent work:

recall_memory(queries: ["current task"], time_query: "last 30 days", limit: 10)

Recent work is dynamic and time-sensitive. Semantic search finds relevant context even with different terminology.

Tip

Do not mix tag-based preference recall with semantic task recall — combining them dilutes results.

Storage Patterns by Type

Type	Importance	Use Case	Example
Preference	0.9	User preferences, explicit choices	”User prefers early returns over nested conditionals”
Decision	0.9	Architectural decisions, library choices	”Chose Redis for caching due to performance needs”
Insight	0.8	Bug root causes, key learnings	”Auth failing on null input. Root: missing validation”
Pattern	0.7	Reusable approaches, best practices	”Using early returns for validation in all API routes”
Style	0.7	Code style, formatting preferences	”Using 2-space indents with Prettier, enforced via pre-commit”
Context	0.5–0.7	General information, feature notes	”Added JWT auth with refresh token rotation”
Habit	0.6	Regular workflows, behaviors	”Run tests before committing”

Content Size Governance

Limit	Action	Purpose
Target: 150–300 chars	None	Optimal for embedding quality
Soft limit: 500 chars	Auto-summarize (backend)	Prevent degradation
Hard limit: 2000 chars	Reject immediately	Database protection

Format guideline: "Brief title. Context and details. Impact/outcome."

If more detail is needed: split into multiple atomic memories, use metadata for structured data, create associations between related memories.

Relationship Types (11 types)

Type	Use Case
LEADS_TO	Bug → Solution, Problem → Fix
REINFORCES	Supporting evidence, validation
CONTRADICTS	Conflicting approaches, alternatives
EVOLVED_INTO	Knowledge progression, iterations
INVALIDATED_BY	Outdated info → current approach
DERIVED_FROM	Source relationships, origins
RELATES_TO	General connections
PREFERS_OVER	User/team preferences
EXEMPLIFIES	Pattern examples
OCCURRED_BEFORE	Temporal sequence
PART_OF	Hierarchical structure

Association triggers:

Memory Type	Trigger	Association
User correction	Search for what’s being corrected	INVALIDATED_BY
Bug fix	Link to original bug discovery	DERIVED_FROM
Decision	Link to alternatives considered	PREFERS_OVER
Evolution	When knowledge supersedes old	EVOLVED_INTO

---

Plugin Commands

When installed via plugin, these slash commands are available:

/memory-health

Checks AutoMem service health and connectivity:

• Calls check_database_health()
• Reports FalkorDB and Qdrant connection status
• Validates AUTOMEM_ENDPOINT configuration

✓ FalkorDB: Connected
✓ Qdrant: Connected
✓ AutoMem service: Healthy

/memory-recall

Intelligent context-aware recall:

• Analyzes current working directory
• Examines recently opened files
• Executes parallel recall strategies
• Presents relevant memories with relationships

/memory-store

Store a decision, insight, or pattern:

• Prompts for memory content
• Suggests tags based on context
• Applies appropriate importance score
• Creates associations with related memories

---

Tagging Strategy

1. Always include project name
2. Add platform tag (claude-code)
3. Include current month (YYYY-MM format)
4. Add component/domain tag
5. Add memory type tag

Example: ["my-app", "claude-code", "auth", "decision", "2025-01"]

---

Migration from Hooks (Pre-v0.8.0)

If you have a pre-v0.8.0 hooks-based setup, these components were removed:

Component	Path	Purpose
Capture hooks	templates/claude-code/hooks/capture-*.sh	Automated memory capture
Queue processing	templates/claude-code/scripts/process-queue.py	Batch memory processing
Cleanup scripts	templates/claude-code/scripts/queue-cleanup.sh	Queue deduplication
Notifications	templates/claude-code/scripts/smart-notify.sh	Desktop notifications
Profile system	templates/claude-code/profiles/	Lean vs extras configs

Migration steps:

# 1. Backup existing setup
cp ~/.claude/settings.json ~/.claude/settings.json.pre-v0.8.0.bak

# 2. Remove old hooks (optional)
rm -rf ~/.claude/hooks/

# 3. Update to current setup
npx @verygoodplugins/mcp-automem claude-code

# 4. Verify tools appear
claude --list-tools | grep memory

---

Best Practices

When to use memory:

• Session start: Always recall context for project-related work
• Before decisions: Check for existing patterns and preferences
• After significant work: Store decisions, insights, patterns
• During debugging: Search for similar past issues
• User corrections: Always store style corrections

When to skip memory:

• Trivial questions about syntax
• Simple file operations
• Basic factual queries
• Already well-documented information

Good memory content:

• “Chose PostgreSQL over MongoDB. Need ACID for transactions. Impact: Data consistency guaranteed.”
• “Login failing on special chars. Root: missing sanitization. Added validator. Files: auth/login.ts”
• “Early returns for validation. Reduces nesting, improves readability. Applied in all API routes.”

Poor memory content:

• “Fixed typo” (too vague, no context)
• “Updated config” (what config? why?)
• “Changed authentication system from basic auth to JWT…” (too long, should be split)

---

Troubleshooting

Tool names not found

Symptom: mcp__memory__* tools not available.

• Check the server name in ~/.claude.json — it determines the prefix
• Plugin installations use different server names (e.g., plugin_automem_memory)
• Use Claude Code’s tool list as source of truth for exact names
• Update CLAUDE.md rules to match your actual tool names

Service unreachable

Symptom: /memory-health fails, recall_memory returns errors.

# Check service is running
curl http://127.0.0.1:8001/health

# For cloud deployments
curl -H "Authorization: Bearer $KEY" https://your-automem.example.com/health

Memories not storing

• Check AutoMem service logs for errors
• Verify AUTOMEM_API_KEY is set if using cloud deployment
• Check content size — hard limit is 2000 chars
• Ensure service has write permissions to database directories

Recall returns empty results

• Ensure memories are tagged with project name
• Try broader queries with fewer filters
• Remove time_query for older memories
• Use tag_mode: "any" instead of "all"