claude_memory 0.2.0 → 0.3.0

data/README.md

@@ -17,21 +17,47 @@ It automatically:
 
 ## Quick Start
 
-### Install
+### 1. Install the Gem
 ```bash
 gem install claude_memory
 ```
 
-### Initialize
+### 2. Install the Plugin
+
+From within Claude Code, add the marketplace and install the plugin:
+
+```bash
+# Add the marketplace (one-time setup)
+/plugin marketplace add codenamev/claude_memory
+
+# Install the plugin
+/plugin install claude-memory
+```
+
+### 3. Initialize Memory
+
+Initialize both global and project-specific memory:
+
 ```bash
-# In your project
-cd my-project
 claude-memory init
+```
+
+This creates:
+- **Global database** (`~/.claude/memory.sqlite3`) - User-wide preferences
+- **Project database** (`.claude/memory.sqlite3`) - Project-specific knowledge
+
+### 4. Analyze Your Project (Optional)
+
+Bootstrap memory with your project's tech stack:
+
+```
+/claude-memory:analyze
+```
 
-# Or globally for all projects
-claude-memory init --global
+This reads your project files (Gemfile, package.json, etc.) and stores facts about languages, frameworks, tools, and conventions.
 
-# Verify setup
+### 5. Verify Setup
+```bash
 claude-memory doctor
 ```
 
@@ -90,9 +116,91 @@ Claude: [uses it during session]
 
 Supported tags: `<private>`, `<no-memory>`, `<secret>`
 
+## Upgrading
+
+Existing users can upgrade seamlessly:
+
+```bash
+gem update claude_memory
+```
+
+All database migrations happen automatically. Run `claude-memory doctor` to verify.
+
+See [CHANGELOG.md](CHANGELOG.md) for detailed release notes.
+
+## Troubleshooting
+
+### Check Setup Status
+
+If memory tools aren't working, check initialization status:
+
+```
+memory.check_setup
+```
+
+This returns:
+- Initialization status (healthy, needs_upgrade, not_initialized)
+- Version information
+- Missing components
+- Actionable recommendations
+
+### Installation Help
+
+Need help getting started? Run:
+
+```
+/setup-memory
+```
+
+This skill provides:
+- Step-by-step installation instructions
+- Common error solutions
+- Post-installation verification
+- Upgrade guidance
+
+### Health Check
+
+Verify your ClaudeMemory installation:
+
+```bash
+claude-memory doctor
+```
+
+This checks:
+- Database existence and integrity
+- Schema version compatibility
+- Hooks configuration
+- Snapshot status
+- Stuck operations
+- Orphaned hooks (hooks without MCP configuration)
+
+### Uninstalling
+
+To remove ClaudeMemory configuration:
+
+```bash
+# Remove hooks and MCP configuration (keeps databases)
+claude-memory uninstall
+
+# Remove everything including databases
+claude-memory uninstall --full
+
+# For global uninstall
+claude-memory uninstall --global
+claude-memory uninstall --global --full
+```
+
+The uninstall command removes:
+- Hooks from `.claude/settings.json`
+- MCP server from `.claude.json`
+- ClaudeMemory section from `CLAUDE.md`
+- Databases and generated files (with `--full`)
+
+**Note:** The `doctor` command will warn you if orphaned hooks are detected (hooks configured but MCP plugin removed). Run `claude-memory uninstall` to clean them up.
+
 ## Documentation
 
-- 📖 [Getting Started](docs/GETTING_STARTED.md) - Step-by-step onboarding *(coming soon)*
+- 📖 [Getting Started](docs/GETTING_STARTED.md) - Step-by-step onboarding
 - 💡 [Examples](docs/EXAMPLES.md) - Use cases and workflows
 - 🔧 [Plugin Setup](docs/PLUGIN.md) - Claude Code integration
 - 🏗️ [Architecture](docs/architecture.md) - Technical deep dive
@@ -102,7 +210,7 @@ Supported tags: `<private>`, `<no-memory>`, `<secret>`
 
 - **Language:** Ruby 3.2+
 - **Storage:** SQLite3 (no external services)
-- **Testing:** 583 examples, 100% core coverage
+- **Testing:** 985 examples, 100% core coverage
 - **Code Style:** Standard Ruby
 
 ```bash
@@ -118,7 +226,6 @@ bundle exec rspec
 
 - 🐛 [Report a bug](https://github.com/codenamev/claude_memory/issues)
 - 💬 [Discussions](https://github.com/codenamev/claude_memory/discussions)
-- 📧 Email: valentino@hanamirb.org
 
 ## License
 

data/db/migrations/001_create_initial_schema.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+Sequel.migration do
+  up do
+    create_table?(:meta) do
+      String :key, primary_key: true
+      String :value
+    end
+
+    # Content items store ingested transcript chunks with metadata
+    # metadata_json stores extensible session metadata as JSON:
+    # {
+    #   "git_branch": "feature/auth",
+    #   "cwd": "/path/to/project",
+    #   "claude_version": "4.5",
+    #   "tools_used": ["Read", "Edit", "Bash"]
+    # }
+    create_table?(:content_items) do
+      primary_key :id
+      String :source, null: false
+      String :session_id
+      String :transcript_path
+      String :occurred_at
+      String :ingested_at, null: false
+      String :text_hash, null: false
+      Integer :byte_len, null: false
+      String :raw_text, text: true
+      String :metadata_json, text: true  # Extensible JSON metadata
+    end
+
+    create_table?(:delta_cursors) do
+      primary_key :id
+      String :session_id, null: false
+      String :transcript_path, null: false
+      Integer :last_byte_offset, null: false, default: 0
+      String :updated_at, null: false
+      unique [:session_id, :transcript_path]
+    end
+
+    create_table?(:entities) do
+      primary_key :id
+      String :type, null: false
+      String :canonical_name, null: false
+      String :slug, null: false, unique: true
+      String :created_at, null: false
+    end
+
+    create_table?(:entity_aliases) do
+      primary_key :id
+      foreign_key :entity_id, :entities, null: false
+      String :source
+      String :alias, null: false
+      Float :confidence, default: 1.0
+    end
+
+    create_table?(:facts) do
+      primary_key :id
+      foreign_key :subject_entity_id, :entities
+      String :predicate, null: false
+      foreign_key :object_entity_id, :entities
+      String :object_literal
+      String :datatype
+      String :polarity, default: "positive"
+      String :valid_from
+      String :valid_to
+      String :status, default: "active"
+      Float :confidence, default: 1.0
+      String :created_from
+      String :created_at, null: false
+    end
+
+    create_table?(:provenance) do
+      primary_key :id
+      foreign_key :fact_id, :facts, null: false
+      foreign_key :content_item_id, :content_items
+      String :quote, text: true
+      foreign_key :attribution_entity_id, :entities
+      String :strength, default: "stated"
+    end
+
+    create_table?(:fact_links) do
+      primary_key :id
+      foreign_key :from_fact_id, :facts, null: false
+      foreign_key :to_fact_id, :facts, null: false
+      String :link_type, null: false
+    end
+
+    create_table?(:conflicts) do
+      primary_key :id
+      foreign_key :fact_a_id, :facts, null: false
+      foreign_key :fact_b_id, :facts, null: false
+      String :status, default: "open"
+      String :detected_at, null: false
+      String :notes, text: true
+    end
+
+    # Indexes
+    run "CREATE INDEX IF NOT EXISTS idx_facts_predicate ON facts(predicate)"
+    run "CREATE INDEX IF NOT EXISTS idx_facts_subject ON facts(subject_entity_id)"
+    run "CREATE INDEX IF NOT EXISTS idx_facts_status ON facts(status)"
+    run "CREATE INDEX IF NOT EXISTS idx_provenance_fact ON provenance(fact_id)"
+    run "CREATE INDEX IF NOT EXISTS idx_entity_aliases_entity ON entity_aliases(entity_id)"
+    run "CREATE INDEX IF NOT EXISTS idx_content_items_session ON content_items(session_id)"
+  end
+
+  down do
+    drop_table?(:conflicts)
+    drop_table?(:fact_links)
+    drop_table?(:provenance)
+    drop_table?(:facts)
+    drop_table?(:entity_aliases)
+    drop_table?(:entities)
+    drop_table?(:delta_cursors)
+    drop_table?(:content_items)
+    drop_table?(:meta)
+  end
+end

data/db/migrations/002_add_project_scoping.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Migration v2: Add project scoping support
+# - Adds project_path to content_items for tracking content by project
+# - Adds scope (global/project) and project_path to facts
+# - Adds indexes for filtering by scope and project
+Sequel.migration do
+  up do
+    alter_table(:content_items) do
+      add_column :project_path, String
+    end
+
+    alter_table(:facts) do
+      add_column :scope, String, default: "project"
+      add_column :project_path, String
+      add_index :scope, name: :idx_facts_scope
+      add_index :project_path, name: :idx_facts_project
+    end
+  end
+
+  down do
+    alter_table(:facts) do
+      drop_index :scope, name: :idx_facts_scope
+      drop_index :project_path, name: :idx_facts_project
+      drop_column :scope
+      drop_column :project_path
+    end
+
+    alter_table(:content_items) do
+      drop_column :project_path
+    end
+  end
+end

data/db/migrations/003_add_session_metadata.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+# Migration v3: Add session metadata and tool tracking
+# - Adds git_branch, cwd, claude_version, thinking_level to content_items
+# - Creates tool_calls table for tracking tool usage per content item
+# - Adds indexes for efficient querying
+Sequel.migration do
+  up do
+    alter_table(:content_items) do
+      add_column :git_branch, String
+      add_column :cwd, String
+      add_column :claude_version, String
+      add_column :thinking_level, String
+      add_index :git_branch, name: :idx_content_items_git_branch
+    end
+
+    create_table?(:tool_calls) do
+      primary_key :id
+      foreign_key :content_item_id, :content_items, on_delete: :cascade
+      String :tool_name, null: false
+      String :tool_input, text: true  # JSON of input parameters
+      String :tool_result, text: true  # Truncated result (first 500 chars)
+      TrueClass :is_error, default: false
+      String :timestamp, null: false
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_tool_calls_tool_name ON tool_calls(tool_name)"
+    run "CREATE INDEX IF NOT EXISTS idx_tool_calls_content_item ON tool_calls(content_item_id)"
+  end
+
+  down do
+    alter_table(:content_items) do
+      drop_index :git_branch, name: :idx_content_items_git_branch
+      drop_column :git_branch
+      drop_column :cwd
+      drop_column :claude_version
+      drop_column :thinking_level
+    end
+
+    drop_table?(:tool_calls)
+  end
+end

data/db/migrations/004_add_fact_embeddings.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Migration v4: Add embeddings for semantic search
+# - Adds embedding_json column to facts table for vector storage
+# - Uses JSON storage for embeddings instead of sqlite-vec extension
+# - Similarity calculations are done in Ruby using cosine similarity
+# - Future: Could migrate to native vector extension or external vector DB
+Sequel.migration do
+  up do
+    alter_table(:facts) do
+      add_column :embedding_json, String, text: true  # JSON array of floats
+    end
+  end
+
+  down do
+    alter_table(:facts) do
+      drop_column :embedding_json
+    end
+  end
+end

data/db/migrations/005_add_incremental_sync.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+# Migration v5: Add incremental sync support
+# - Adds source_mtime to content_items for tracking file modification times
+# - Enables efficient incremental sync: only re-ingest when source changed
+# - Index for efficient mtime-based lookups
+Sequel.migration do
+  up do
+    alter_table(:content_items) do
+      add_column :source_mtime, String  # ISO8601 timestamp of source file mtime
+      add_index :source_mtime, name: :idx_content_items_source_mtime
+    end
+  end
+
+  down do
+    alter_table(:content_items) do
+      drop_index :source_mtime, name: :idx_content_items_source_mtime
+      drop_column :source_mtime
+    end
+  end
+end

data/db/migrations/006_add_operation_tracking.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+# Migration v6: Add operation tracking and schema health monitoring
+# - Creates operation_progress table for long-running operations
+# - Creates schema_health table for validation and corruption detection
+# - Enables resumable operations with checkpoint support
+Sequel.migration do
+  up do
+    create_table?(:operation_progress) do
+      primary_key :id
+      String :operation_type, null: false  # "index_embeddings", "sweep", "distill"
+      String :scope, null: false           # "global" or "project"
+      String :status, null: false          # "running", "completed", "failed"
+      Integer :total_items
+      Integer :processed_items, default: 0
+      String :checkpoint_data, text: true  # JSON for resumption
+      String :started_at, null: false
+      String :completed_at
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_operation_progress_type ON operation_progress(operation_type)"
+    run "CREATE INDEX IF NOT EXISTS idx_operation_progress_status ON operation_progress(status)"
+
+    create_table?(:schema_health) do
+      primary_key :id
+      String :checked_at, null: false
+      Integer :schema_version, null: false
+      String :validation_status, null: false  # "healthy", "corrupt", "unknown"
+      String :issues_json, text: true         # Array of detected problems
+      String :table_counts_json, text: true   # Snapshot of table row counts
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_schema_health_checked_at ON schema_health(checked_at)"
+  end
+
+  down do
+    drop_table?(:operation_progress)
+    drop_table?(:schema_health)
+  end
+end

data/db/migrations/007_add_ingestion_metrics.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+# Migration v7: Add ingestion metrics for ROI tracking
+# - Creates ingestion_metrics table to track distillation costs
+# - Tracks token usage (input/output) and facts extracted
+# - Enables ROI analysis: tokens spent per fact extracted
+# - Shows efficiency of memory system over time
+Sequel.migration do
+  up do
+    create_table?(:ingestion_metrics) do
+      primary_key :id
+      foreign_key :content_item_id, :content_items, null: false
+      Integer :input_tokens         # Tokens sent to distillation API
+      Integer :output_tokens        # Tokens returned from distillation API
+      Integer :facts_extracted      # Number of facts extracted from this content
+      String :created_at, null: false
+    end
+
+    run "CREATE INDEX IF NOT EXISTS idx_ingestion_metrics_content_item ON ingestion_metrics(content_item_id)"
+    run "CREATE INDEX IF NOT EXISTS idx_ingestion_metrics_created_at ON ingestion_metrics(created_at)"
+  end
+
+  down do
+    drop_table?(:ingestion_metrics)
+  end
+end