Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(cc-memory-plugin): stop silently dropping tool-heavy batches; remove MIGRATION.md (#1850)

t0sakie69ae7e08fce
diff --git a/examples/claude-code-memory-plugin/MIGRATION.md b/examples/claude-code-memory-plugin/MIGRATION.md
deleted file mode 100644
index 4c635e9dc..000000000
--- a/examples/claude-code-memory-plugin/MIGRATION.md
+++ /dev/null
@@ -1,151 +0,0 @@
-# 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
-
-| Aspect | Old Plugin (`claude-memory-plugin`) | New Plugin (`claude-code-memory-plugin`) |
-|--------|--------------------------------------|-------------------------------------------|
-| **Architecture** | Bash hooks + Python bridge (`ov_memory.py`) | Native MCP server + Node.js hooks |
-| **Auto-Recall** | Skill-based, requires explicit invocation | Transparent, injected via `UserPromptSubmit` hook |
-| **Memory Capture** | Accumulates on `Stop`, commits on `SessionEnd` (async) | Incremental capture on each `Stop` (sync, safer) |
-| **Crash Safety** | Risk of losing accumulated turns if Claude crashes before `SessionEnd` | Each turn persisted independently — no data loss |
-| **Type Safety** | Shell + Python, no compile-time checks | TypeScript MCP server, compiled JS artifact |
-| **Tool Discovery** | Custom skill file | Standard MCP tools (`memory_recall`, `memory_store`, etc.) |
-| **Config Scope** | Project-local (`./ov.conf`) | Global (`~/.openviking/ov.conf`) — works across all projects |
-| **Runtime Bootstrap** | Manual setup required | Auto-bootstrap on first `SessionStart` into `${CLAUDE_PLUGIN_DATA}` |
-
-### 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:
-
-```bash
-# 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:
-
-```bash
-node --version # Should be 18.x or higher
-```
-
-### 3. Remove Old Plugin, Install New Plugin
-
-```bash
-# 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:
-
-```bash
-rm -rf ./.openviking/memory/
-```
-
-### 5. Update Config File (Optional)
-
-Add the `claude_code` section to `~/.openviking/ov.conf` for plugin-specific settings:
-
-```json
-{
- "claude_code": {
- "agentId": "claude-code",
- "recallLimit": 6,
- "captureMode": "semantic",
- "captureTimeoutMs": 30000,
- "captureAssistantTurns": false
- }
-}
-```
-
-## Behavior Changes
-
-### Memory Recall
-
-| Old Plugin | New Plugin |
-|------------|------------|
-| Run `/memory-recall <query>` manually | Automatic recall on every prompt |
-| Skill-based, requires Claude tool call | Transparent, injected as system context |
-
-The new plugin automatically injects relevant memories into the context before each prompt. No manual action needed.
-
-### Memory Capture
-
-| Old Plugin | New Plugin |
-|------------|------------|
-| Captures at `SessionEnd` (batch) | Captures at `Stop` (incremental) |
-| Requires explicit commit | Automatic, real-time |
-
-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:
-
-| Tool | Description |
-|------|-------------|
-| `memory_recall` | Manual semantic search |
-| `memory_store` | Manually store a memory |
-| `memory_forget` | Delete memories by URI or query |
-| `memory_health` | Check server status |
-
-These tools are available when you need explicit control over memory operations.
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| MCP tools not available | Start a new Claude session; first run installs runtime deps |
-| No memories recalled | Ensure OpenViking server is running: `openviking-server` |
-| Hook timeout | Increase timeout in `hooks/hooks.json` |
diff --git a/examples/claude-code-memory-plugin/scripts/auto-capture.mjs b/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
index 408f3e2c9..1d7c2128e 100644
--- a/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
+++ b/examples/claude-code-memory-plugin/scripts/auto-capture.mjs
@@ -391,20 +391,46 @@ async function main() {
return;
}
+ // Batch-level capture decision. shouldCapture() is designed to evaluate a *single
+ // user message* (length bounds, command/punctuation/question-only filters, keyword
+ // trigger). Applied to a multi-turn batch concatenated by formatTurnsAsText(), it
+ // misfires:
+ // - tool I/O inlining easily pushes combined text over captureMaxLength → entire
+ // batch silently dropped + state advanced → permanent data loss
+ // - JSON-shaped tool I/O can match the punctuation-only regex → non_content drop
+ // - a leading `/cmd` user turn flips the whole batch to `command` → drop
+ // - a question-shaped user turn ("why?") tags the whole batch as question_only
+ // For batches we only need: skip empty batches, and (keyword mode) require *some*
+ // user turn to carry a trigger phrase. Per-turn substance is already bounded by
+ // TOOL_BLOCK_MAX_CHARS during harvest.
const combined = formatTurnsAsText(captureTurns);
- const decision = shouldCapture(combined);
- log("should_capture", {
- capture: decision.capture,
- reason: decision.reason,
- textPreview: decision.text.slice(0, 100),
- });
-
- if (!decision.capture) {
+ if (!sanitize(combined)) {
+ log("skip", { stage: "batch_empty" });
await saveState(sessionId, { capturedTurnCount: allTurns.length });
approve();
return;
}
+ if (cfg.captureMode === "keyword") {
+ const hasTrigger = captureTurns.some(
+ (t) =>
+ t.role === "user" &&
+ MEMORY_TRIGGERS.some((re) => re.test(sanitize(t.text))),
+ );
+ if (!hasTrigger) {
+ log("skip", { stage: "keyword_mode_no_trigger", turns: captureTurns.length });
+ await saveState(sessionId, { capturedTurnCount: allTurns.length });
+ approve();
+ return;
+ }
+ }
+
+ log("should_capture", {
+ capture: true,
+ reason: cfg.captureMode === "keyword" ? "keyword_trigger_matched" : "semantic",
+ combinedLength: combined.length,
+ });
+
const result = await pushTurnsToOv(ovSessionId, captureTurns);
log("push_turns", { ovSessionId, ok: result.ok, failed: result.failed });