claude_memory 0.3.0 → 0.4.0

data/output-styles/memory-aware.md

@@ -0,0 +1,71 @@
+---
+keep-coding-instructions: true
+---
+
+# Memory-Aware Output Style
+
+This output style helps Claude format responses in a way that makes knowledge easy to capture and recall from memory.
+
+## Stating Decisions and Conventions
+
+When making or documenting decisions, use clear declarative language:
+
+**Good examples:**
+- "We decided to use PostgreSQL for the main database"
+- "We agreed to use 4-space indentation for Ruby files"
+- "Convention: All API responses include a `meta` object"
+- "Standard: Test files go in `spec/` matching the source structure"
+
+**Why this helps:** Clear statements are easier to extract and recall later.
+
+## Signaling Changes and Supersession
+
+When replacing or updating previous decisions, make the change explicit:
+
+**Good examples:**
+- "We're switching from Redis to Memcached for caching"
+- "This supersedes our earlier decision to use REST APIs—we're now using GraphQL"
+- "We no longer validate email format server-side; client-side only"
+
+**Why this helps:** Memory can track supersession and resolve conflicts.
+
+## Acknowledging Contradictions
+
+When encountering conflicting information, call it out explicitly:
+
+**Good examples:**
+- "This contradicts our earlier decision to use MySQL"
+- "I found conflicting information: the README says Postgres, but the config uses SQLite"
+- "Two facts conflict: authentication was JWT, now seeing sessions"
+
+**Why this helps:** Explicit contradictions help memory identify conflicts to resolve.
+
+## Citing Sources
+
+When referencing previous knowledge, distinguish memory from code exploration:
+
+**Good examples:**
+- "From memory: We use RSpec for testing (fact #42)"
+- "According to earlier conversations: PostgreSQL is the primary database"
+- "From code exploration: Found 3 additional test frameworks in Gemfile"
+
+**Why this helps:** Clear attribution makes it easier to verify and explain facts.
+
+## Response Format
+
+Use structured language that makes facts extractable:
+
+**Technology choices:**
+- "This project uses [technology] for [purpose]"
+- "We chose [X] over [Y] because [reason]"
+
+**Architectural patterns:**
+- "The architecture follows [pattern]"
+- "Components communicate via [method]"
+
+**Rules and constraints:**
+- "Rule: [statement]"
+- "Constraint: [limitation]"
+- "Requirement: [need]"
+
+**Why this helps:** Structured statements are easier to parse and store.

data/skills/debug-memory/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: debug-memory
+description: Diagnose ClaudeMemory installation and configuration issues. Use when memory tools fail or setup seems broken.
+user_invocable: true
+---
+
+# Debug Memory Setup
+
+When invoked with `/debug-memory`, this skill runs comprehensive diagnostics on your ClaudeMemory installation.
+
+## What This Checks
+
+This skill will verify:
+- ✅ Database existence (global and project)
+- ✅ Schema version compatibility
+- ✅ Hook configuration
+- ✅ CLAUDE.md setup
+- ✅ Published snapshot status
+- ✅ MCP server connectivity
+- ✅ Recent ingest activity
+
+## Step 1: Run Setup Check
+
+First, check the memory system status using the MCP tool:
+
+```
+memory.check_setup
+```
+
+This returns:
+- **initialized**: true/false
+- **version**: ClaudeMemory version
+- **issues**: List of problems found
+- **recommendation**: Actionable next steps
+
+## Step 2: Analyze Results
+
+Based on the check results:
+
+### If initialized = true
+✅ System is healthy! Show the user:
+- Version information
+- Database stats
+- Last successful operations
+
+### If initialized = false
+⚠️ System needs setup. Check for:
+- **Missing database**: Run `claude-memory init`
+- **Missing CLAUDE.md**: Not importing memory snapshot
+- **Missing hooks**: Hooks not configured in settings.json
+- **Version mismatch**: Need to upgrade with `gem update claude-memory`
+
+## Step 3: Provide Recommendations
+
+Give the user clear next steps:
+
+**For missing setup:**
+```bash
+# Initialize ClaudeMemory
+claude-memory init
+
+# Or use the setup skill
+/setup-memory
+```
+
+**For configuration issues:**
+```bash
+# Check system health
+claude-memory doctor
+
+# View current status
+claude-memory status
+```
+
+**For version issues:**
+```bash
+# Upgrade to latest version
+gem update claude-memory
+claude-memory init  # Re-run init after upgrade
+```
+
+## Step 4: Verify Fix
+
+After user follows recommendations, run `memory.check_setup` again to confirm the issue is resolved.
+
+## Common Issues
+
+### "Database not found"
+- **Cause**: ClaudeMemory not initialized
+- **Fix**: Run `claude-memory init` or `/setup-memory`
+
+### "Hooks not configured"
+- **Cause**: `.claude/settings.json` missing hook definitions
+- **Fix**: Run `claude-memory init` to add hooks
+
+### "CLAUDE.md not importing snapshot"
+- **Cause**: Missing `@.claude/rules/claude_memory.generated.md` import
+- **Fix**: Add import to `.claude/CLAUDE.md`
+
+### "Version mismatch"
+- **Cause**: Old ClaudeMemory version installed
+- **Fix**: Run `gem update claude-memory`
+
+### "No recent ingest activity"
+- **Cause**: Hooks not triggering or failing silently
+- **Fix**: Check hook configuration with `claude-memory doctor`
+
+## Example Output
+
+```
+Running ClaudeMemory diagnostics...
+
+✅ Global database: healthy
+   - Location: ~/.claude/memory.sqlite3
+   - Schema: v7
+   - Facts: 42
+
+✅ Project database: healthy
+   - Location: .claude/memory.sqlite3
+   - Schema: v7
+   - Facts: 127
+   - Last ingest: 2026-01-29T21:47:41Z
+
+✅ Hooks: configured
+✅ Snapshot: published
+✅ CLAUDE.md: importing snapshot
+
+All systems operational! Memory is working correctly.
+```
+
+## When to Use This Skill
+
+Use `/debug-memory` when:
+- Memory tools are failing with errors
+- Unsure if ClaudeMemory is properly installed
+- Hooks don't seem to be running
+- Facts aren't being captured
+- After upgrading ClaudeMemory
+- Setting up a new project
+
+## Related Commands
+
+- `/setup-memory` - Install or upgrade ClaudeMemory
+- `claude-memory doctor` - CLI health check
+- `claude-memory status` - View system status
+- `memory.check_setup` - The underlying MCP tool

data/skills/memory-first-workflow/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: memory-first-workflow
+description: Workflow for checking memory before code exploration. Auto-loaded when answering questions about code, architecture, or patterns.
+user-invocable: false
+---
+
+# Memory-First Research Pattern
+
+When answering questions about code, architecture, patterns, decisions, or technical choices, follow this workflow:
+
+## Step 1: Query Memory First
+
+Before reading files or exploring code, check if memory already has the answer:
+
+```
+memory.recall "<topic>"
+```
+
+**Example queries:**
+- `memory.recall "authentication flow"`
+- `memory.recall "database choice"`
+- `memory.recall "error handling patterns"`
+
+## Step 2: Use Specialized Shortcuts
+
+For specific types of questions, use targeted memory tools:
+
+### Before Implementing Features
+```
+memory.decisions
+```
+Returns architectural decisions and constraints that may affect implementation.
+
+### Before Working with Frameworks/Databases
+```
+memory.architecture
+```
+Returns framework choices, database selection, and architectural patterns.
+
+### Before Writing Code
+```
+memory.conventions
+```
+Returns coding style, naming conventions, and project standards.
+
+### If Finding Contradictions
+```
+memory.conflicts
+```
+Returns open disputes that need resolution.
+
+## Step 3: Evaluate Memory Results
+
+**If memory has sufficient information:**
+- Answer using recalled facts
+- Cite fact IDs or sources: "From memory (fact #42): ..."
+- Avoid unnecessary file reads
+
+**If memory has partial information:**
+- Share what memory knows
+- Note what needs investigation: "Memory shows we use PostgreSQL, but I need to check the connection pooling setup..."
+- Proceed to file exploration for missing details
+
+**If memory has no information:**
+- Note explicitly: "Memory has no prior knowledge about [topic]"
+- Proceed to file exploration
+- After learning, consider if this should be stored in memory
+
+## Step 4: Explore Code (Only If Needed)
+
+When memory is insufficient, use file exploration tools:
+- `Read` for specific files
+- `Grep` for searching content
+- `Glob` for finding files by pattern
+- `Task` (Explore agent) for broad investigations
+
+## Step 5: Distinguish Sources
+
+When presenting findings, clearly separate:
+- **Recalled knowledge:** "From memory: We use RSpec for testing"
+- **Discovered information:** "From code exploration: Found additional test helper in `spec/support/`"
+
+## Why This Pattern Matters
+
+### Saves Time
+Memory provides instant access to distilled knowledge without re-reading hundreds of files.
+
+### Provides Context
+Past decisions, lessons learned, and rationale are preserved in memory.
+
+### Reduces Tokens
+Recalled facts are concise compared to reading entire files.
+
+### Ensures Consistency
+Prevents contradicting previous decisions or duplicating solved problems.
+
+### Improves Quality
+Understanding past context leads to better decisions aligned with project history.
+
+## Anti-Patterns to Avoid
+
+❌ **Don't skip memory checks:**
+```
+User: "What database do we use?"
+Bad: *immediately reads config files*
+Good: *checks memory.architecture first*
+```
+
+❌ **Don't assume memory is wrong:**
+```
+Bad: "Memory says PostgreSQL, let me verify by reading the config..."
+Good: "Memory says PostgreSQL. Need any specific config details?"
+```
+
+❌ **Don't ignore memory conflicts:**
+```
+Bad: *finds conflict, picks one arbitrarily*
+Good: "memory.conflicts shows authentication method disputed—let me investigate and resolve"
+```
+
+## Example Workflow
+
+**User asks:** "How do we handle errors in API responses?"
+
+**Step 1:** Check memory
+```
+memory.recall "error handling API"
+memory.conventions
+```
+
+**Step 2:** Evaluate results
+- Memory shows: "Convention: API errors return JSON with `error` and `message` keys"
+- Memory shows: "Decision: 4xx for client errors, 5xx for server errors"
+
+**Step 3:** Answer with citations
+"From memory: We handle API errors by returning JSON with `error` and `message` keys. Client errors use 4xx status codes, server errors use 5xx. Is there a specific error case you're working with?"
+
+**Step 4:** Only if needed, explore code
+If user asks: "Show me the error middleware"
+*Then* use Read/Grep to find the implementation.
+
+---
+
+This workflow is automatically loaded when you ask technical questions. You don't need to invoke it manually—it guides Claude's research process behind the scenes.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: claude_memory
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Valentino Stoll
@@ -49,24 +49,27 @@ files:
 - ".claude-plugin/marketplace.json"
 - ".claude-plugin/plugin.json"
 - ".claude.json"
-- ".claude/.mind.mv2.o2N83S"
 - ".claude/CLAUDE.md"
 - ".claude/output-styles/memory-aware.md"
 - ".claude/rules/claude_memory.generated.md"
 - ".claude/settings.json"
 - ".claude/settings.local.json"
+- ".claude/skills/check-memory/DEPRECATED.md"
 - ".claude/skills/check-memory/SKILL.md"
+- ".claude/skills/debug-memory"
 - ".claude/skills/improve/SKILL.md"
 - ".claude/skills/improve/feature-patterns.md"
+- ".claude/skills/memory-first-workflow"
 - ".claude/skills/quality-update/SKILL.md"
 - ".claude/skills/quality-update/implementation-guide.md"
 - ".claude/skills/review-commit/SKILL.md"
 - ".claude/skills/review-for-quality/SKILL.md"
 - ".claude/skills/review-for-quality/expert-checklists.md"
-- ".claude/skills/setup-memory/SKILL.md"
+- ".claude/skills/setup-memory"
 - ".claude/skills/study-repo/SKILL.md"
 - ".claude/skills/study-repo/analysis-template.md"
 - ".claude/skills/study-repo/focus-examples.md"
+- ".lefthook/map_specs.rb"
 - ".ruby-version"
 - CHANGELOG.md
 - CLAUDE.md
@@ -74,6 +77,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- WEEK2_COMPLETE.md
 - commands/analyze.md
 - commands/recall.md
 - commands/remember.md
@@ -84,7 +88,6 @@ files:
 - db/migrations/005_add_incremental_sync.rb
 - db/migrations/006_add_operation_tracking.rb
 - db/migrations/007_add_ingestion_metrics.rb
-- docs/.claude/mind.mv2.lock
 - docs/EXAMPLES.md
 - docs/GETTING_STARTED.md
 - docs/RELEASE_NOTES_v0.2.0.md
@@ -92,7 +95,11 @@ files:
 - docs/SOCIAL_MEDIA_v0.2.0.md
 - docs/architecture.md
 - docs/auto_init_design.md
+- docs/ci_integration.md
 - docs/demo.md
+- docs/eval_week1_summary.md
+- docs/eval_week2_summary.md
+- docs/evals.md
 - docs/expert_review.md
 - docs/improvements.md
 - docs/influence/.gitkeep
@@ -171,6 +178,7 @@ files:
 - lib/claude_memory/domain/entity.rb
 - lib/claude_memory/domain/fact.rb
 - lib/claude_memory/domain/provenance.rb
+- lib/claude_memory/embeddings/fastembed_adapter.rb
 - lib/claude_memory/embeddings/generator.rb
 - lib/claude_memory/embeddings/similarity.rb
 - lib/claude_memory/hook/exit_codes.rb
@@ -207,9 +215,13 @@ files:
 - lib/claude_memory/templates/hooks.example.json
 - lib/claude_memory/templates/output-styles/memory-aware.md
 - lib/claude_memory/version.rb
+- output-styles/memory-aware.md
 - sig/claude_memory.rbs
 - skills/analyze/SKILL.md
+- skills/debug-memory/SKILL.md
+- skills/memory-first-workflow/SKILL.md
 - skills/memory/SKILL.md
+- skills/setup-memory/SKILL.md
 homepage: https://github.com/codenamev/claude_memory
 licenses:
 - MIT

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

@@ -1,21 +0,0 @@
----
-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