claude_memory 0.4.0 → 0.5.0

data/docs/remaining_improvements.md

@@ -1,330 +0,0 @@
-# Remaining Improvements from Analysis
-
-This document contains the improvements that have NOT yet been implemented from the episodic-memory and claude-mem analysis.
-
-**Note:** The "index" command to generate embeddings for existing facts has been completed (2026-01-23). FastEmbed integration (BAAI/bge-small-en-v1.5 via fastembed-rb) was added for high-quality local embeddings (2026-02-02), replacing TF-IDF as the primary embedding approach for benchmarks.
-
----
-
-## 1. Background Processing for Hooks
-
-### What Episodic-Memory Does
-
-**Background Sync**:
-```bash
-# SessionStart hook
-episodic-memory sync --background
-```
-
-Runs in background, user continues working immediately.
-
-**File**: `src/sync.ts`
-
-### What We Should Do
-
-**Priority**: MEDIUM
-
-**Implementation**:
-
-1. **Background processing flag**:
-   ```ruby
-   # lib/claude_memory/commands/hook_command.rb
-   def call(args)
-     opts = parse_options(args, { async: false })
-
-     if opts[:async]
-       # Fork and detach
-       pid = fork do
-         Process.setsid  # Detach from terminal
-         execute_hook(subcommand, payload)
-       end
-       Process.detach(pid)
-
-       stdout.puts "Hook execution started in background (PID: #{pid})"
-       return Hook::ExitCodes::SUCCESS
-     end
-
-     execute_hook(subcommand, payload)
-   end
-   ```
-
-2. **Hook configuration**:
-   ```json
-   {
-     "hooks": {
-       "SessionStart": [{
-         "matcher": "startup|resume",
-         "hooks": [{
-           "type": "command",
-           "command": "claude-memory hook ingest --async",
-           "async": true
-         }]
-       }]
-     }
-   }
-   ```
-
-**Benefits**:
-- Non-blocking hooks (user continues working immediately)
-- Better user experience for long-running operations
-- Doesn't delay session startup
-
-**Trade-offs**:
-- Background process management complexity
-- Need logging for background execution
-- Potential race conditions if multiple sessions start simultaneously
-
----
-
-## 2. ROI Metrics and Token Economics
-
-### What claude-mem Does
-
-**Discovery Token Tracking**:
-- `discovery_tokens` field on observations table
-- Tracks tokens spent discovering each piece of knowledge
-- Cumulative metrics in session summaries
-- Footer displays ROI: "Access 10k tokens for 2,500t"
-
-**File**: `src/services/sqlite/Database.ts`
-
-```typescript
-observations: {
-  id: INTEGER PRIMARY KEY,
-  title: TEXT,
-  narrative: TEXT,
-  discovery_tokens: INTEGER,  // ← Cost tracking
-  created_at_epoch: INTEGER
-}
-
-session_summaries: {
-  cumulative_discovery_tokens: INTEGER,  // ← Running total
-  observation_count: INTEGER
-}
-```
-
-**Context Footer Example**:
-```markdown
-💡 **Token Economics:**
-- Context shown: 2,500 tokens
-- Research captured: 10,000 tokens
-- ROI: 4x compression
-```
-
-### What We Should Do
-
-**Priority**: MEDIUM
-
-**Implementation**:
-
-1. **Add metrics table**:
-   ```ruby
-   create_table :ingestion_metrics do
-     primary_key :id
-     foreign_key :content_item_id, :content_items
-     Integer :input_tokens
-     Integer :output_tokens
-     Integer :facts_extracted
-     DateTime :created_at
-   end
-   ```
-
-2. **Track during distillation**:
-   ```ruby
-   # lib/claude_memory/distill/distiller.rb
-   def distill(content)
-     response = api_call(content)
-     facts = extract_facts(response)
-
-     store_metrics(
-       input_tokens: response.usage.input_tokens,
-       output_tokens: response.usage.output_tokens,
-       facts_extracted: facts.size
-     )
-
-     facts
-   end
-   ```
-
-3. **Display in CLI**:
-   ```ruby
-   # claude-memory stats
-   def stats_cmd
-     metrics = store.aggregate_metrics
-     puts "Token Economics:"
-     puts "  Input: #{metrics[:input_tokens]} tokens"
-     puts "  Output: #{metrics[:output_tokens]} tokens"
-     puts "  Facts: #{metrics[:facts_extracted]}"
-     puts "  Efficiency: #{metrics[:facts_extracted] / metrics[:input_tokens].to_f} facts/token"
-   end
-   ```
-
-4. **Add to published snapshot**:
-   ```markdown
-   <!-- At bottom of .claude/rules/claude_memory.generated.md -->
-
-   ---
-
-   *Memory stats: 145 facts from 12,500 ingested tokens (86 facts/1k tokens)*
-   ```
-
-**Benefits**:
-- Visibility into memory system efficiency
-- Justifies API costs (shows compression ratio)
-- Helps tune distillation prompts for better extraction
-
-**Trade-offs**:
-- Requires API usage tracking
-- Adds database complexity
-- May not be meaningful for all distiller implementations
-
----
-
-## 3. Structured Logging
-
-### Implementation
-
-**Priority**: LOW
-
-1. **Add structured logger**:
-   ```ruby
-   # lib/claude_memory/logging/logger.rb
-   module ClaudeMemory
-     module Logging
-       class Logger
-         def initialize(output = $stderr, level: :info)
-           @output = output
-           @level = level
-         end
-
-         def info(message, metadata = {})
-           log(:info, message, metadata)
-         end
-
-         def error(message, exception: nil, metadata = {})
-           log(:error, message, metadata.merge(exception: exception&.message))
-         end
-
-         private
-
-         def log(level, message, metadata)
-           return if should_skip?(level)
-
-           log_entry = {
-             timestamp: Time.now.iso8601,
-             level: level,
-             message: message
-           }.merge(metadata)
-
-           @output.puts JSON.generate(log_entry)
-         end
-       end
-     end
-   end
-   ```
-
-2. **Usage in Ingester**:
-   ```ruby
-   def ingest(...)
-     logger.info("Starting ingestion",
-       session_id: session_id,
-       transcript_path: transcript_path
-     )
-
-     begin
-       # ... ingestion logic ...
-
-       logger.info("Ingestion complete",
-         content_items_created: 1,
-         facts_extracted: facts.size
-       )
-     rescue => e
-       logger.error("Ingestion failed",
-         exception: e,
-         session_id: session_id
-       )
-       raise
-     end
-   end
-   ```
-
-**Benefits**:
-- Better debugging with structured data
-- Easy log parsing and analysis
-- Consistent log format
-
-**Trade-offs**:
-- Additional complexity
-- Log output may be verbose
-
----
-
-
-## Features to Avoid
-
-### 1. Chroma Vector Database
-
-**Their Approach**: Hybrid SQLite FTS5 + Chroma vector search.
-
-**Our Take**: **Skip it.** Adds significant complexity:
-
-- Python dependency
-- ChromaDB server
-- Embedding generation
-- Sync overhead
-
-**Alternative**: We use [fastembed-rb](https://github.com/khasinski/fastembed-rb) with BAAI/bge-small-en-v1.5 for high-quality local embeddings (384-dim, no API key, ONNX runtime). Benchmark results: Recall@5=0.786 aggregate, 0.696 on semantic paraphrase queries.
-
-### 2. Claude Agent SDK for Distillation
-
-**Their Approach**: Use `@anthropic-ai/claude-agent-sdk` for observation compression.
-
-**Our Take**: **Skip it.** We already have `Distill::Distiller` interface. SDK adds:
-
-- Node.js dependency
-- Subprocess management
-- Complex event loop
-
-**Alternative**: Direct API calls via `anthropic-rb` gem (if we implement distiller).
-
-### 3. Worker Service Background Process
-
-**Their Approach**: Long-running worker with HTTP API + MCP wrapper.
-
-**Our Take**: **Skip it.** We use MCP server directly:
-
-- No background process to manage
-- No port conflicts
-- No PID files
-- Simpler deployment
-
-**Alternative**: Keep stdio-based MCP server. Add HTTP transport only if needed.
-
-### 4. Web Viewer UI
-
-**Their Approach**: React-based web UI at `http://localhost:37777`.
-
-**Our Take**: **Skip for MVP.** Significant effort for uncertain value:
-
-- React + esbuild
-- SSE implementation
-- State management
-- CSS/theming
-
-**Alternative**: CLI output is sufficient. Add web UI if users request it.
-
----
-
-## Implementation Priorities
-
-### Medium Priority
-
-1. **Background Processing** - Non-blocking hooks for better UX
-2. **ROI Metrics** - Track token economics for distillation
-
-### Low Priority
-
-3. **Structured Logging** - Better debugging with JSON logs
-4. **Health Monitoring** - Only if we add background worker
-5. **Web Viewer UI** - Only if users request visualization
-6. **Configuration-Driven Context** - Only if users request snapshot customization