claude-plugin-contextfs 0.2.15

package/README.md

@@ -0,0 +1,102 @@
+# ContextFS Plugin for Claude Code
+
+Persistent memory management for Claude Code - save, search, and recall context across sessions.
+
+## Features
+
+- **Persistent Memory**: Save decisions, procedures, errors, and facts to long-term storage
+- **Semantic Search**: Find relevant memories using hybrid keyword + semantic search
+- **Session Management**: Automatically save and restore session context
+- **Cross-Repo Support**: Share knowledge across multiple repositories
+- **MCP Integration**: Full MCP server with 15+ tools
+
+## Installation
+
+### Option 1: Install via Claude Plugin Registry
+
+```bash
+claude plugin add contextfs
+```
+
+### Option 2: Install via npm
+
+```bash
+npm install -g claude-plugin-contextfs
+claude plugin add claude-plugin-contextfs
+```
+
+### Option 3: Install via ContextFS CLI (Recommended)
+
+```bash
+# Install ContextFS
+pip install contextfs
+
+# Install Claude Code integration
+contextfs install claude
+```
+
+## Prerequisites
+
+The plugin requires the ContextFS Python package to be installed:
+
+```bash
+pip install contextfs
+```
+
+## Usage
+
+### Starting the MCP Server
+
+Before using the plugin, start the MCP server:
+
+```bash
+contextfs server
+```
+
+### Available Skills
+
+- **/remember** - Extract and save important information from conversations
+- **/recall** - Search memories for relevant context
+
+### Available MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `contextfs_save` | Save a new memory |
+| `contextfs_search` | Search memories using hybrid search |
+| `contextfs_recall` | Get a specific memory by ID |
+| `contextfs_list` | List recent memories |
+| `contextfs_evolve` | Update a memory with version history |
+| `contextfs_link` | Create relationships between memories |
+| `contextfs_delete` | Delete a memory |
+| `contextfs_sessions` | List recent sessions |
+| `contextfs_load_session` | Load a session's messages |
+
+### Hooks
+
+The plugin includes automatic hooks:
+
+- **SessionStart**: Auto-recall relevant memories for current project
+- **Stop**: Extract and save important information from the session
+- **PreCompact**: Save session before context compaction
+
+## Memory Types
+
+| Type | Use Case |
+|------|----------|
+| `fact` | Learned information about codebase/user |
+| `decision` | Architectural/design decisions with rationale |
+| `procedural` | Step-by-step workflows and procedures |
+| `error` | Errors encountered and their solutions |
+| `code` | Code snippets and patterns |
+| `episodic` | Session summaries |
+
+## Links
+
+- [ContextFS Documentation](https://github.com/magneticion/contextfs)
+- [MCP Server Documentation](https://github.com/magneticion/contextfs#mcp-server)
+- [Claude Code Plugins](https://claude-plugins.dev/)
+
+## License
+
+MIT

package/agents/memory-extractor.md

@@ -0,0 +1,124 @@
+# Memory Extractor Agent
+
+Automatically extract and save important information from conversations to ContextFS.
+
+## Agent Configuration
+
+```yaml
+name: memory-extractor
+description: Extracts decisions, facts, errors, and procedures from conversations and saves to ContextFS
+model: haiku  # Fast model for extraction
+tools:
+  - mcp__contextfs__contextfs_save
+  - mcp__contextfs__contextfs_search
+  - mcp__contextfs__contextfs_evolve
+  - mcp__contextfs__contextfs_link
+```
+
+## System Prompt
+
+You are a memory extraction specialist. Your job is to analyze conversations and extract valuable information for long-term storage in ContextFS.
+
+### TYPE-SAFE Memory Operations
+
+**CRITICAL: Some types REQUIRE structured_data with specific fields.**
+
+| Type | Required Fields |
+|------|-----------------|
+| `decision` | `decision`, `rationale`, `alternatives[]` |
+| `procedural` | `steps[]` |
+| `error` | `error_type`, `message`, `resolution` |
+
+| Type | No structured_data required |
+|------|----------------------------|
+| `fact` | Learned information |
+| `code` | Code snippets |
+| `episodic` | Session summaries |
+
+### Extraction Examples
+
+**1. Decision (REQUIRED structured_data)**
+```python
+contextfs_save(
+    type="decision",
+    summary="Redis chosen for session storage",
+    content="Session storage: Use Redis instead of PostgreSQL",
+    tags=["decision", "redis", "session", "architecture"],
+    structured_data={
+        "decision": "Use Redis for session storage",         # REQUIRED
+        "rationale": "Sub-millisecond latency for auth",     # REQUIRED
+        "alternatives": ["PostgreSQL", "Memcached"]          # REQUIRED
+    }
+)
+```
+
+**2. Error (REQUIRED structured_data)**
+```python
+contextfs_save(
+    type="error",
+    summary="CORS policy blocked request",
+    content="Error: CORS policy blocked request from localhost:3000",
+    tags=["error", "cors", "frontend"],
+    structured_data={
+        "error_type": "CORSError",                           # REQUIRED
+        "message": "CORS policy blocked request",            # REQUIRED
+        "resolution": "Add proxy config to package.json"     # REQUIRED
+    }
+)
+```
+
+**3. Procedural (REQUIRED structured_data with steps[])**
+```python
+contextfs_save(
+    type="procedural",
+    summary="Deploy to production",
+    content="Production deployment procedure",
+    tags=["procedure", "deploy", "production"],
+    structured_data={
+        "title": "Production Deployment",
+        "steps": [                                           # REQUIRED
+            "Run tests locally",
+            "Build Docker image",
+            "Push to registry",
+            "Deploy via Railway"
+        ],
+        "prerequisites": ["Docker", "Railway CLI"]
+    }
+)
+```
+
+**4. Fact (no structured_data required)**
+```python
+contextfs_save(
+    type="fact",
+    summary="API uses JWT with 1hr expiry",
+    content="The auth system uses JWT tokens with 1hr expiry, refresh tokens last 7 days",
+    tags=["fact", "auth", "jwt"]
+)
+```
+
+### Extraction Rules
+
+1. **Search before saving** - Always check if similar memory exists
+2. **Evolve don't duplicate** - Use `contextfs_evolve` for updates
+3. **Be concise** - Extract essence, not verbatim conversation
+4. **Add context** - Include why information matters
+5. **Tag appropriately** - Use consistent, searchable tags
+6. **Link related** - Connect new memories to existing ones
+7. **Use correct structured_data** - Decision/error/procedural REQUIRE it
+
+### Output Format
+
+For each extracted memory, report:
+- Type and summary
+- Tags applied
+- Whether it's new or evolved from existing
+- Memory ID for reference
+
+## Invocation
+
+This agent should be invoked:
+1. At session end (via Stop hook)
+2. Via `/remember` command
+3. Periodically during long sessions
+4. Before context compaction

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "claude-plugin-contextfs",
+  "version": "0.2.15",
+  "description": "ContextFS memory management plugin for Claude Code - persistent memory across sessions",
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "contextfs",
+    "memory",
+    "mcp",
+    "ai",
+    "context",
+    "persistent-memory"
+  ],
+  "author": "Matthew Long <matthew@yonedaai.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/magneticion/contextfs",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/magneticion/contextfs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/magneticion/contextfs/issues"
+  },
+  "files": [
+    "skills/**/*",
+    "agents/**/*",
+    "plugin.json",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/plugin.json

@@ -0,0 +1,62 @@
+{
+  "name": "contextfs",
+  "version": "0.2.15",
+  "description": "Persistent memory management for Claude Code - save, search, and recall context across sessions",
+  "author": "Matthew Long",
+  "homepage": "https://github.com/magneticion/contextfs",
+  "skills": [
+    "skills/remember.md",
+    "skills/recall.md"
+  ],
+  "agents": [
+    "agents/memory-extractor.md"
+  ],
+  "mcpServers": {
+    "contextfs": {
+      "type": "sse",
+      "url": "http://127.0.0.1:3000/mcp/sse",
+      "description": "ContextFS MCP server - start with 'contextfs server'"
+    }
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python -m contextfs.cli memory auto-recall --quiet"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python -m contextfs.cli memory extract-transcript --save --quiet"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python -m contextfs.cli memory save-session --label 'pre-compact' --quiet"
+          }
+        ]
+      }
+    ]
+  },
+  "requirements": {
+    "python": ">=3.10",
+    "packages": [
+      "contextfs"
+    ]
+  }
+}

package/skills/recall.md

@@ -0,0 +1,127 @@
+# Recall - Search and Load Relevant Context
+
+Search ContextFS memory for relevant context based on the current task or query.
+
+## Available Tools
+
+| Tool | Purpose |
+|------|---------|
+| `contextfs_search` | Hybrid semantic + keyword search |
+| `contextfs_sessions` | List recent sessions |
+| `contextfs_load_session` | Load session messages |
+| `contextfs_recall` | Get specific memory by ID |
+| `contextfs_list` | List recent memories |
+
+---
+
+## Search Strategy
+
+### If Starting a New Task
+- Search for prior work on the same topic
+- Search for relevant decisions and procedures
+- Search for known errors and solutions
+
+### If Debugging
+- Search for similar errors (type="error")
+- Search for related code patterns
+- Search for prior debugging sessions
+
+### If Exploring Code
+- Search for architectural decisions (type="decision")
+- Search for code patterns (type="code")
+- Search for API documentation (type="api")
+
+---
+
+## Search Patterns
+
+### General Search
+```python
+contextfs_search(
+    query="<topic or task>",
+    limit=5,
+    cross_repo=True  # Search across all repositories
+)
+```
+
+### Type-Filtered Search
+```python
+# Find decisions
+contextfs_search(query="<topic>", type="decision", limit=3)
+
+# Find errors and solutions
+contextfs_search(query="<error or symptom>", type="error", limit=5)
+
+# Find procedures
+contextfs_search(query="<workflow>", type="procedural", limit=3)
+
+# Find code patterns
+contextfs_search(query="<pattern>", type="code", limit=5)
+```
+
+### Project-Scoped Search
+```python
+contextfs_search(
+    query="<topic>",
+    project="my-project",  # Filter by project
+    limit=5
+)
+```
+
+---
+
+## Session Management
+
+### List Recent Sessions
+```python
+contextfs_sessions(limit=5, label="<optional filter>")
+```
+
+### Load Specific Session
+```python
+contextfs_load_session(session_id="<id>", max_messages=20)
+```
+
+---
+
+## Get Specific Memory
+```python
+# Recall by ID (can use partial ID, min 8 chars)
+contextfs_recall(id="abc12345")
+```
+
+---
+
+## Output
+
+Present findings organized by relevance:
+
+1. **Most Relevant Memories** - Direct matches to the query
+2. **Related Decisions** - Prior decisions that may affect current work
+3. **Known Issues** - Errors and solutions that may be relevant
+4. **Procedures to Follow** - Established workflows for similar tasks
+
+Include memory IDs for reference so user can request more details.
+
+---
+
+## Example Usage
+
+User: "I need to work on the authentication system"
+
+Searches to run:
+```python
+# General search
+contextfs_search(query="authentication system", limit=5, cross_repo=True)
+
+# Decisions about auth
+contextfs_search(query="auth", type="decision", limit=3)
+
+# Known auth errors
+contextfs_search(query="auth login", type="error", limit=3)
+
+# Auth procedures
+contextfs_search(query="authentication", type="procedural", limit=2)
+```
+
+Then synthesize findings into actionable context.

package/skills/remember.md

@@ -0,0 +1,134 @@
+# Remember - Save Conversation Insights to Memory
+
+Extract and save important information from this conversation to ContextFS long-term memory.
+
+## TYPE-SAFE Memory Operations
+
+**CRITICAL: Some types REQUIRE structured_data with specific fields.**
+
+### Types WITH Required structured_data
+
+| Type | Required Fields |
+|------|-----------------|
+| `decision` | `decision`, `rationale`, `alternatives[]` |
+| `procedural` | `steps[]` (title, prerequisites optional) |
+| `error` | `error_type`, `message`, `resolution` |
+| `api` | `endpoint`, `method` |
+| `config` | `name`, `settings{}` |
+
+### Types WITHOUT Required structured_data
+
+| Type | Use Case |
+|------|----------|
+| `fact` | Learned information about codebase/user |
+| `episodic` | Session summaries, conversations |
+| `code` | Code snippets, patterns |
+| `user` | User preferences |
+
+---
+
+## Extraction Categories
+
+### 1. Decisions Made (REQUIRED: structured_data)
+```python
+contextfs_save(
+    type="decision",
+    summary="Chose PostgreSQL over MongoDB",
+    content="Full rationale and context...",
+    tags=["decision", "<topic>"],
+    structured_data={
+        "decision": "Use PostgreSQL for user data",      # REQUIRED
+        "rationale": "Team expertise, ACID compliance",  # REQUIRED
+        "alternatives": ["MongoDB", "DynamoDB"]          # REQUIRED
+    }
+)
+```
+
+### 2. Errors and Solutions (REQUIRED: structured_data)
+```python
+contextfs_save(
+    type="error",
+    summary="ChromaDB collection not found",
+    content="Full error context and stack trace...",
+    tags=["error", "<technology>"],
+    structured_data={
+        "error_type": "CollectionNotFoundError",  # REQUIRED
+        "message": "Collection does not exist",   # REQUIRED
+        "resolution": "Reconnect MCP server"      # REQUIRED
+    }
+)
+```
+
+### 3. Procedures (REQUIRED: structured_data with steps[])
+```python
+contextfs_save(
+    type="procedural",
+    summary="Deploy to Railway",
+    content="Detailed deployment procedure...",
+    tags=["procedure", "<topic>"],
+    structured_data={
+        "title": "Railway Deployment",                                    # optional
+        "steps": ["Build Docker", "Push to registry", "Redeploy"],        # REQUIRED
+        "prerequisites": ["Docker installed", "Railway CLI configured"]   # optional
+    }
+)
+```
+
+### 4. Facts Learned (no structured_data required)
+```python
+contextfs_save(
+    type="fact",
+    summary="API uses JWT auth with 1hr expiry",
+    content="The auth system uses JWT tokens...",
+    tags=["fact", "<topic>"]
+)
+```
+
+### 5. Code Patterns (no structured_data required)
+```python
+contextfs_save(
+    type="code",
+    summary="Auth middleware pattern",
+    content="```python\ndef auth_middleware():\n    ...\n```",
+    tags=["code", "<language>", "<pattern>"]
+)
+```
+
+---
+
+## Execution Steps
+
+1. **Review the conversation** - Identify all memorable content
+
+2. **Search before saving** - Check for duplicates:
+   ```python
+   contextfs_search(query="<topic>", limit=3)
+   ```
+
+3. **Evolve don't duplicate** - If similar memory exists, update it:
+   ```python
+   contextfs_evolve(memory_id="<existing_id>", new_content="Updated info...")
+   ```
+
+4. **Save new memories** - Use appropriate type WITH required structured_data
+
+5. **Link related memories** - Connect to existing context:
+   ```python
+   contextfs_link(from_id="<new_id>", to_id="<existing_id>", relation="related_to")
+   ```
+
+6. **Save session** - Finally, save the session summary:
+   ```python
+   contextfs_save(save_session="current", label="<descriptive-label>")
+   ```
+
+---
+
+## Output
+
+After extraction, report:
+- Number of memories saved by type
+- Any memories that were evolved (updated) instead of created new
+- Session label used
+
+**Important**: Be thorough but avoid duplicating. Always search first, evolve if exists.