airkjw/claude-mem
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: Live Context System with Distributed CLAUDE.md Generation (#556)

Browse Source 
* docs: add folder index generator plan

RFC for auto-generating folder-level CLAUDE.md files with observation
timelines. Includes IDE symlink support and root CLAUDE.md integration.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: implement folder index generator (Phase 1)

Add automatic CLAUDE.md generation for folders containing observed files.
This enables IDE context providers to access relevant memory observations.

Core modules:
- FolderDiscovery: Extract folders from observation file paths
- FolderTimelineCompiler: Compile chronological timeline per folder
- ClaudeMdGenerator: Write CLAUDE.md with tag-based content replacement
- FolderIndexOrchestrator: Coordinate regeneration on observation save

Integration:
- Event-driven regeneration after observation save in ResponseProcessor
- HTTP endpoints for folder discovery, timeline, and manual generation
- Settings for enabling/configuring folder index behavior

The <claude-mem-context> tag wrapping ensures:
- Manual CLAUDE.md content is preserved
- Auto-generated content won't be recursively observed
- Clean separation between user and system content

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: add updateFolderClaudeMd function to CursorHooksInstaller

Adds function to update CLAUDE.md files for folders touched by observations.
Uses existing /api/search/by-file endpoint, preserves content outside
<claude-mem-context> tags, and writes atomically via temp file + rename.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: hook updateFolderClaudeMd into ResponseProcessor

Calls updateFolderClaudeMd after observation save to update folder-level
CLAUDE.md files. Uses fire-and-forget pattern with error logging.
Extracts file paths from saved observations and workspace path from registry.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: add timeline formatting for folder CLAUDE.md files

Implements formatTimelineForClaudeMd function that transforms API response
into compact markdown table format. Converts emojis to text labels,
handles ditto marks for timestamps, and groups under "Recent" header.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* refactor: remove old folder-index implementation

Deletes redundant folder-index services that were replaced by the simpler
updateFolderClaudeMd approach in CursorHooksInstaller.ts.

Removed:
- src/services/folder-index/ directory (5 files)
- FolderIndexRoutes.ts
- folder-index settings from SettingsDefaultsManager
- folder-index route registration from worker-service

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: add worktree-aware project filtering for unified timelines

Detect git worktrees and show both parent repo and worktree observations
in the session start timeline. When running in a worktree, the context
now includes observations from both projects, interleaved chronologically.

- Add detectWorktree() utility to identify worktree directories
- Add getProjectContext() to return parent + worktree projects
- Update context hook to pass multi-project queries
- Add queryObservationsMulti() and querySummariesMulti() for IN clauses
- Maintain backward compatibility with single-project queries

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* fix: restructure logging to prove session correctness and reduce noise

Add critical logging at each stage of the session lifecycle to prove the session ID chain (contentSessionId → sessionDbId → memorySessionId) stays aligned. New logs include CREATED, ENQUEUED, CLAIMED, MEMORY_ID_CAPTURED, STORING, and STORED. Move intermediate migration and backfill progress logs to DEBUG level to reduce noise, keeping only essential initialization and completion logs at INFO level.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

* refactor: extract folder CLAUDE.md utils to shared location

Moves folder CLAUDE.md utilities from CursorHooksInstaller to a new
shared utils file. Removes Cursor registry dependency - file paths
from observations are already absolute, no workspace lookup needed.

New file: src/utils/claude-md-utils.ts
- replaceTaggedContent() - preserves user content outside tags
- writeClaudeMdToFolder() - atomic writes with tag preservation
- formatTimelineForClaudeMd() - API response to compact markdown
- updateFolderClaudeMdFiles() - orchestrates folder updates

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: trigger folder CLAUDE.md updates when observations are saved

The folder CLAUDE.md update was previously only triggered in
syncAndBroadcastSummary, but summaries run with observationCount=0
(observations are saved separately). Moved the update logic to
syncAndBroadcastObservations where file paths are available.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* all the claudes

* test: add unit tests for claude-md-utils pure functions

Add 11 tests covering replaceTaggedContent and formatTimelineForClaudeMd:
- replaceTaggedContent: empty content, tag replacement, appending, partial tags
- formatTimelineForClaudeMd: empty input, parsing, ditto marks, session IDs

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* test: add integration tests for file operation functions

Add 9 tests for writeClaudeMdToFolder and updateFolderClaudeMdFiles:
- writeClaudeMdToFolder: folder creation, content preservation, nested dirs, atomic writes
- updateFolderClaudeMdFiles: empty skip, fetch/write, deduplication, error handling

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* test: add unit tests for timeline-formatting utilities

Add 14 tests for extractFirstFile and groupByDate functions:
- extractFirstFile: relative paths, fallback to files_read, null handling, invalid JSON
- groupByDate: empty arrays, date grouping, chronological sorting, item preservation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* chore: rebuild plugin scripts with merged features

* docs: add project-specific CLAUDE.md with architecture and development notes

* fix: exclude project root from auto-generated CLAUDE.md updates

Skip folders containing .git directory when auto-updating subfolder
CLAUDE.md files. This ensures:

1. Root CLAUDE.md remains user-managed and untouched by the system
2. SessionStart context injection stays pristine throughout the session
3. Subfolder CLAUDE.md files continue to receive live context updates
4. Cleaner separation between user-authored root docs and auto-generated folder indexes

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: prevent crash from resuming stale SDK sessions on worker restart

When the worker restarts, it was incorrectly passing the `resume` parameter
to INIT prompts (lastPromptNumber=1) when a memorySessionId existed from a
previous SDK session. This caused "Claude Code process exited with code 1"
crashes because the SDK tried to resume into a session that no longer exists.

Root cause: The resume condition only checked `hasRealMemorySessionId` but
did not verify that this was a CONTINUATION prompt (lastPromptNumber > 1).

Fix: Add `session.lastPromptNumber > 1` check to the resume condition:
- Before: `...(hasRealMemorySessionId && { resume: session.memorySessionId })`
- After: `...(hasRealMemorySessionId && session.lastPromptNumber > 1 && { resume: ... })`

Also added:
- Enhanced debug logging that warns when skipping resume for INIT prompts
- Unit tests in tests/sdk-agent-resume.test.ts (9 test cases)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: properly handle Chroma MCP connection errors

Previously, ensureCollection() caught ALL errors from chroma_get_collection_info
and assumed they meant "collection doesn't exist", triggering unnecessary
collection creation attempts. Connection errors like "Not connected" or
"MCP error -32000: Connection closed" would cascade into failed creation attempts.

Similarly, queryChroma() would silently return empty results when the MCP call
failed, masking the underlying connection problem.

Changes:
- ensureCollection(): Detect connection errors and re-throw immediately instead
  of attempting collection creation
- queryChroma(): Wrap MCP call in try-catch and throw connection errors instead
  of returning empty results
- Both methods reset connection state (connected=false, client=null) on
  connection errors so subsequent operations can attempt to reconnect

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* pushed

* fix: scope regenerate-claude-md.ts to current working directory

Critical bug fix: The script was querying ALL observations from the database
across ALL projects ever recorded (1396+ folders), then attempting to write
CLAUDE.md files everywhere including other projects, non-existent paths, and
ignored directories.

Changes:
- Use git ls-files to discover folders (respects .gitignore automatically)
- Filter database query to current project only (by folder name)
- Use relative paths for database queries (matches storage format)
- Add --clean flag to remove auto-generated CLAUDE.md files
- Add fallback directory walker for non-git repos

Now correctly scopes to 26 folders with observations instead of 1396+.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* docs and adjustments

* fix: cleanup mode strips tags instead of deleting files blindly

The cleanup mode was incorrectly deleting entire files that contained
<claude-mem-context> tags. The correct behavior (per original design):

1. Strip the <claude-mem-context>...</claude-mem-context> section
2. If empty after stripping → delete the file
3. If has remaining content → save the stripped version

Now properly preserves user content in CLAUDE.md files while removing
only the auto-generated sections.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* deleted some files

* chore: regenerate folder CLAUDE.md files with fixed script

Regenerated 23 folder CLAUDE.md files using the corrected script that:
- Scopes to current working directory only
- Uses git ls-files to respect .gitignore
- Filters by project name

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Update CLAUDE.md files for January 5, 2026

- Regenerated and staged 23 CLAUDE.md files with a mix of new and modified content.
- Fixed cleanup mode to properly strip tags instead of deleting files blindly.
- Cleaned up empty CLAUDE.md files from various directories, including ~/.claude and ~/Scripts.
- Conducted dry-run cleanup that identified a significant reduction in auto-generated CLAUDE.md files.
- Removed the isAutoGeneratedClaudeMd function due to incorrect file deletion behavior.

* feat: use settings for observation limit in batch regeneration script

Replace hard-coded limit of 10 with configurable CLAUDE_MEM_CONTEXT_OBSERVATIONS
setting (default: 50). This allows users to control how many observations appear
in folder CLAUDE.md files.

Changes:
- Import SettingsDefaultsManager and load settings at script startup
- Use OBSERVATION_LIMIT constant derived from settings at both call sites
- Remove stale default parameter from findObservationsByFolder function

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: use settings for observation limit in event-driven updates

Replace hard-coded limit of 10 in updateFolderClaudeMdFiles with
configurable CLAUDE_MEM_CONTEXT_OBSERVATIONS setting (default: 50).

Changes:
- Import SettingsDefaultsManager and os module
- Load settings at function start (once, not in loop)
- Use limit from settings in API call

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: Implement configurable observation limits and enhance search functionality

- Added configurable observation limits to batch regeneration scripts.
- Enhanced SearchManager to handle folder queries and normalize parameters.
- Introduced methods to check for direct child files in observations and sessions.
- Updated SearchOptions interface to include isFolder flag for filtering.
- Improved code quality with comprehensive reviews and anti-pattern checks.
- Cleaned up auto-generated CLAUDE.md files across various directories.
- Documented recent changes and improvements in CLAUDE.md files.

* build asset

* Project Context from Claude-Mem auto-added (can be auto removed at any time)

* CLAUDE.md updates

* fix: resolve CLAUDE.md files to correct directory in worktree setups

When using git worktrees, CLAUDE.md files were being written relative to
the worker's process.cwd() instead of the actual project directory. This
fix threads the project's cwd from message processing through to the file
writing utilities, ensuring CLAUDE.md files are created in the correct
project directory regardless of where the worker was started.

Changes:
- Add projectRoot parameter to updateFolderClaudeMdFiles for path resolution
- Thread projectRoot through ResponseProcessor call chain
- Track lastCwd from messages in SDKAgent, GeminiAgent, OpenRouterAgent
- Add tests for relative/absolute path handling with projectRoot

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* more project context updates

* context updates

* fix: preserve actual dates in folder CLAUDE.md generation

Previously, formatTimelineForClaudeMd used today's date for all
observations because the API only returned time (e.g., "4:30 PM")
without date information. This caused all historical observations
to appear as if they happened today.

Changes:
- SearchManager.findByFile now groups results by date with headers
  (e.g., "### Jan 4, 2026") matching formatSearchResults behavior
- formatTimelineForClaudeMd now parses these date headers and uses
  the correct date when constructing epochs for date grouping

The timeline dates are critical for claude-mem context - LLMs need
accurate temporal context to understand when work happened.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* build: update worker assets with date parsing fix

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* claude-mem context: Fixed critical date parsing bug in PR #556

* fix: address PR #556 review items

- Use getWorkerHost() instead of hard-coded 127.0.0.1 in claude-md-utils
- Add error message and stack details to FOLDER_INDEX logging
- Add 5 new tests for worktree/projectRoot path resolution

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* Refactor CLAUDE documentation across multiple components and tests

- Updated CLAUDE.md files in src/ui/viewer, src/ui/viewer/constants, src/ui/viewer/hooks, tests/server, tests/worker/agents, and plans to reflect recent changes and improvements.
- Removed outdated entries and consolidated recent activities for clarity.
- Enhanced documentation for hooks, settings, and pagination implementations.
- Streamlined test suite documentation for server and worker agents, indicating recent test audits and cleanup efforts.
- Adjusted plans to remove obsolete entries and focus on current implementation strategies.

* docs: comprehensive v9.0 documentation audit and updates

- Add usage/folder-context to docs.json navigation (was documented but hidden!)
- Update introduction.mdx with v9.0 release notes (Live Context, Worktree Support, Windows Fixes)
- Add CLAUDE_MEM_WORKER_HOST setting to configuration.mdx
- Add Folder Context Files section with link to detailed docs
- Document worktree support in folder-context.mdx
- Update terminology from "mem-search skill" to "MCP tools" throughout active docs
- Update Search Pipeline in architecture/overview.mdx
- Update usage/getting-started.mdx with MCP tools terminology
- Update usage/claude-desktop.mdx title and terminology
- Update hooks-architecture.mdx reference

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: add recent activity log for worker CLI with detailed entries

* chore: update CLAUDE.md context files

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* feat: add brainstorming report for CLAUDE.md distribution architecture

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Alex Newman
2026-01-05 22:41:42 -05:00
committed by GitHub
parent 21a1e272d9
commit e1ab73decc
152 changed files with 10367 additions and 2103 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/public/CLAUDE.md
+81 -1
View File
@@ -85,4 +85,84 @@ npx mintlify dev
**Simple Rule**:
- `/docs/public/` = Official user documentation (Mintlify .mdx files) ← YOU ARE HERE
- `/docs/context/` = Internal docs, plans, references, audits
- `/docs/context/` = Internal docs, plans, references, audits
<claude-mem-context>
# Recent Activity
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Nov 18, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11206 | 3:01 PM | 🔵 | mem-search skill architecture and migration details retrieved in full format | ~538 |
### Nov 21, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #13221 | 2:01 AM | 🔴 | Fixed broken markdown link to Viewer UI documentation | ~316 |
| #13220 | 2:00 AM | 🔴 | Escaped HTML less-than symbol in universal architecture timeout documentation | ~316 |
| #13216 | 1:54 AM | ✅ | Universal Architecture Added to Navigation | ~330 |
| #13215 | " | 🟣 | Universal AI Memory Architecture Documentation Created | ~732 |
| #13213 | 1:50 AM | 🔵 | Introduction Page Content and Recent v6.0.0 Release | ~495 |
| #13212 | " | 🔵 | Architecture Evolution Documentation Structure | ~408 |
| #13211 | " | 🔵 | Mintlify Documentation Site Configuration | ~430 |
| #13209 | 1:48 AM | 🔵 | Public Documentation Structure and Guidelines | ~383 |
### Nov 25, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #14994 | 2:22 PM | ✅ | Version Channel Section Added to Configuration Documentation | ~301 |
| #14993 | " | ✅ | Beta Features Added to Documentation Navigation | ~188 |
| #14992 | 2:21 PM | 🟣 | Beta Features Documentation Page Created | ~488 |
| #14991 | " | 🔵 | Mintlify Navigation Structure and Documentation Groups | ~394 |
| #14989 | " | 🔵 | Installation Documentation with Quick Start and Verification Steps | ~383 |
| #14988 | " | 🔵 | Configuration Documentation Structure and Environment Variables | ~338 |
### Nov 26, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #16190 | 10:22 PM | 🔵 | RAGTIME Search Retrieved Five Observations About Claude-Mem vs RAG Architecture | ~637 |
### Dec 3, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #19884 | 9:42 PM | 🔵 | Configuration system and environment variables | ~701 |
| #19878 | 9:40 PM | 🔵 | Installation process and system architecture | ~486 |
### Dec 8, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #22335 | 10:26 PM | 🔵 | Mintlify documentation configuration analyzed | ~534 |
| #22311 | 9:47 PM | 🔵 | Comprehensive Hooks Architecture Documentation Review | ~263 |
| #22297 | 9:43 PM | 🔵 | Mintlify Documentation Framework Configuration | ~446 |
| #22294 | " | 🔵 | Documentation Site Structure Located | ~359 |
### Dec 9, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #23179 | 10:44 PM | ✅ | Removed explanatory reasons from tool exclusion documentation | ~297 |
### Dec 15, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #27038 | 6:02 PM | 🔵 | 95% token reduction claims found only in private experimental documents, not in main public docs | ~513 |
| #27037 | " | 🔵 | Branch switching functionality exists in SettingsRoutes with UI switcher removal intent | ~463 |
| #26986 | 5:24 PM | ✅ | Updated Endless Mode latency warning in beta features documentation | ~299 |
### Dec 29, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #33938 | 6:27 PM | 🔵 | Relevant CLAUDE.md Context Identified for PR #492 | ~435 |
| #33750 | 12:25 AM | ✅ | Documentation Update: Removed Version Number from Architecture Evolution | ~281 |
</claude-mem-context>
docs/public/architecture/CLAUDE.md
+30
View File
@@ -0,0 +1,30 @@
<claude-mem-context>
# Recent Activity
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Nov 18, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11206 | 3:01 PM | 🔵 | mem-search skill architecture and migration details retrieved in full format | ~538 |
### Nov 21, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #13218 | 1:58 AM | 🔴 | Escaped HTML special character in MDX documentation | ~261 |
### Dec 3, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #19891 | 9:43 PM | 🔵 | Seven hook scripts across five lifecycle events | ~713 |
### Dec 15, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #27040 | 6:03 PM | 🔵 | Comprehensive search confirms no 95% claims exist in main branch public documentation | ~508 |
| #27037 | 6:02 PM | 🔵 | Branch switching functionality exists in SettingsRoutes with UI switcher removal intent | ~463 |
</claude-mem-context>
docs/public/architecture/overview.mdx
+6 -6
View File
@@ -45,19 +45,19 @@ Hook (stdin) → Database → Worker Service → SDK Processor → Database →
4. **Output**: Processed summaries written back to database
5. **Retrieval**: Next session's context hook reads summaries from database
### Search Pipeline (v5.4.0+)
### Search Pipeline
```
User Query → mem-search Skill Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
User Query → MCP Tools Invoked → HTTP API → SessionSearch Service → FTS5 Database → Search Results → Claude
```
1. **User Query**: User asks naturally: "What bugs did we fix?"
2. **Skill Invoked**: Claude recognizes intent and invokes mem-search skill
3. **HTTP API**: Skill uses curl to call HTTP endpoint (e.g., `/api/search/observations`)
2. **MCP Tools Invoked**: Claude recognizes intent and invokes MCP search tools
3. **HTTP API**: MCP tools call HTTP endpoint (e.g., `/api/search/observations`)
4. **SessionSearch**: Worker service queries FTS5 virtual tables
5. **Format**: Results formatted and returned to skill
5. **Format**: Results formatted and returned via MCP
6. **Return**: Claude presents formatted results to user
**Token Savings**: ~2,250 tokens per session vs MCP approach through progressive disclosure
Uses 3-layer progressive disclosure: search → timeline → get_observations
## Session Lifecycle
docs/public/configuration.mdx
+17 -9
View File
@@ -18,6 +18,7 @@ Settings are managed in `~/.claude-mem/settings.json`. The file is auto-created
| `CLAUDE_MEM_MODE` | `code` | Active mode profile (e.g., `code--es`, `email-investigation`) |
| `CLAUDE_MEM_CONTEXT_OBSERVATIONS` | `50` | Number of observations to inject |
| `CLAUDE_MEM_WORKER_PORT` | `37777` | Worker service port |
| `CLAUDE_MEM_WORKER_HOST` | `127.0.0.1` | Worker service host address |
| `CLAUDE_MEM_SKIP_TOOLS` | `ListMcpResourcesTool,SlashCommand,Skill,TodoWrite,AskUserQuestion` | Comma-separated tools to exclude from observations |
### Gemini Provider Settings
@@ -189,19 +190,16 @@ Hooks are configured in `plugin/hooks/hooks.json`:
}
```
### Search Configuration (v5.4.0+)
### Search Configuration
**Migration Note**: As of v5.4.0, Claude-Mem uses skill-based search instead of MCP tools. As of v5.5.0, the skill was renamed to "mem-search" for better scope differentiation.
Claude-Mem provides MCP search tools for querying your project history.
**Previous (v5.3.x and earlier)**: MCP search server with 9 tools (~2,500 tokens per session)
**Current (v5.4.0+)**: mem-search skill with HTTP API (~250 tokens per session)
**No configuration required** - MCP tools are automatically available in Claude Code sessions.
**No configuration required** - the mem-search skill is automatically available in Claude Code sessions.
Search operations are now provided via:
- **Skill**: `plugin/skills/mem-search/SKILL.md` (auto-invoked when users ask about past work)
Search operations are provided via:
- **MCP Server**: 3 tools (search, timeline, get_observations) with progressive disclosure
- **HTTP API**: 10 endpoints on worker service port 37777
- **Progressive Disclosure**: Full instructions loaded on-demand only when needed
- **Auto-Invocation**: Claude recognizes natural language queries about past work
## Version Channel
@@ -229,6 +227,16 @@ Endless Mode is experimental and slower than standard mode. See [Beta Features](
Worker service is managed by Bun as a background process. The worker auto-starts on first session and runs continuously in the background.
## Folder Context Files
Claude-mem can automatically generate `CLAUDE.md` files in your project folders with activity timelines. This feature is disabled by default.
| Setting | Default | Description |
|---------|---------|-------------|
| `CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED` | `false` | Enable auto-generation of folder CLAUDE.md files |
See [Folder Context Files](usage/folder-context) for full documentation on how this feature works, configuration options, and git integration recommendations.
## Context Injection Configuration
Claude-Mem injects past observations into each new session, giving Claude awareness of recent work. You can configure exactly what gets injected using the **Context Settings Modal**.
docs/public/cursor/CLAUDE.md
+51
View File
@@ -0,0 +1,51 @@
<claude-mem-context>
# Recent Activity
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Dec 29, 2025
**gemini-setup.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34346 | 11:11 PM | 🟣 | Gemini Free Tier Integration Guide | ~413 |
| #34337 | 11:10 PM | 🔵 | Cursor Documentation Available | ~161 |
| #34331 | 11:05 PM | 🔴 | Fixed Broken Links in cursor/gemini-setup.mdx | ~253 |
| #34326 | 11:04 PM | 🔵 | Broken Links in Cursor Gemini Setup Documentation | ~324 |
| #34320 | 11:03 PM | 🔵 | Mintlify Broken Links Detected in Documentation | ~292 |
| #34215 | 10:08 PM | 🔵 | Retrieved Detailed Cursor Integration Implementation History | ~676 |
| #34214 | 10:07 PM | 🔵 | Cursor Integration Feature Set Discovered via Memory Search | ~427 |
| #34148 | 9:28 PM | 🟣 | Cursor IDE Integration with Cross-Platform Hooks and Documentation | ~514 |
| #34112 | 9:07 PM | 🟣 | Committed Cursor Public Documentation to Repository | ~427 |
| #34106 | 9:05 PM | 🟣 | Created Cursor-Specific Gemini Setup Guide | ~563 |
**index.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34339 | 11:10 PM | 🟣 | Cursor IDE Integration with Persistent Memory | ~394 |
| #34335 | 11:06 PM | 🟣 | Mintlify Documentation Linting Successfully Completed | ~409 |
| #34330 | 11:05 PM | 🔴 | Fixed Remaining Broken Links in cursor/index.mdx Next Steps Section | ~284 |
| #34329 | " | 🔴 | Fixed Broken Links in cursor/index.mdx Detailed Guides Section | ~269 |
| #34325 | 11:04 PM | 🔵 | Multiple Broken Links in Cursor Index Documentation | ~329 |
| #34216 | 10:08 PM | 🔵 | Additional Cursor Integration Details Retrieved for Post Writing | ~600 |
| #34105 | 9:05 PM | 🟣 | Created Cursor Integration Landing Page | ~522 |
**openrouter-setup.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34332 | 11:05 PM | 🔴 | Fixed Broken Links in cursor/openrouter-setup.mdx | ~283 |
| #34324 | 11:04 PM | 🔵 | Broken Link Syntax Identified in Cursor Documentation | ~329 |
| #34107 | 9:06 PM | 🟣 | Created Cursor-Specific OpenRouter Setup Guide | ~573 |
**cursor**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #34322 | 11:03 PM | 🔵 | Cursor Directory Files Confirmed to Exist | ~224 |
### Jan 4, 2026
**gemini-setup.mdx**
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #36751 | 12:32 AM | 🔵 | Gemini-Related Files Located Across Project | ~242 |
</claude-mem-context>
docs/public/docs.json
+1
View File
@@ -43,6 +43,7 @@
"usage/private-tags",
"usage/export-import",
"usage/manual-recovery",
"usage/folder-context",
"beta-features",
"endless-mode"
]
docs/public/hooks-architecture.mdx
+1 -1
View File
@@ -148,7 +148,7 @@ Claude-Mem uses 6 lifecycle hook scripts across 5 lifecycle events, plus 1 pre-h
|----|------|---|-------|--------|
| #2586 | 12:58 AM | 🔵 | Context hook file empty | ~51 |
*Use mem-search skill to access full details*
*Use MCP search tools to access full details*
```
**Source:** `src/hooks/context-hook.ts` → `plugin/scripts/context-hook.js`
docs/public/introduction.mdx
+17 -14
View File
@@ -23,15 +23,16 @@ Restart Claude Code. Context from previous sessions will automatically appear in
## Key Features
- 🧠 **Persistent Memory** - Context survives across sessions
- 🌐 **Multilingual Modes** - Supports 10+ languages (Spanish, Chinese, French, etc.)
- 🎭 **Mode System** - Switch between workflows (Code, Email Investigation)
- 🔍 **mem-search Skill** - Query your project history with natural language (~2,250 token savings)
- 📁 **Folder Context Files** - Auto-generated `CLAUDE.md` in project folders with activity timelines
- 🌐 **Multilingual Modes** - Supports 28 languages (Spanish, Chinese, French, Japanese, etc.)
- 🎭 **Mode System** - Switch between workflows (Code, Email Investigation, Chill)
- 🔍 **MCP Search Tools** - Query your project history with natural language
- 🌐 **Web Viewer UI** - Real-time memory stream visualization at http://localhost:37777
- 🔒 **Privacy Control** - Use `<private>` tags to exclude sensitive content from storage
- ⚙️ **Context Configuration** - Fine-grained control over what context gets injected
- 🤖 **Automatic Operation** - No manual intervention required
- 📊 **FTS5 Search** - Fast full-text search across observations
- 🔗 **Citations** - Reference past observations with IDs (access via http://localhost:37777/api/observation/{id} or view all in the web viewer at http://localhost:37777)
- 🔗 **Citations** - Reference past observations with IDs
## How It Works
@@ -58,11 +59,11 @@ Restart Claude Code. Context from previous sessions will automatically appear in
```
**Core Components:**
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd (6 hook scripts)
1. **4 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop
2. **Smart Install** - Cached dependency checker (pre-hook script)
3. **Worker Service** - HTTP API on port 37777 managed by Bun
4. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
5. **mem-search Skill** - Query historical context with natural language
5. **MCP Search Tools** - Query historical context with natural language
6. **Web Viewer UI** - Real-time visualization with SSE and infinite scroll
See [Architecture Overview](architecture/overview) for details.
@@ -76,21 +77,23 @@ See [Architecture Overview](architecture/overview) for details.
## What's New
**v9.0.0 - Live Context:**
- **Folder Context Files**: Auto-generated `CLAUDE.md` in project folders with activity timelines
- **Worktree Support**: Unified context from parent repos and git worktrees
- **Configurable Observation Limits**: Control how many observations appear in context
- **Windows Fixes**: Resolved IPC detection and hook execution issues
- **Settings Auto-Creation**: `settings.json` now auto-creates on first run
- **MCP Tools Naming**: Updated from "mem-search skill" to "MCP tools" terminology
**v7.1.0 - Bun Migration:**
- Replaced PM2 with native Bun process management
- Switched from better-sqlite3 to bun:sqlite for faster database access
- Automatic one-time migration on first hook trigger
- Simplified cross-platform support
**v7.0.0 - Context Configuration:**
- 11 settings for fine-grained control over context injection
- Dual-tag privacy system (`<private>` tags)
**Previous Highlights:**
- **v5.5.0**: mem-search skill with 100% effectiveness rate
- **v5.4.0**: Skill-based search (~2,250 tokens saved per session)
- **v5.1.0**: Web viewer UI at http://localhost:37777
## Next Steps
<CardGroup cols={2}>
@@ -100,8 +103,8 @@ See [Architecture Overview](architecture/overview) for details.
<Card title="Getting Started" icon="rocket" href="/usage/getting-started">
Learn how Claude-Mem works automatically
</Card>
<Card title="Architecture" icon="sitemap" href="/architecture/overview">
System components & data flow
<Card title="Folder Context" icon="folder-open" href="/usage/folder-context">
Auto-generated folder CLAUDE.md files
</Card>
<Card title="Search Tools" icon="magnifying-glass" href="/usage/search-tools">
Query your project history
docs/public/usage/CLAUDE.md
+47
View File
@@ -0,0 +1,47 @@
<claude-mem-context>
# Recent Activity
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Nov 18, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #11206 | 3:01 PM | 🔵 | mem-search skill architecture and migration details retrieved in full format | ~538 |
### Dec 3, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #19892 | 9:43 PM | 🔵 | Automatic operation workflow and progressive disclosure strategy | ~780 |
### Dec 10, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #23677 | 8:37 PM | ✅ | Update Export Documentation to Reflect Hybrid Search and Project Filter | ~314 |
| #23675 | " | 🔵 | Export/Import Memory Scripts Documentation | ~399 |
| #23590 | 5:51 PM | 🔵 | Import/Export Feature Status Review | ~490 |
| #23584 | 5:50 PM | 🔵 | Export/Import Documentation | ~405 |
### Dec 14, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #26335 | 9:02 PM | 🔵 | Citation URI Scheme Documentation | ~255 |
### Dec 25, 2025
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #32536 | 7:28 PM | ✅ | Updated Gemini provider warning about free tier rate limits | ~185 |
| #32535 | " | ✅ | Updated Gemini provider tip to recommend enabling billing | ~179 |
| #32534 | 7:27 PM | ✅ | Updated Gemini provider warning about rate limits | ~174 |
| #32533 | " | ✅ | Updated Gemini provider documentation with rate limit information | ~216 |
### Jan 5, 2026
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #37508 | 3:21 PM | 🔵 | Private Tags Documentation Defines User Privacy Control Mechanisms | ~748 |
</claude-mem-context>
docs/public/usage/claude-desktop.mdx
+6 -6
View File
@@ -1,23 +1,23 @@
---
title: Claude Desktop Skill
description: Use claude-mem memory search in Claude Desktop with the mem-search skill
title: Claude Desktop MCP
description: Use claude-mem memory search in Claude Desktop with MCP tools
icon: desktop
---
<Note>
**Availability:** The mem-search skill works with Claude Desktop on macOS and Windows.
**Availability:** Claude-mem MCP tools work with Claude Desktop on macOS and Windows.
</Note>
## Overview
Claude Desktop can access your claude-mem memory database through the **mem-search** skill. This allows you to search past sessions, decisions, and observations directly from Claude Desktop conversations.
Claude Desktop can access your claude-mem memory database through **MCP tools**. This allows you to search past sessions, decisions, and observations directly from Claude Desktop conversations.
## Prerequisites
Before installing the skill, ensure:
Before configuring MCP tools, ensure:
1. **claude-mem is installed** and the worker service is running
2. **MCP server is configured** in Claude Desktop (the skill uses the `mcp-search` MCP server)
2. **MCP server is configured** in Claude Desktop (uses the `mcp-search` MCP server)
### Verify Worker is Running
docs/public/usage/folder-context.mdx
+280
View File
@@ -0,0 +1,280 @@
---
title: "Folder Context Files"
description: "Automatic per-folder CLAUDE.md files that provide directory-level context to Claude"
---
## Overview
Claude-mem automatically generates `CLAUDE.md` files in your project folders to provide Claude with directory-level context. These files contain a summary of recent activity in each folder, helping Claude understand what work has been done and where.
<Info>
This feature is **disabled by default**. Enable it via settings if you want automatic folder-level context generation.
</Info>
## How It Works
When you work with Claude Code in a project, claude-mem tracks which files are read and modified. After each observation is saved, it automatically:
1. Identifies unique folder paths from touched files
2. Queries recent observations relevant to each folder
3. Generates a formatted timeline of activity
4. Writes it to `CLAUDE.md` in that folder (inside `<claude-mem-context>` tags)
### What Gets Generated
Each folder's `CLAUDE.md` contains a "Recent Activity" section showing:
- Observation IDs for reference
- Timestamps of when work occurred
- Type indicators (bug fixes, features, discoveries, etc.)
- Brief titles describing the work
- Estimated token counts
```markdown
<claude-mem-context>
# Recent Activity
<!-- This section is auto-generated by claude-mem. Edit content outside the tags. -->
### Jan 4, 2026
| ID | Time | T | Title | Read |
|----|------|---|-------|------|
| #1234 | 4:30 PM | 🔵 | Implemented user authentication | ~250 |
| #1235 | " | 🔴 | Fixed login redirect bug | ~180 |
</claude-mem-context>
```
### User Content Preservation
The auto-generated content is wrapped in `<claude-mem-context>` tags. **Any content you write outside these tags is preserved** when the file is regenerated. This means you can:
- Add your own documentation above or below the generated section
- Write folder-specific instructions for Claude
- Include architectural notes or conventions
```markdown
# Authentication Module
This folder contains all authentication-related code.
Follow the established patterns for new auth providers.
<claude-mem-context>
... auto-generated content ...
</claude-mem-context>
## Manual Notes
- OAuth providers go in /providers/
- Session handling uses Redis
```
### Project Root Exclusion
The **project root** (folders containing a `.git` directory) is **excluded** from auto-generation. This is intentional:
- Root `CLAUDE.md` files typically contain project-wide instructions you've written manually
- Auto-generating at the root could overwrite important project documentation
- Subfolders are where folder-level context is most useful
<Note>
Git submodules (which have a `.git` *file* instead of directory) are correctly detected and **not** excluded, so they receive auto-generated context.
</Note>
## Configuration
### Enabling the Feature
To enable folder CLAUDE.md generation, edit your settings file:
**1. Open `~/.claude-mem/settings.json`**
**2. Add or update this setting:**
```json
{
"CLAUDE_MEM_FOLDER_CLAUDEMD_ENABLED": "true"
}
```
**3. Save the file** - changes take effect immediately (no restart needed)
| Value | Behavior |
|-------|----------|
| `"false"` (default) | Folder CLAUDE.md generation disabled |
| `"true"` | Auto-generate folder CLAUDE.md files |
<Tip>
If the settings file doesn't exist, create it with just the settings you want to change. Claude-mem will use defaults for any missing settings.
</Tip>
## Cleanup Mode
The regenerate script includes a `--clean` mode for removing auto-generated content:
```bash
# Preview what would be cleaned (dry run)
bun scripts/regenerate-claude-md.ts --clean --dry-run
# Actually clean files
bun scripts/regenerate-claude-md.ts --clean
```
**What cleanup does:**
1. Finds all `CLAUDE.md` files recursively
2. Strips `<claude-mem-context>...</claude-mem-context>` sections
3. **Deletes** files that become empty after stripping
4. **Preserves** files that have user content outside the tags
This is useful for:
- Preparing a branch for PR (removing generated files)
- Resetting folder context to start fresh
- Removing context before sharing code
## Git Integration
### Should You Commit These Files?
This is **your choice** based on your workflow. Here are the trade-offs:
<Tabs>
<Tab title="Commit Them">
**Pros:**
- Team members see folder-level context and recent activity
- New contributors can understand what happened where
- Code reviewers get additional context about changes
- Historical record of work patterns in the repo
**Cons:**
- Adds files to your repository
- Files change frequently during development
- May create noise in diffs and commit history
- Different team members may generate different content
</Tab>
<Tab title="Gitignore Them">
**Pros:**
- Clean repository without generated files
- No commit noise from auto-generated content
- Each developer has their own local context
- Simpler git history
**Cons:**
- Team doesn't share folder context
- Context is lost when switching machines
- New team members don't benefit from existing context
</Tab>
</Tabs>
### Gitignore Pattern
To exclude folder CLAUDE.md files from git:
```gitignore
# Ignore auto-generated folder context files
**/CLAUDE.md
# But keep the root CLAUDE.md if you want
!CLAUDE.md
```
Or to ignore all CLAUDE.md files everywhere:
```gitignore
**/CLAUDE.md
```
### Recommended Workflows
**For Solo Developers:**
- Keep them local (gitignore) for personal context
- Or commit them if you work across multiple machines
**For Teams:**
- Discuss with your team which approach works best
- Consider committing them if onboarding is frequent
- Use `--clean` before PRs if you prefer clean diffs
**Before Merging PRs:**
```bash
# Clean up generated files before merge
bun scripts/regenerate-claude-md.ts --clean
git add -A
git commit -m "chore: clean up generated CLAUDE.md files"
```
## Regenerating Context
To manually regenerate all folder CLAUDE.md files from the database:
```bash
# Preview what would be regenerated
bun scripts/regenerate-claude-md.ts --dry-run
# Regenerate all folders
bun scripts/regenerate-claude-md.ts
# Regenerate for a specific project only
bun scripts/regenerate-claude-md.ts --project=my-project
```
This is useful after:
- Importing observations from another machine
- Database recovery
- Wanting to refresh all folder context
## Worktree Support
**New in v9.0**: Claude-mem now supports git worktrees with unified context.
When you're working in a git worktree, context is automatically gathered from both:
- The parent repository (where the worktree was created)
- The worktree directory itself
This means observations about shared code are visible regardless of which worktree you're in, giving you a complete picture of recent activity across all related directories.
### How It Works
1. When generating context, claude-mem detects if your project is a worktree
2. It identifies the parent repository automatically
3. Timeline queries include both locations
4. Results are interleaved chronologically
<Note>
No configuration needed - worktree detection is automatic. If you're not using worktrees, this feature has no effect.
</Note>
## Technical Details
### File Format
Generated content uses a consistent markdown table format:
| Column | Description |
|--------|-------------|
| ID | Observation ID (e.g., `#1234`) or session ID (`#S123`) |
| Time | 12-hour format with AM/PM, ditto marks (`"`) for repeated times |
| T | Type emoji indicator |
| Title | Brief description of the observation |
| Read | Estimated token count (e.g., `~250`) |
### Type Indicators
| Emoji | Type |
|-------|------|
| 🔴 | Bug fix |
| 🟣 | Feature |
| 🔄 | Refactor |
| ✅ | Change |
| 🔵 | Discovery |
| ⚖️ | Decision |
| 🎯 | Session |
| 💬 | Prompt |
### Atomic Writes
Files are written atomically using a temp file + rename pattern. This prevents partial writes if the process is interrupted.
### Performance
- Updates happen asynchronously (fire-and-forget)
- Failures are logged but don't block the main workflow
- Only folders with actual file activity are updated
- Deduplication prevents redundant updates for the same folder
docs/public/usage/getting-started.mdx
+6 -8
View File
@@ -160,13 +160,13 @@ Context injection uses progressive disclosure for efficient token usage:
- Shows full summary details **only if** generated after last observation
- Token cost: ~50-200 tokens for index view
### Layer 2: On-Demand Details (mem-search Skill)
### Layer 2: On-Demand Details (MCP Tools)
- Ask naturally: "What bugs did we fix?" or "How did we implement X?"
- Claude auto-invokes mem-search skill to fetch full details
- Claude auto-invokes MCP search tools to fetch full details
- Search by concept, file, type, or keyword
- Timeline context around specific observations
- Token cost: ~100-500 tokens per observation fetched
- Skill uses HTTP API (v5.4.0+) for efficient retrieval
- Uses 3-layer workflow: search → timeline → get_observations
### Layer 3: Perfect Recall (Code Access)
- Read source files directly when needed
@@ -193,9 +193,9 @@ When you use `/clear`, the session doesn't end - it continues with a new prompt
The `/clear` command clears the conversation context visible to Claude AND re-injects fresh context from recent sessions, while the underlying session continues tracking observations.
## Searching Your History (v5.4.0+)
## Searching Your History
Claude-Mem uses the mem-search skill for querying your project history. Simply ask naturally:
Claude-Mem provides MCP tools for querying your project history. Simply ask naturally:
```
"What bugs did we fix last session?"
@@ -204,9 +204,7 @@ Claude-Mem uses the mem-search skill for querying your project history. Simply a
"Show me recent work on this project"
```
Claude automatically recognizes your intent and invokes the mem-search skill, which uses HTTP API endpoints to query your memory efficiently.
**Token Savings**: ~2,250 tokens per session start vs previous MCP approach
Claude automatically recognizes your intent and invokes the MCP search tools, which use a 3-layer workflow (search → timeline → get_observations) for efficient token usage.
## Next Steps