claude_memory 0.1.0

data/README.md

@@ -0,0 +1,212 @@
+# ClaudeMemory
+
+Turn-key Ruby gem providing Claude Code with instant, high-quality, long-term, self-managed memory using **Claude Code Hooks + MCP + Output Style**, with minimal dependencies (SQLite by default).
+
+## Features
+
+- **Automated ingestion**: Claude Code hooks trigger delta-based transcript ingestion
+- **Claude-powered fact extraction**: Uses Claude's own intelligence to extract facts (no API key needed)
+- **Truth maintenance**: Deterministic conflict/supersession resolution
+- **Full-text search**: SQLite FTS5 for fast recall without embeddings
+- **MCP integration**: Memory tools accessible directly in Claude Code
+- **Snapshot publishing**: Curated memory files for Claude Code's built-in system
+- **Claude Code Plugin**: Install as a plugin for seamless integration
+
+## Installation
+
+```bash
+gem install claude_memory
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'claude_memory'
+```
+
+## Quick Start
+
+```bash
+# Initialize in your project (project-local)
+cd your-project
+claude-memory init
+
+# Or install globally for all projects
+claude-memory init --global
+
+# Verify setup
+claude-memory doctor
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `init` | Initialize ClaudeMemory in a project |
+| `db:init` | Initialize the SQLite database |
+| `ingest` | Ingest transcript delta |
+| `hook ingest` | Hook entrypoint for ingest (reads stdin JSON) |
+| `hook sweep` | Hook entrypoint for sweep (reads stdin JSON) |
+| `hook publish` | Hook entrypoint for publish (reads stdin JSON) |
+| `search` | Search indexed content |
+| `recall` | Recall facts matching a query |
+| `explain` | Explain a fact with provenance receipts |
+| `conflicts` | Show open conflicts |
+| `changes` | Show recent fact changes |
+| `publish` | Publish snapshot to Claude Code memory |
+| `sweep` | Run maintenance/pruning |
+| `serve-mcp` | Start MCP server for Claude Code |
+| `doctor` | Check system health |
+
+## Usage Examples
+
+### Ingest Content
+
+```bash
+claude-memory ingest \
+  --source claude_code \
+  --session-id sess-123 \
+  --transcript-path ~/.claude/projects/myproject/transcripts/latest.jsonl
+```
+
+### Recall Facts
+
+```bash
+claude-memory recall "database"
+# Returns facts + provenance receipts
+
+claude-memory recall "database" --scope project
+# Only facts scoped to current project
+
+claude-memory recall "preferences" --scope global
+# Only global facts (apply to all projects)
+
+claude-memory explain 42
+# Detailed explanation with supersession/conflict links
+```
+
+### Publish Snapshot
+
+```bash
+# Publish to .claude/rules/ (shared, default)
+claude-memory publish
+
+# Publish to local file (not committed)
+claude-memory publish --mode local
+
+# Publish to user home directory
+claude-memory publish --mode home
+```
+
+### MCP Tools
+
+When configured, these tools are available in Claude Code:
+
+- `memory.recall` - Search for relevant facts (supports scope filtering)
+- `memory.explain` - Get detailed fact provenance
+- `memory.promote` - Promote a project fact to global memory
+- `memory.store_extraction` - Store extracted facts from a conversation
+- `memory.changes` - Recent fact updates
+- `memory.conflicts` - Open contradictions
+- `memory.sweep_now` - Run maintenance
+- `memory.status` - System health check
+
+## Scope: Global vs Project
+
+Facts are scoped to control where they apply:
+
+| Scope | Description | Example |
+|-------|-------------|---------|
+| `project` | Applies only to the current project | "This app uses PostgreSQL" |
+| `global` | Applies across all projects | "I prefer 4-space indentation" |
+
+**Automatic detection**: The distiller recognizes signals like "always", "in all projects", or "my preference" and sets `scope_hint: "global"`.
+
+**Manual promotion**: Use `memory.set_scope` in Claude Code or the user can say "make that preference global" and Claude will call the tool.
+
+## Claude Code Plugin
+
+ClaudeMemory is available as a Claude Code plugin for seamless integration.
+
+### Install as Plugin
+
+```bash
+# Add the marketplace
+/plugin marketplace add /path/to/claude_memory
+
+# Install the plugin
+/plugin install claude-memory
+```
+
+### Plugin Components
+
+| Component | Description |
+|-----------|-------------|
+| **MCP Server** | Exposes memory tools to Claude |
+| **Hooks** | Automatic ingestion, extraction, and publishing |
+| **Skill** | `/memory` command for manual interaction |
+
+### How Claude-Powered Extraction Works
+
+ClaudeMemory uses **prompt hooks** to leverage Claude's own intelligence for fact extraction—no separate API key required:
+
+1. **On session stop**: A prompt hook asks Claude to review what it learned
+2. **Claude extracts facts**: Using its understanding of the conversation, Claude identifies durable facts
+3. **Stores via MCP**: Claude calls `memory.store_extraction` to persist the facts
+4. **Truth maintenance**: The resolver handles conflicts and supersession automatically
+
+This approach means:
+- ✅ No API key configuration needed
+- ✅ Uses Claude's full contextual understanding
+- ✅ Extracts only genuinely useful, durable facts
+- ✅ Respects scope (project vs global)
+
+### Fact Types Extracted
+
+| Predicate | Description | Example |
+|-----------|-------------|---------|
+| `uses_database` | Database technology | "PostgreSQL" |
+| `uses_framework` | Framework choice | "Rails", "React" |
+| `deployment_platform` | Where deployed | "Vercel", "AWS" |
+| `convention` | Coding standards | "4-space indentation" |
+| `decision` | Architectural choice | "Use microservices" |
+| `auth_method` | Authentication approach | "JWT tokens" |
+
+## Architecture
+
+```
+Transcripts → Ingest → FTS Index
+                    ↓
+        Claude Prompt Hook → Extract entities/facts/signals
+                    ↓
+         memory.store_extraction (MCP)
+                    ↓
+              Resolve → Truth maintenance (conflicts/supersession)
+                    ↓
+              Store → SQLite (facts, provenance, entities, scope)
+                    ↓
+              Publish → .claude/rules/claude_memory.generated.md
+```
+
+## Configuration
+
+The database location defaults to `.claude_memory.sqlite3` in the project root.
+
+Override with `--db PATH` on any command.
+
+## Development
+
+```bash
+git clone https://github.com/codenamev/claude_memory
+cd claude_memory
+bin/setup
+bundle exec rspec
+```
+
+## License
+
+MIT License - see [LICENSE.txt](LICENSE.txt)
+
+## Contributing
+
+Bug reports and pull requests welcome at https://github.com/codenamev/claude_memory

data/Rakefile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "standard/rake"
+
+task default: %i[spec standard]

data/commands/analyze.md

@@ -0,0 +1,29 @@
+---
+description: Analyze project and store facts in memory
+disable-model-invocation: true
+---
+
+Analyze this project to understand its tech stack, frameworks, tools, and conventions.
+
+## Steps
+
+1. Read key project files (if they exist):
+   - `Gemfile`, `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`
+   - `README.md`, `tsconfig.json`, `Dockerfile`
+   - `.eslintrc*`, `.prettierrc*`, `.rubocop.yml`, `.standard.yml`
+   - `.github/workflows/*.yml`
+
+2. Extract facts about:
+   - Languages (Ruby, TypeScript, Python, Go, Rust)
+   - Frameworks (Rails, React, Next.js, Django, FastAPI)
+   - Tools (RSpec, Jest, ESLint, Prettier, Docker)
+   - Databases (PostgreSQL, MySQL, Redis, MongoDB)
+   - Package managers (Bundler, npm, pnpm, Poetry, Cargo)
+   - CI/CD (GitHub Actions, CircleCI, GitLab CI)
+
+3. Use `memory.store_extraction` to store facts with:
+   - Appropriate entity types and predicates
+   - Quotes referencing the source file/line
+   - `strength: "stated"` for explicit declarations
+
+4. Report what you learned and stored.

data/commands/recall.md

@@ -0,0 +1,17 @@
+---
+description: Recall what you know about this project
+disable-model-invocation: true
+---
+
+Recall facts stored in memory about this project.
+
+Use `memory.recall` to search for relevant facts. Try queries like:
+- "uses" - to find tech stack facts
+- "framework" - to find framework choices
+- "database" - to find database facts
+- "tool" - to find tooling facts
+- "convention" - to find coding conventions
+
+Summarize what you know about this project's tech stack and conventions.
+
+$ARGUMENTS

data/commands/remember.md

@@ -0,0 +1,26 @@
+---
+description: Store something in memory
+disable-model-invocation: true
+argument-hint: [what to remember]
+---
+
+Store the following in memory using `memory.store_extraction`:
+
+$ARGUMENTS
+
+## Guidelines
+
+1. Choose appropriate entity types:
+   - `database`, `framework`, `language`, `platform`, `tool`, `convention`
+
+2. Choose appropriate predicates:
+   - `uses_database`, `uses_framework`, `uses_language`, `uses_tool`
+   - `has_convention`, `prefers`, `decision`
+
+3. Set scope:
+   - Use `scope_hint: "global"` if the user says this applies to all projects
+   - Use `scope_hint: "project"` (default) for project-specific facts
+
+4. Include the user's statement as the `quote` for provenance.
+
+5. Confirm what was stored.

data/docs/demo.md

@@ -0,0 +1,126 @@
+# Claude Memory Demo
+
+This document walks through a complete end-to-end demo of ClaudeMemory.
+
+## Setup
+
+```bash
+# Install the gem
+gem install claude_memory
+
+# Initialize in your project
+cd your-project
+claude-memory init
+```
+
+## Ingest Some Content
+
+Create a sample transcript:
+
+```bash
+echo '{"type":"message","content":"We decided to use PostgreSQL for the database."}
+{"type":"message","content":"Convention: Always use snake_case for variable names."}
+{"type":"message","content":"We are deploying to AWS using Terraform."}' > /tmp/demo_transcript.jsonl
+```
+
+Ingest it:
+
+```bash
+claude-memory ingest \
+  --source claude_code \
+  --session-id demo-session \
+  --transcript-path /tmp/demo_transcript.jsonl
+```
+
+## Distill and Resolve Facts
+
+The distiller extracts structured facts from raw content:
+
+```bash
+# Search the indexed content
+claude-memory search "PostgreSQL"
+
+# Check for conflicts
+claude-memory conflicts
+```
+
+## Recall Facts
+
+Query the memory:
+
+```bash
+# Recall facts about databases
+claude-memory recall "database"
+
+# Explain a specific fact
+claude-memory explain 1
+```
+
+## Publish Snapshot
+
+Generate a snapshot for Claude Code:
+
+```bash
+claude-memory publish
+
+# Check the generated file
+cat .claude/rules/claude_memory.generated.md
+```
+
+## Maintenance
+
+Run periodic maintenance:
+
+```bash
+# Run sweep with 5-second budget
+claude-memory sweep --budget 5
+
+# Check system status via MCP
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"memory.status","arguments":{}}}' | \
+  claude-memory serve-mcp
+```
+
+## Verify Setup
+
+```bash
+claude-memory doctor
+```
+
+## Full Loop with Claude Code
+
+1. Configure hooks (from `claude-memory init` output)
+2. Configure MCP server
+3. Start using Claude Code normally
+4. Hooks automatically ingest transcripts
+5. Use MCP tools like `memory.recall` in your prompts
+6. Run `claude-memory publish` periodically to update snapshot
+
+## Example: Detecting Conflicts
+
+```bash
+# First statement
+echo '{"type":"message","content":"We use MySQL for the database."}' > /tmp/t1.jsonl
+claude-memory ingest --source claude_code --session-id s1 --transcript-path /tmp/t1.jsonl
+
+# Contradicting statement without supersession
+echo '{"type":"message","content":"We use PostgreSQL for the database."}' > /tmp/t2.jsonl
+claude-memory ingest --source claude_code --session-id s2 --transcript-path /tmp/t2.jsonl
+
+# This would create a conflict (requires distill+resolve which needs LLM in full version)
+claude-memory conflicts
+```
+
+## Example: Supersession
+
+```bash
+# Original decision
+echo '{"type":"message","content":"We decided to use MySQL."}' > /tmp/t1.jsonl
+claude-memory ingest --source claude_code --session-id s1 --transcript-path /tmp/t1.jsonl
+
+# Superseding decision with explicit signal
+echo '{"type":"message","content":"We no longer use MySQL, switching to PostgreSQL."}' > /tmp/t2.jsonl
+claude-memory ingest --source claude_code --session-id s2 --transcript-path /tmp/t2.jsonl
+
+# Check recent changes
+claude-memory changes --since 2024-01-01
+```

data/docs/organizational_memory_playbook.md

@@ -0,0 +1,291 @@
+# **Organizational Memory: Axioms, Formulae, and Scale Playbook**
+
+*A north star for building, evaluating, or reasoning about org-memory systems.*
+
+---
+
+## I. Core Premise
+
+> **When implementation becomes cheap, meaning becomes the bottleneck.**
+
+Modern teams no longer fail because they cannot build fast enough.
+They fail because they cannot **remember why they built what they built**.
+
+Organizational memory is not storage.
+It is the system that preserves **decision-quality over time**.
+
+---
+
+## II. Foundational Axioms
+
+### **Axiom 1: Code is no longer the primary artifact**
+
+The primary artifact is the **decision**.
+
+Code is a consequence of decisions.
+Tests, reviews, and conversations encode intent more faithfully than the final diff.
+
+---
+
+### **Axiom 2: Truth is temporal**
+
+There is no permanent truth.
+
+Only:
+
+> *What was believed to be true, by whom, at a given time.*
+
+Any system that cannot answer *“when was this true?”* will hallucinate certainty.
+
+---
+
+### **Axiom 3: Memory without resolution becomes noise**
+
+Captured information increases entropy unless conflicts are resolved.
+
+Storing more ≠ knowing more.
+
+Resolution creates signal.
+
+---
+
+### **Axiom 4: Provenance outweighs content**
+
+A weak fact with strong provenance is more valuable than a strong claim with no source.
+
+Who said it, when, and with what authority matters more than phrasing.
+
+---
+
+### **Axiom 5: Meaning must be captured at the moment of action**
+
+Reconstruction after the fact is lossy.
+
+If memory is not embedded in the execution path, it decays immediately.
+
+---
+
+## III. Primitive Building Blocks
+
+### **1. Fact (Temporal)**
+
+```
+(subject, predicate, object,
+ valid_from, valid_to,
+ source, confidence)
+```
+
+Facts are intervals, not fields.
+
+---
+
+### **2. Decision**
+
+```
+(action,
+ context,
+ alternatives,
+ rationale,
+ approver,
+ time,
+ outcome)
+```
+
+If “because” cannot be answered, the decision is incomplete.
+
+---
+
+### **3. Trace (Because Graph)**
+
+Edges matter more than nodes.
+
+* evidence → rationale
+* rationale → decision
+* decision → action
+* policy(version) → constraint
+* approver → authorization
+
+No edges = folklore.
+
+---
+
+### **4. Status**
+
+Every belief must be one of:
+
+* current
+* superseded
+* disputed
+
+If none apply, the system is lying.
+
+---
+
+## IV. Core Formulae
+
+### **1. Organizational Memory Value**
+
+Let:
+
+* **R** = rework avoided
+* **O** = onboarding acceleration
+* **D** = decision-quality improvement
+* **A** = adoption rate (0–1)
+* **C** = system cost
+* **P** = risk cost (privacy, error, misuse)
+
+[
+\text{Memory Value} =
+A \cdot (R + O + \lambda D) - (C + P)
+]
+
+If adoption is near zero, value is near zero regardless of intelligence.
+
+---
+
+### **2. Temporal Truth Resolution**
+
+At time **t**:
+
+[
+Truth(t) =
+\arg\max_{claims}
+(confidence \times authority(source))
+]
+
+subject to:
+
+[
+valid_from \le t < valid_to
+]
+
+Truth is **time-sliced and source-weighted**.
+
+---
+
+### **3. Signal-to-Entropy Ratio**
+
+[
+SER = \frac{\text{Resolved Decisions}}{\text{Captured Artifacts}}
+]
+
+Healthy systems increase SER over time.
+
+Wikis decay. Memory systems must sharpen.
+
+---
+
+## V. Scale Playbook
+
+### **Scale 1: Individual or Tiny Team (1–5)**
+
+**Goal:** Stop losing important decisions.
+
+**Characteristics**
+
+* Low conflict
+* High context sharing
+* Minimal governance
+
+**Do**
+
+* Capture PRs, LLM sessions, key discussions
+* Distill into:
+
+  * Decision
+  * Learning
+  * Open Question
+* Append-only with timestamps
+
+**Avoid**
+
+* Complex ontologies
+* Automatic resolution
+* Over-structuring
+
+**Failure Mode**
+
+* Memory becomes a diary, not a tool
+
+---
+
+### **Scale 2: Team / Org (5–50)**
+
+**Goal:** Prevent contradictions from compounding.
+
+**Add**
+
+* Supersedes links
+* Decision status (current / superseded / disputed)
+* Authority weighting
+* Policy versioning
+
+**Key Question**
+
+> “Which belief is currently in force?”
+
+**Failure Mode**
+
+* Two truths exist and no one knows which one applies
+
+---
+
+### **Scale 3: Organization / Enterprise (50+)**
+
+**Goal:** Make memory unavoidable.
+
+**Add**
+
+* Event logs of actions
+* Mandatory capture points
+* Approval instrumentation
+* Audit-friendly traces
+
+**Rule**
+
+> If it materially affects the business, it must be captured at execution time.
+
+**Failure Mode**
+
+* Post-hoc archaeology
+* Compliance theater
+* Memory drift between teams
+
+---
+
+## VI. What This System Delivers
+
+| Recipient    | Value                              |
+| ------------ | ---------------------------------- |
+| Engineers    | Less rework, faster onboarding     |
+| Product      | Clear rationale, fewer regressions |
+| Leadership   | Decision continuity                |
+| AI agents    | Grounded reasoning                 |
+| Organization | Institutional durability           |
+
+---
+
+## VII. The North Star Question
+
+Every org-memory system must answer, clearly and reliably:
+
+> **“Why are we the way we are right now?”**
+
+If it cannot answer that question:
+
+* confidently
+* temporally
+* with provenance
+
+…it is not memory.
+It is storage wearing a lab coat.
+
+---
+
+## VIII. Final Reduction
+
+If all of this collapses into one sentence:
+
+> **Organizational memory exists to preserve decision-quality across time, scale, and personnel change.**
+
+Everything else is implementation detail.