Migration Guide: claude-memory-plugin → claude-code-memory-plugin

This guide helps you migrate from the legacy claude-memory-plugin to the new claude-code-memory-plugin.

Key Differences

Why the New Model is Better

1. Incremental Capture = Crash-Resilient: The old approach batches all turns until SessionEnd. If Claude crashes or the user kills the session, those memories are lost. The new plugin extracts on every Stop, so each turn is independently persisted.

2. Transparent Auto-Recall: No skill invocation needed — memories are automatically injected into context via systemMessage on every prompt. This matches the mental model of "memory just works."

3. MCP Native: Standard protocol, better tooling support, type-safe TypeScript implementation. Other MCP-compatible clients can potentially reuse the same server.

4. Global Configuration: One config file for all projects (~/.openviking/ov.conf), not per-project ./ov.conf files.

Capture Strategy: User Messages Only by Default

One design choice worth explaining in detail:

Why Auto-Capture User Messages Only

In practice, auto-capturing assistant turns in coding scenarios has proven problematic:

1. VLM Token Cost: Each capture triggers an LLM extraction call to OpenViking. Capturing every assistant turn (including tool calls, sub-agent outputs, etc.) quickly becomes expensive.

2. Signal-to-Noise Ratio: Claude Code's assistant messages often contain verbose tool outputs, file contents, and nested sub-agent traces. These rarely contain memorable personal context — the valuable signal is typically in the user's questions, decisions, and stated preferences.

3. Coding Workflow Nature: For coding tasks, "memory" is often about:

   • User preferences ("use tabs not spaces", "prefer arrow functions")
   • Project context ("this repo uses bun, not npm")
   • Decisions made ("let's skip the refactor for now")

   These almost always originate from the user, not the assistant.

Current Default

The plugin defaults to captureAssistantTurns: false — only user messages are considered for auto-capture. This keeps token usage manageable while still preserving the most valuable context.

Users can opt-in to full capture by setting "captureAssistantTurns": true in their ov.conf if they want assistant turns included (e.g., for non-coding workflows where assistant insights matter).

Migration Steps

1. Update Config Location

Move your config from project root to the global location:

# Old location (per-project)
./ov.conf

# New location (global)
~/.openviking/ov.conf

If you have project-specific configs, merge them into the global config. The new plugin supports a claude_code section for plugin-specific overrides.

2. Install Node.js Runtime

The new plugin requires Node.js. Ensure Node.js 18+ is installed:

node --version  # Should be 18.x or higher

3. Remove Old Plugin, Install New Plugin

# Uninstall old plugin (if installed via marketplace)
/plugin uninstall openviking-memory

# Install new plugin
/plugin marketplace add Castor6/openviking-plugins
/plugin install claude-code-memory-plugin@openviking-plugin

4. Remove Per-Project Plugin Files

Delete the old plugin directory from your project if it was checked in:

rm -rf ./.openviking/memory/

5. Update Config File (Optional)

Add the claude_code section to ~/.openviking/ov.conf for plugin-specific settings:

{
  "claude_code": {
    "agentId": "claude-code",
    "recallLimit": 6,
    "captureMode": "semantic",
    "captureTimeoutMs": 30000,
    "captureAssistantTurns": false
  }
}

Behavior Changes

Memory Recall

The new plugin automatically injects relevant memories into the context before each prompt. No manual action needed.

Memory Capture

The new plugin captures memories incrementally after each turn, providing faster feedback and better persistence.

MCP Tools (New Feature)

The new plugin provides MCP tools for explicit memory operations:

These tools are available when you need explicit control over memory operations.

Troubleshooting