claude_memory 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 015ffacff45c0d7976124cbf40c2188d03f3fd182f24de2eab83bd5c0273107e
+  data.tar.gz: 68879337aca9ec2b5e9574df1982aead620975b84448cf0ca385d00690619d5b
+SHA512:
+  metadata.gz: 3c3ba3ea0f53e035b7ea377bc2c81fc398d7476bfb1019594db274e6aba67e2d92d09420e5f8c08ce1695a0f0128b1cb03d6931df92c172f57f3dc903233c41a
+  data.tar.gz: f4f1c185a02b2c5a469dac940e4b06a2cd37a67d0efc4ae8199d4688a2a3511eaf856ea393ecfb9f8972febe6d05cf490c384071a9e349e307d8adf20753219f

data/.claude/CLAUDE.md

@@ -0,0 +1,3 @@
+# Project Memory
+
+@.claude/rules/claude_memory.generated.md

data/.claude/output-styles/memory-aware.md

@@ -0,0 +1,21 @@
+---
+keep-coding-instructions: true
+---
+
+# Memory-Aware Output Style
+
+When making decisions or establishing conventions:
+- State decisions clearly with "We decided to..." or "We agreed to..."
+- Be explicit about technology choices: "We use PostgreSQL for..."
+- Clarify when replacing previous decisions: "We no longer use X, switching to Y"
+- Note conventions with "Convention:" or "Standard:"
+
+When recalling past context:
+- Use the memory.recall MCP tool to find relevant past decisions
+- Cite specific facts when referencing previous work
+- If unsure, use memory.explain to get provenance for a fact
+
+When conflicts arise:
+- Acknowledge contradictions explicitly
+- Use memory.conflicts to see open disputes
+- Help resolve conflicts by providing clear supersession signals

data/.claude/rules/claude_memory.generated.md

@@ -0,0 +1,21 @@
+<!-- 
+  This file is auto-generated by claude-memory.
+  Do not edit manually - changes will be overwritten.
+  Generated: 2026-01-20T22:15:57Z
+-->
+
+# Project Memory
+
+## Conventions
+
+- run linting with 'bundle exec rake standard'
+- Ruby 3.2+ required
+- frozen_string_literal: true in all Ruby files
+- Uses Standard Ruby for linting
+- Default task runs tests and linter
+- RSpec uses documentation format
+
+## Technical Constraints
+
+- **Uses framework**: Sequel
+- **Uses database**: SQLite3

data/.claude/settings.json

@@ -0,0 +1,62 @@
+{
+  "hooks": {
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 10
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "claude-memory hook ingest --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          },
+          {
+            "type": "command",
+            "command": "claude-memory hook sweep --db /Users/valentinostoll/src/claude_memory/.claude/memory.sqlite3",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}

data/.claude/settings.local.json

@@ -0,0 +1,21 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__claude-memory__memory_changes",
+      "mcp__claude-memory__memory_status",
+      "mcp__claude-memory__memory_recall",
+      "Bash(./exe/claude-memory:*)",
+      "mcp__claude-memory__memory_store_extraction",
+      "mcp__plugin_claude-memory_claude-memory__memory_store_extraction",
+      "mcp__plugin_claude-memory_claude-memory__memory_recall",
+      "mcp__plugin_claude-memory_claude-memory__memory_status",
+      "mcp__plugin_claude-memory_memory__memory_recall",
+      "mcp__memory__memory_recall",
+      "mcp__memory__memory_changes",
+      "mcp__memory__memory_status",
+      "mcp__memory__memory_store_extraction",
+      "mcp__memory__memory_explain"
+    ]
+  },
+  "enableAllProjectMcpServers": true
+}

data/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "claude-memory-marketplace",
+  "owner": {
+    "name": "Valentino Stoll"
+  },
+  "plugins": [
+    {
+      "name": "claude-memory",
+      "source": "./",
+      "description": "Long-term self-managed memory for Claude Code"
+    }
+  ]
+}

data/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "claude-memory",
+  "version": "0.1.0",
+  "description": "Long-term self-managed memory for Claude Code with fact extraction, truth maintenance, and provenance tracking",
+  "author": {
+    "name": "Valentino Stoll"
+  },
+  "license": "MIT",
+  "keywords": ["memory", "facts", "knowledge", "persistence"]
+}

data/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "memory": {
+      "type": "stdio",
+      "command": "claude-memory",
+      "args": [
+        "serve-mcp"
+      ]
+    }
+  }
+}

data/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [Unreleased]
+
+### Added
+
+- **Claude Code Plugin**: Full plugin structure for seamless Claude Code integration
+  - `.claude-plugin/plugin.json` manifest
+  - `.claude-plugin/marketplace.json` for plugin distribution
+  - `hooks/hooks.json` with prompt hooks for Claude-powered extraction
+  - `skills/memory/SKILL.md` for `/memory` command
+- **Claude-Powered Fact Extraction**: New `memory.store_extraction` MCP tool
+  - Accepts structured JSON with entities, facts, and decisions
+  - Prompt hooks ask Claude to extract facts on session stop
+  - No API key required - uses Claude Code's own session
+  - Full schema validation with truth maintenance
+- **Empty Query Handling**: FTS5 search now gracefully handles empty queries
+
+## [0.1.0] - 2026-01-20
+
+### Added
+
+- SQLite store with full MVP schema (entities, facts, provenance, conflicts)
+- Transcript delta ingestion with cursor tracking
+- Full-text search via SQLite FTS5
+- NullDistiller for heuristic-based fact extraction
+- Resolver for truth maintenance (supersession/conflict handling)
+- Recall API with provenance receipts
+- Sweep mechanics for time-bounded maintenance
+- MCP server with memory tools
+- Publish command for Claude Code memory integration
+- CLI with all core commands
+- Doctor command for health checks
+- Hooks and output style templates

data/CLAUDE.md

@@ -0,0 +1,224 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+ClaudeMemory is a Ruby gem that provides long-term, self-managed memory for Claude Code using hooks, MCP tools, and output styles. It ingests transcripts, distills them into facts with provenance, resolves contradictions, and publishes curated snapshots.
+
+**Key dependencies:**
+- Ruby 3.2.0+
+- Sequel (~> 5.0) for database access
+- SQLite3 (~> 2.0) for storage
+
+## Development Commands
+
+### Setup
+```bash
+bin/setup              # Install dependencies
+```
+
+### Testing
+```bash
+bundle exec rspec                              # Run all tests
+bundle exec rspec spec/claude_memory/cli_spec.rb  # Run single test file
+bundle exec rspec spec/claude_memory/cli_spec.rb:42  # Run specific test by line number
+bundle exec rake spec                          # Alternative test command
+bundle exec rake                               # Run tests + Standard linter (default task)
+```
+
+### Linting
+```bash
+bundle exec rake standard        # Run Standard Ruby linter
+bundle exec rake standard:fix    # Auto-fix linting issues
+```
+
+### Build & Release
+```bash
+bundle exec rake build   # Build gem to pkg/
+bundle exec rake install # Install gem locally
+bundle exec rake release # Tag + push to RubyGems (requires credentials)
+```
+
+### Running the CLI
+```bash
+# During development, use the executable directly
+./exe/claude-memory <command>
+
+# Or via bundle exec
+bundle exec claude-memory <command>
+```
+
+## Architecture
+
+### Dual-Database System
+ClaudeMemory uses two SQLite databases for memory separation:
+
+- **Global DB** (`~/.claude/memory.sqlite3`): User-wide knowledge across all projects (preferences, conventions)
+- **Project DB** (`.claude/memory.sqlite3`): Project-specific facts and decisions
+
+The `Store::StoreManager` class manages both connections. Commands query both databases by default, with project facts taking precedence.
+
+### Core Pipeline
+
+```
+Transcripts → Ingest → Index (FTS5)
+                   ↓
+             Distill → Extract entities/facts + scope hints
+                   ↓
+             Resolve → Truth maintenance (supersession/conflicts)
+                   ↓
+             Store → SQLite (facts, provenance, entities)
+                   ↓
+             Publish → .claude/rules/claude_memory.generated.md
+```
+
+### Module Structure
+
+- **`Store`**: SQLite database access via Sequel (`sqlite_store.rb`, `store_manager.rb`)
+  - Schema includes: content_items, entities, facts, provenance, fact_links, conflicts
+  - Schema migrations in `ensure_schema!` and `migrate_to_v2!`
+
+- **`Ingest`**: Transcript reading and delta-based ingestion (`ingester.rb`, `transcript_reader.rb`)
+  - Tracks cursor position per session to avoid re-processing
+
+- **`Index`**: Full-text search using SQLite FTS5 (`lexical_fts.rb`)
+  - No embeddings required for MVP
+
+- **`Distill`**: Fact extraction interface (`distiller.rb`, `null_distiller.rb`)
+  - Pluggable distiller design (current: NullDistiller stub)
+  - Extracts entities, facts, scope hints from content
+
+- **`Resolve`**: Truth maintenance and conflict resolution (`resolver.rb`, `predicate_policy.rb`)
+  - Determines equivalence, supersession, or conflicts
+  - PredicatePolicy controls single-value vs multi-value predicates
+
+- **`Recall`**: Query interface for facts (`recall.rb`)
+  - Searches both global + project databases
+  - Returns facts with provenance receipts
+
+- **`Sweep`**: Maintenance and pruning (`sweeper.rb`)
+
+- **`Publish`**: Snapshot generation to Claude Code memory files (`publish.rb`)
+  - Modes: shared (repo), local (uncommitted), home (user directory)
+
+- **`MCP`**: Model Context Protocol server and tools (`mcp/server.rb`, `mcp/tools.rb`)
+  - Exposes memory tools to Claude Code: recall, explain, promote, status, conflicts, changes, sweep_now
+
+- **`Hook`**: Hook entrypoint handlers (`hook/handler.rb`)
+  - Reads stdin JSON from Claude Code hooks
+  - Routes to ingest/sweep/publish commands
+
+- **`CLI`**: Command-line interface (`cli.rb`)
+  - All user-facing commands and option parsing
+
+### Database Schema
+
+Key tables (defined in `sqlite_store.rb`):
+- `content_items`: Ingested transcript chunks with cursor tracking
+- `entities`: Named entities (people, repos, concepts)
+- `entity_aliases`: Alternative names for entities
+- `facts`: Subject-predicate-object triples with validity windows and scope
+- `provenance`: Links facts to source content_items
+- `fact_links`: Supersession and conflict relationships
+- `conflicts`: Open contradictions
+
+Facts include:
+- `scope`: "global" or "project" (determines applicability)
+- `project_path`: Set for project-scoped facts
+- `valid_from`/`valid_to`: Temporal validity window
+
+### Scope System
+
+Facts are scoped to control where they apply:
+- **project**: Current project only (e.g., "this app uses PostgreSQL")
+- **global**: All projects (e.g., "I prefer 4-space indentation")
+
+Distiller detects signals like "always", "in all projects", "my preference" and sets `scope_hint: "global"`. Users can manually promote facts via `claude-memory promote <fact_id>` or the `memory.promote` MCP tool.
+
+## Testing Strategy
+
+Tests are in `spec/claude_memory/` organized by module. Use RSpec's `--format documentation` for readable output.
+
+When writing tests:
+- Mock external dependencies (file I/O, database where appropriate)
+- Use `let` blocks for shared test data
+- Focus on behavior, not implementation details
+
+## Common Development Tasks
+
+### Adding a New CLI Command
+
+1. Add command name to `CLI#run` case statement
+2. Implement private method (e.g., `my_command_cmd`)
+3. Add parser method (e.g., `parse_my_command_options`)
+4. Update `print_help` output
+5. Add corresponding tests in `spec/claude_memory/cli_spec.rb`
+
+### Adding a New MCP Tool
+
+1. Add tool definition to `MCP::Tools::TOOLS` hash
+2. Implement handler in `MCP::Server#handle_tool_call`
+3. Ensure tool queries appropriate database(s) via StoreManager
+4. Add tests in `spec/claude_memory/mcp/`
+
+### Modifying Database Schema
+
+1. Increment `SCHEMA_VERSION` in `sqlite_store.rb`
+2. Add migration method (e.g., `migrate_to_v3!`)
+3. Call migration in `run_migrations!`
+4. Test migration on existing database files
+5. Update documentation if schema changes affect external interfaces
+
+### Adding a New Predicate Policy
+
+Single-value predicates (like "uses_database") supersede old values. Multi-value predicates (like "depends_on") accumulate. Modify `PredicatePolicy.single?` to adjust behavior.
+
+## Important Files
+
+- `lib/claude_memory.rb`: Main module, requires, database path helpers
+- `lib/claude_memory/cli.rb`: All CLI command implementations (800+ lines)
+- `lib/claude_memory/store/store_manager.rb`: Dual-database connection manager
+- `lib/claude_memory/resolve/resolver.rb`: Truth maintenance logic
+- `lib/claude_memory/recall.rb`: Fact query and merging logic
+- `docs/updated_plan.md`: Comprehensive architectural plan and milestones
+- `claude_memory.gemspec`: Gem metadata and dependencies
+
+## MCP Integration
+
+The gem includes an MCP server (`claude-memory serve-mcp`) that exposes memory operations as tools. Configuration should be in `.mcp.json` at project root.
+
+Available MCP tools:
+- `memory.recall` - Search for relevant facts (scope filtering supported)
+- `memory.explain` - Get detailed fact provenance
+- `memory.promote` - Promote project fact to global
+- `memory.status` - Health check for both databases
+- `memory.changes` - Recent fact updates
+- `memory.conflicts` - Open contradictions
+- `memory.sweep_now` - Run maintenance
+
+## Hook Integration
+
+ClaudeMemory integrates with Claude Code via hooks in `.claude/settings.json`:
+
+- **Ingest hook**: Triggers on Stop/SessionStart/PreCompact events
+  - Calls `claude-memory hook ingest` with stdin JSON
+  - Reads transcript delta and updates both global and project databases
+
+- **Sweep hook**: Triggers on idle_prompt and safety events
+  - Runs time-bounded maintenance on both databases
+
+- **Publish hook**: Optional, on SessionEnd/PreCompact
+  - Publishes curated snapshot to `.claude/rules/`
+
+Hook commands read JSON payloads from stdin for robustness.
+
+## Code Style
+
+This project uses [Standard Ruby](https://github.com/standardrb/standard) for linting. Run `bundle exec rake standard:fix` before committing.
+
+Key conventions:
+- Use `frozen_string_literal: true` at top of all Ruby files
+- Prefer explicit returns only when control flow is complex
+- Use Sequel's dataset methods (avoid raw SQL where possible)
+- Keep CLI commands focused; extract complex logic to dedicated classes

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"claude_memory" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["v@codenamev.com"](mailto:"v@codenamev.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Valentino Stoll
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.