claude-mem 3.3.7 → 3.3.9

package/docs/reference/claude-code/mcp-configuration.md

@@ -0,0 +1,133 @@
+# MCP Configuration Documentation
+## Source: Official Claude Code Docs v2025
+## Last Verified: 2025-08-31
+
+## MCP Configuration File Locations
+
+### User Scope
+- **File**: `~/.claude.json`
+- **Purpose**: User-wide MCP servers available across all projects
+- **Persistence**: Persists across projects
+- **Example Path**: `/Users/username/.claude.json`
+
+### Project Scope
+- **File**: `./.mcp.json`
+- **Purpose**: Project-specific servers for team collaboration
+- **Persistence**: Checked into version control
+- **Example Path**: `/path/to/project/.mcp.json`
+
+### Local Scope
+- **Status**: Not officially documented
+- **Implementation**: Currently uses `~/.claude.json` (may need revision)
+
+## Configuration Structure
+
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "command-to-run",
+      "args": ["arg1", "arg2"],
+      "env": {
+        "ENV_VAR": "value"
+      }
+    }
+  }
+}
+```
+
+## Example Configurations
+
+### Memory Server (stdio)
+```json
+{
+  "mcpServers": {
+    "claude-mem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"]
+    }
+  }
+}
+```
+
+### HTTP Server
+```json
+{
+  "mcpServers": {
+    "api-server": {
+      "type": "sse",
+      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
+      "headers": {
+        "Authorization": "Bearer ${API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Environment Variable Expansion
+
+MCP configs support environment variable expansion:
+- `${VAR}` - Direct expansion
+- `${VAR:-default}` - With fallback value
+
+Applicable fields:
+- `command`
+- `args`
+- `env`
+- `url`
+- `headers`
+
+## CLI Commands
+
+```bash
+# Add a server
+claude mcp add <name> <command> [args...]
+
+# Add with scope
+claude mcp add <name> --scope project /path/to/server
+claude mcp add <name> --scope user /path/to/server
+
+# List servers
+claude mcp list
+
+# Get server details
+claude mcp get <name>
+
+# Remove server
+claude mcp remove <name>
+
+# Check status (within Claude Code)
+/mcp
+```
+
+## Tool Naming Convention
+
+MCP tools follow the pattern: `mcp__<serverName>__<toolName>`
+
+Example:
+- Server: `claude-mem`
+- Tool: `create_entities`
+- Full name: `mcp__claude_mem__create_entities`
+
+## Security Considerations
+
+1. **Tool Permissions**: Must explicitly allow MCP tools via `--allowedTools`
+2. **Server Trust**: Only use MCP servers from trusted sources
+3. **Credential Management**: Use environment variables for sensitive data
+4. **Audit Trail**: MCP operations can be monitored via hooks
+
+## Common Issues
+
+### Issue: MCP server not connecting
+**Solution**: Check that the command and args are correct, and npx is in PATH
+
+### Issue: Tools not available
+**Solution**: Ensure server is in allowed list and properly configured
+
+### Issue: Configuration not loading
+**Solution**: Verify JSON syntax and file location
+
+## References
+- Official Docs: https://docs.anthropic.com/en/docs/claude-code/mcp
+- MCP Protocol: https://modelcontextprotocol.io/

package/docs/reference/claude-code/session-start-hook.md

@@ -0,0 +1,82 @@
+# SessionStart Hook Documentation
+
+## Official Documentation Reference
+- **Source**: https://docs.anthropic.com/en/docs/claude-code/hooks#sessionstart
+- **Last Verified**: 2025-08-31
+- **Version**: Claude Code v2025
+
+## Hook Payload Structure
+
+The SessionStart hook receives the following JSON payload via stdin:
+
+```json
+{
+  "session_id": "string",
+  "transcript_path": "string", 
+  "hook_event_name": "SessionStart",
+  "source": "startup" | "compact" | "vscode" | "web"
+}
+```
+
+### Field Descriptions
+
+- **session_id**: Unique identifier for the Claude Code session
+- **transcript_path**: Path to the conversation transcript JSONL file
+- **hook_event_name**: Always "SessionStart" for this hook
+- **source**: Indicates how the session was initiated:
+  - `"startup"`: New session started normally (should load context)
+  - `"compact"`: Session started after compaction (may skip context)
+  - `"vscode"`: Session initiated from VS Code extension
+  - `"web"`: Session initiated from web interface
+
+## Response Format
+
+The hook should output JSON in the following format to add context:
+
+```json
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "string"
+  }
+}
+```
+
+### Response Fields
+
+- **hookSpecificOutput**: Container for hook-specific output
+- **hookEventName**: Must be "SessionStart"
+- **additionalContext**: String content to add to the session context
+
+## Implementation Notes
+
+### Context Loading Strategy
+
+The hook should determine whether to load context based on the `source` field:
+
+1. **For "startup" source**: Load full context from memory
+2. **For "compact" source**: Skip or load minimal context (session continuing after compaction)
+3. **For "vscode"/"web" sources**: Load context as appropriate
+
+### Error Handling
+
+- If context loading fails, exit silently (exit code 0)
+- Do not break the session start with errors
+- Log errors to separate log file if needed
+
+## Common Mistakes
+
+### Incorrect Field Check (FIXED)
+**Wrong**: Checking `payload.reason === 'continue'`
+**Correct**: Checking `payload.source === 'compact'`
+
+The payload does not have a `reason` field. The `source` field indicates the session initiation context.
+
+## Code Location
+- **File**: `/Users/alexnewman/Scripts/claude-mem/hooks/session-start.js`
+- **Line**: 53-66 (field check and documentation)
+
+## Cross-References
+- General Hooks Documentation: [docs/claude-code/hooks.md](./hooks.md)
+- Hook Response Formats: [docs/claude-code/hook-responses.md](./hook-responses.md)
+- MCP Configuration: [docs/claude-code/mcp-configuration.md](./mcp-configuration.md)

package/docs/reference/load-context-format-example.md

@@ -0,0 +1,33 @@
+<session-start-hook>
+
+🧠 What's new: Thursday, September 4, 2025 at 06:13 PM EDT
+====================================================================
+Established Claude memory management infrastructure with compression tools for session archiving. Optimized session summary generation with compact command overviews for improved retrieval efficiency.
+
+📚 Recent Context 
+====================================================================
+👀 in claude_mem_source_d096f650-76a3-4163-9b7a-19f36a13c648_{number}:
+
+1. Removed maxTurns:1 limitation that prevented Claude from completing multi-step compression with tool calls
+    — maxTurns, Claude SDK, compression fix, MCP tools
+
+3. Deployed steve-krug-ux agent to redesign prompt from pipe-separated to JSON with XMLResponse tags
+    — steve-krug-ux, JSON format, prompt redesign
+
+5. Expanded TranscriptCompressor to use all 13 claude-mem MCP tools for intelligent compression
+    — allowedTools, MCP tools expansion, TranscriptCompressor
+
+6. Traced index population failure through multiple system layers to identify root cause
+   — debugging, ContextTemplates, claude-mem-index, trace
+
+======================================================================
+👀 in claude_mem_source_d096f650-76a3-4163-9b7a-19f36a13c648_{number}:
+
+1. Implemented Claude memory management and compression tools system
+   — memory management, compression, archiving, session context
+
+2. Generated compact command overview for session summaries
+   — command overview, session summaries, memory retrieval
+
+======================================================================
+</session-start-hook>