This fork is in maintenance mode. No new features — a complete rewrite is in design. Updates here will only address latent bugs.

~4k tokens to access ~400k tokens of work.

• By reference — inject a semantic index, fetch full observations on-demand
• By vectorization — retrieve relevant memories via similarity search

Fork of thedotmack/claude-mem with additional features for standalone deployment, Cursor IDE integration, and alternative vector backends.

For base documentation, see upstream: github.com/thedotmack/claude-mem

This fork removes automatic CLAUDE.md file generation. Memory is accessed via MCP tools only:

mcp__plugin_claude-mem_mcp-search__search      # Search observations
mcp__plugin_claude-mem_mcp-search__timeline    # Get context around results
mcp__plugin_claude-mem_mcp-search__get_observations  # Fetch full details

Removed:

• Auto-generated <claude-mem-context> sections in CLAUDE.md files
• /do and /make-plan planner commands (separation of concerns)

Cleanup existing auto-generated content:

bun scripts/regenerate-claude-md.ts --clean

Path resolution supports running claude-mem without Claude Code marketplace:

Installation:

# Build from source
cd /path/to/claude-mem
bun install && bun run build

# Install to standalone location
mkdir -p ~/.claude-mem/plugin/scripts
cp plugin/scripts/*.cjs ~/.claude-mem/plugin/scripts/
cp plugin/package.json ~/.claude-mem/plugin/
cp -r plugin/modes ~/.claude-mem/plugin/
cp -r plugin/skills ~/.claude-mem/plugin/
cp -r plugin/ui ~/.claude-mem/plugin/

# Start worker
cd ~/.claude-mem && bun plugin/scripts/worker-service.cjs start

Configure MCP server and hooks for Cursor:

1. MCP Server (~/.cursor/mcp.json):

{
  "mcpServers": {
    "claude-mem": {
      "command": "bun",
      "args": ["/home/YOUR_USER/.claude-mem/plugin/scripts/mcp-server.cjs"]
    }
  }
}

2. Hooks (~/.cursor/hooks.json):

{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [
      { "command": "bun \"/home/YOUR_USER/.claude-mem/plugin/scripts/worker-service.cjs\" hook cursor session-init" },
      { "command": "bun \"/home/YOUR_USER/.claude-mem/plugin/scripts/worker-service.cjs\" hook cursor context" }
    ],
    "afterMCPExecution": [
      { "command": "bun \"/home/YOUR_USER/.claude-mem/plugin/scripts/worker-service.cjs\" hook cursor observation" }
    ],
    "afterShellExecution": [
      { "command": "bun \"/home/YOUR_USER/.claude-mem/plugin/scripts/worker-service.cjs\" hook cursor observation" }
    ],
    "afterFileEdit": [
      { "command": "bun \"/home/YOUR_USER/.claude-mem/plugin/scripts/worker-service.cjs\" hook cursor file-edit" }
    ],
    "stop": [
      { "command": "bun \"/home/YOUR_USER/.claude-mem/plugin/scripts/worker-service.cjs\" hook cursor summarize" }
    ]
  }
}

Replace YOUR_USER with your username. Restart Cursor after creating these files.

Note: Uses bun runtime (not node) due to bun:sqlite dependency.

Local LLM inference via LM Studio:

{
  "AI_PROVIDER": "lmstudio",
  "LMSTUDIO_BASE_URL": "http://localhost:1234/v1",
  "LMSTUDIO_MODEL": "ibm/granite-4-h-tiny"
}

Configure via web UI at http://localhost:37777 or in ~/.claude-mem/settings.json.

Recommended model: ibm/granite-4-h-tiny (4.2GB) — native 1M context window, efficient at ~259 output tokens/call. Load with at least 32k context: lms load ibm/granite-4-h-tiny -c 32768 -y.

Important: The init prompt is sent as role: 'system' to prevent hallucination with small models. Earlier versions sent it as role: 'user', which caused models to fabricate observations. The CLAUDE_MEM_OPENROUTER_MAX_TOKENS setting in settings.json must match the server-side context window.

The worker tracks SDK observer subprocesses to prevent accumulation:

• ObserverRegistry — singleton mapping sessionDbId → Set<pid>, enables session-scoped cleanup and orphan detection
• ObserverReaper — periodic (60s) sweep that kills unregistered observer processes and prunes dead PIDs from the registry
• GracefulShutdown — kills all tracked observers on worker exit (SIGTERM → 3s grace → SIGKILL)

No configuration needed — active by default when the worker starts.

Alternative vector backend using sqlite-vec:

• No Python dependency - Pure SQLite
• Windows support - No console popup issues
• Portable - Single database file
• Git-LFS export - Version control your memory

{
  "VECTOR_BACKEND": "sqlite-vec",
  "EMBEDDING_PROVIDER": "lmstudio",
  "EMBEDDING_MODEL": "text-embedding-nomic-embed-text-v1.5",
  "EMBEDDING_DIMENSIONS": "768"
}

Import observations from external databases with different schemas. Configure field mappings via the Settings UI or programmatically.

See docs/migration.md for full documentation.

Export vector database to a dedicated git repository for backup and versioning.

{
  "GIT_LFS_ENABLED": "true",
  "GIT_LFS_REMOTE": "origin",
  "GIT_LFS_REMOTE_URL": "https://github.com/username/claude-mem-vectors.git",
  "GIT_LFS_AUTO_PUSH": "true",
  "GIT_LFS_IDLE_PUSH_SECONDS": "300"
}

CLI Commands:

claude-mem git-sync init --remote <git-url>
claude-mem git-sync status
claude-mem git-sync push
claude-mem git-sync pull

Export Formats:

claude-mem export --format=sqlite   # Vector database only
claude-mem export --format=full     # Complete database with vectors
claude-mem export --format=json     # JSON with base64 vectors
claude-mem export --format=json --project=myproject  # Filter by project

• Standalone installation (~/.claude-mem/plugin/)
• Cursor IDE integration (MCP + Hooks)
• LM Studio / local model support
• sqlite-vec vector backend
• Git-LFS export with auto-push
• Removed CLAUDE.md auto-generation (MCP tools only)
• Dynamic marketplace org detection in sync script
• Schema adapters for external database migration
• Migration UI in settings panel
• System prompt role fix (role: 'system') to prevent local model hallucination
• Observer lifecycle management (ObserverRegistry + ObserverReaper)
• Grounding rules in observer prompts to enforce factual observations
• LMStudioAgent with dedicated init prompt and context management

Team memory sharing via dedicated vector repositories, separate from codebases.

Concept: Like the Resurrection Ship that extends resurrection range across the Cylon fleet, shared vector repos extend memory across teams and machines.

Federation uses geometric constraints for stability and performance:

Golden ratio φ ≈ 1.618

Constraints:

• Maximum 3 remote databases (tetrahedron = 4 vertices)
• 5s timeout per remote, 15s total budget
• Remotes are read-only (security)
• Optional allow-list for remote URLs

{
  "FEDERATION_MAX_REMOTES": "3",
  "FEDERATION_QUERY_TIMEOUT_MS": "5000",
  "FEDERATION_PRIORITY_DECAY": "golden",
  "FEDERATION_ALLOW_LIST": "https://memory.team.com",
  "FEDERATION_READ_ONLY": "true"
}

External databases have varying schemas. Adapters transform external formats to internal without modifying our schema:

// Register adapter for external DB with different field names
registry.register({
  id: 'team-memory',
  url: 'https://memory.team.com',
  fields: {
    id: 'observation_id',      // their field -> our field
    title: 'summary',
    narrative: 'content',
    timestamp: 'metadata.created_at',  // supports dot notation
  },
  transforms: {
    timestamp: 'iso8601',      // convert ISO to epoch
    embedding: 'base64',       // decode base64 vectors
  }
});

Principle: Mutable external schemas, immutable internal schema.

Roadmap:

• GIT_LFS_TEAM_REPOS - Connect to team memory repositories
• attachRemote() - Mount team vector databases
• queryFederated() - Search across all connected repos with priority weighting
• Cross-project context injection

AGPL-3.0 - Modifications shared in accordance with upstream license.

Upstream: thedotmack/claude-mem
This Fork: bpd1069/claude-mem