Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
Python agent-contextagent-memoryagent-pluginsagentic-ragcontext-databasedsh-pluginknowledge-basememorymemory-managementself-evolvingvector-database
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.mddeleted file mode 100644index 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.mjsindex 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 });