Add initial documentation for Claude-Mem plugin
- Created docs structure including introduction, installation, troubleshooting, and usage guides. - Added detailed installation instructions with quick start and advanced options. - Documented the automatic operation of Claude-Mem and its session management features. - Introduced MCP search tools with usage examples and query strategies. - Provided troubleshooting steps for common issues related to worker service, hooks, database, and search tools. - Included system requirements and upgrade notes for transitioning from v3.x to v4.0.0.
This commit is contained in:
Alex Newman
File diff suppressed because it is too large
Load Diff
-297
@@ -1,297 +0,0 @@
|
||||
# Claude Never Forgets
|
||||
|
||||
**Give Claude a memory that spans your entire project.**
|
||||
|
||||
---
|
||||
|
||||
## The Problem
|
||||
|
||||
```
|
||||
You: "Remember that bug we fixed last Tuesday with the auth flow?"
|
||||
Claude: "I don't have access to previous conversations..."
|
||||
```
|
||||
|
||||
Every `/clear` wipes Claude's memory. Every new session starts from zero. You repeat yourself constantly.
|
||||
|
||||
**Until now.**
|
||||
|
||||
---
|
||||
|
||||
## What Changes
|
||||
|
||||
### Before claude-mem
|
||||
```typescript
|
||||
// Monday: You debug an issue
|
||||
You: "Why is the database connection failing?"
|
||||
Claude: [Helps you fix it]
|
||||
|
||||
// Wednesday: Similar issue appears
|
||||
You: "The database is timing out again"
|
||||
Claude: "Let me investigate..." [Starts from scratch]
|
||||
```
|
||||
|
||||
### After claude-mem
|
||||
```typescript
|
||||
// Monday: You debug an issue
|
||||
You: "Why is the database connection failing?"
|
||||
Claude: [Helps you fix it]
|
||||
✓ Remembers: connection pool exhaustion pattern
|
||||
|
||||
// Wednesday: Similar issue appears
|
||||
You: "The database is timing out again"
|
||||
Claude: "Based on Monday's session, this looks like the same
|
||||
connection pool issue. Let me check the pool size config..."
|
||||
```
|
||||
|
||||
Claude **remembers**. Claude **learns**. Claude gets **better** over time.
|
||||
|
||||
---
|
||||
|
||||
## Real Examples
|
||||
|
||||
### 1. **Context Across Sessions**
|
||||
|
||||
**Without claude-mem:**
|
||||
```
|
||||
Session 1: "We use Redux for state management"
|
||||
Session 2: "What state management do you use?" ❌
|
||||
```
|
||||
|
||||
**With claude-mem:**
|
||||
```
|
||||
Session 1: "We use Redux for state management"
|
||||
Session 2: Claude already knows you use Redux ✓
|
||||
Suggests Redux patterns automatically ✓
|
||||
References your store structure ✓
|
||||
```
|
||||
|
||||
### 2. **Architectural Memory**
|
||||
|
||||
**Your third session of the day:**
|
||||
```
|
||||
You: "Add a new API endpoint for user preferences"
|
||||
|
||||
Claude: "I see from previous sessions that:
|
||||
- Your API follows REST conventions in src/api/
|
||||
- You use Zod for validation
|
||||
- Auth middleware is required for user routes
|
||||
- You prefer async/await over promises
|
||||
|
||||
I'll create the endpoint following these patterns..."
|
||||
```
|
||||
|
||||
**No explaining. No repeating. Just building.**
|
||||
|
||||
### 3. **Bug Pattern Recognition**
|
||||
|
||||
```
|
||||
Week 1: Fixed race condition in webhook handler
|
||||
Week 2: Different race condition in event processor
|
||||
|
||||
Claude: "This looks similar to the webhook race condition
|
||||
we fixed last week. The same solution should work..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────────┐
|
||||
│ You code with │
|
||||
│ Claude today │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ claude-mem captures & │
|
||||
│ compresses everything │
|
||||
│ into structured memories │
|
||||
└────────┬────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ Tomorrow, Claude starts │
|
||||
│ with full context of │
|
||||
│ your project history │
|
||||
└─────────────────────────────┘
|
||||
```
|
||||
|
||||
**Automatic. Zero effort. Always on.**
|
||||
|
||||
---
|
||||
|
||||
## What Gets Remembered
|
||||
|
||||
✓ **Decisions**: "Why did we choose this architecture?"
|
||||
✓ **Bugs Fixed**: "How did we solve this before?"
|
||||
✓ **Code Patterns**: "What's our convention for this?"
|
||||
✓ **File Changes**: "What did we modify last session?"
|
||||
✓ **Refactorings**: "What was the old implementation?"
|
||||
✓ **Dependencies**: "Which libraries are we using?"
|
||||
|
||||
Everything Claude does with you gets compressed into **searchable, reusable memory**.
|
||||
|
||||
---
|
||||
|
||||
## Powerful Search
|
||||
|
||||
Ask Claude to search your project history:
|
||||
|
||||
```
|
||||
You: "Find all the database migrations we did"
|
||||
Claude: [Searches across all sessions]
|
||||
"I found 7 database-related changes:
|
||||
- March 15: Added user_preferences table
|
||||
- March 12: Migration for OAuth tokens
|
||||
- March 8: Index optimization on sessions
|
||||
..."
|
||||
|
||||
You: "What decisions did we make about authentication?"
|
||||
Claude: [Retrieves decision observations]
|
||||
"We decided to use JWT tokens because..."
|
||||
```
|
||||
|
||||
7 specialized search tools. Instant recall. Full project history.
|
||||
|
||||
---
|
||||
|
||||
## The Numbers
|
||||
|
||||
| Metric | Before | After |
|
||||
|--------|--------|-------|
|
||||
| Context repetition | Every session | Never |
|
||||
| Onboarding time | 5-10 min per session | 0 seconds |
|
||||
| Bug re-investigation | Common | Rare |
|
||||
| Architectural questions | "What did we decide?" | Claude already knows |
|
||||
| Code pattern consistency | Manual enforcement | Automatic |
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
### Quick Start (2 minutes)
|
||||
|
||||
```bash
|
||||
# 1. Clone and install
|
||||
git clone https://github.com/thedotmack/claude-mem.git
|
||||
cd claude-mem
|
||||
|
||||
# 2. Add to Claude Code
|
||||
/plugin marketplace add .claude-plugin/marketplace.json
|
||||
|
||||
# 3. Install
|
||||
/plugin install claude-mem
|
||||
```
|
||||
|
||||
**Done.** Claude now has memory.
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
Choose your AI model (controls cost vs. quality of memory compression):
|
||||
|
||||
```bash
|
||||
./claude-mem-settings.sh
|
||||
```
|
||||
|
||||
**Models:**
|
||||
- `claude-haiku-4-5` - Fast & cheap
|
||||
- `claude-sonnet-4-5` - Balanced (default) ✓
|
||||
- `claude-opus-4` - Maximum quality
|
||||
|
||||
---
|
||||
|
||||
## Under The Hood
|
||||
|
||||
**Simple architecture, powerful results:**
|
||||
|
||||
1. **Hooks** capture every tool Claude uses
|
||||
2. **Worker service** compresses observations with AI
|
||||
3. **SQLite database** stores structured memories
|
||||
4. **MCP server** makes everything searchable
|
||||
5. **Context injection** gives Claude the right memories at the right time
|
||||
|
||||
**Zero maintenance. Runs in the background. Just works.**
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
### Solo Developers
|
||||
- Never lose context between coding sessions
|
||||
- Build on past decisions automatically
|
||||
- Remember why you made each choice
|
||||
|
||||
### Team Projects
|
||||
- Share architectural knowledge across sessions
|
||||
- Maintain consistency in code patterns
|
||||
- Document decisions as they happen
|
||||
|
||||
### Learning & Experiments
|
||||
- Track what you tried and what worked
|
||||
- Build a personal knowledge base
|
||||
- Learn from past mistakes
|
||||
|
||||
### Large Refactors
|
||||
- Remember what you changed across multiple sessions
|
||||
- Track progress on multi-day tasks
|
||||
- Maintain context through interruptions
|
||||
|
||||
---
|
||||
|
||||
## What Developers Say
|
||||
|
||||
> *"I used to spend 10 minutes every morning explaining my project to Claude. Now it just knows."*
|
||||
|
||||
> *"It's like having a teammate who was actually there for every line of code."*
|
||||
|
||||
> *"The search is incredible. I can ask about decisions we made weeks ago."*
|
||||
|
||||
---
|
||||
|
||||
## FAQ
|
||||
|
||||
**Does this slow down Claude?**
|
||||
No. Memory processing happens in the background. Claude responds instantly.
|
||||
|
||||
**How much does it cost?**
|
||||
Minimal. Memory compression uses your chosen model (default: Sonnet 4.5). Typical cost: $0.01-0.05 per coding session.
|
||||
|
||||
**Where is data stored?**
|
||||
Locally in `~/.claude-mem/claude-mem.db`. Fully private. Never leaves your machine.
|
||||
|
||||
**Can I search my memories?**
|
||||
Yes. 7 specialized search tools available through Claude.
|
||||
|
||||
**Does it work with existing projects?**
|
||||
Yes. Starts learning immediately when installed.
|
||||
|
||||
**What if I want to forget something?**
|
||||
Delete observations directly from the SQLite database, or start fresh by removing the DB file.
|
||||
|
||||
---
|
||||
|
||||
## Get Started
|
||||
|
||||
```bash
|
||||
git clone https://github.com/thedotmack/claude-mem.git
|
||||
cd claude-mem
|
||||
/plugin marketplace add .claude-plugin/marketplace.json
|
||||
/plugin install claude-mem
|
||||
```
|
||||
|
||||
**Give Claude a memory. Transform how you code.**
|
||||
|
||||
---
|
||||
|
||||
## Learn More
|
||||
|
||||
- [Technical Documentation](./CLAUDE.md)
|
||||
- [GitHub Repository](https://github.com/thedotmack/claude-mem)
|
||||
- [Report Issues](https://github.com/thedotmack/claude-mem/issues)
|
||||
|
||||
**License**: AGPL-3.0
|
||||
**Version**: 4.1.0
|
||||
**Author**: Alex Newman ([@thedotmack](https://github.com/thedotmack))
|
||||
@@ -1,246 +0,0 @@
|
||||
# Plan: Store Raw User Prompts for Full Context Search
|
||||
|
||||
## Problem
|
||||
|
||||
Claude-mem currently only captures tool executions (via PostToolUse hook), not the user's actual instructions and requests. This creates a gap:
|
||||
|
||||
- We can see WHAT Claude did (observations)
|
||||
- We can see SUMMARIES of what happened (session_summaries)
|
||||
- We CANNOT see what the user actually said/requested
|
||||
|
||||
**Real Example:**
|
||||
User repeatedly asked to "remove session validation" with increasing frustration over multiple prompts. The memory system captured the final implementation but not the conversation where the user had to convince Claude 3-4 times.
|
||||
|
||||
## Solution
|
||||
|
||||
Store ALL raw user prompts in a dedicated table with full-text search capability.
|
||||
|
||||
## Database Schema Changes
|
||||
|
||||
### 1. Create `user_prompts` table
|
||||
|
||||
```sql
|
||||
CREATE TABLE user_prompts (
|
||||
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
||||
sdk_session_id TEXT NOT NULL,
|
||||
prompt_number INTEGER NOT NULL,
|
||||
prompt_text TEXT NOT NULL,
|
||||
created_at TEXT NOT NULL,
|
||||
created_at_epoch INTEGER NOT NULL,
|
||||
FOREIGN KEY(sdk_session_id) REFERENCES sdk_sessions(sdk_session_id) ON DELETE CASCADE
|
||||
);
|
||||
|
||||
CREATE INDEX idx_user_prompts_sdk_session ON user_prompts(sdk_session_id);
|
||||
CREATE INDEX idx_user_prompts_created ON user_prompts(created_at_epoch DESC);
|
||||
CREATE INDEX idx_user_prompts_prompt_number ON user_prompts(prompt_number);
|
||||
```
|
||||
|
||||
### 2. Create FTS5 virtual table for full-text search
|
||||
|
||||
```sql
|
||||
CREATE VIRTUAL TABLE user_prompts_fts USING fts5(
|
||||
prompt_text,
|
||||
content='user_prompts',
|
||||
content_rowid='id'
|
||||
);
|
||||
```
|
||||
|
||||
### 3. Create triggers to sync FTS5
|
||||
|
||||
```sql
|
||||
CREATE TRIGGER user_prompts_ai AFTER INSERT ON user_prompts BEGIN
|
||||
INSERT INTO user_prompts_fts(rowid, prompt_text)
|
||||
VALUES (new.id, new.prompt_text);
|
||||
END;
|
||||
|
||||
CREATE TRIGGER user_prompts_ad AFTER DELETE ON user_prompts BEGIN
|
||||
INSERT INTO user_prompts_fts(user_prompts_fts, rowid, prompt_text)
|
||||
VALUES('delete', old.id, old.prompt_text);
|
||||
END;
|
||||
|
||||
CREATE TRIGGER user_prompts_au AFTER UPDATE ON user_prompts BEGIN
|
||||
INSERT INTO user_prompts_fts(user_prompts_fts, rowid, prompt_text)
|
||||
VALUES('delete', old.id, old.prompt_text);
|
||||
INSERT INTO user_prompts_fts(rowid, prompt_text)
|
||||
VALUES (new.id, new.prompt_text);
|
||||
END;
|
||||
```
|
||||
|
||||
## Code Changes
|
||||
|
||||
### 1. Update schema migration
|
||||
|
||||
**File:** `src/services/sqlite/SessionStore.ts`
|
||||
|
||||
Add the user_prompts table creation to the schema initialization (look for the `CREATE TABLE` statements in the constructor).
|
||||
|
||||
### 2. Add method to save user prompts
|
||||
|
||||
**File:** `src/services/sqlite/SessionStore.ts`
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Save a user prompt
|
||||
*/
|
||||
saveUserPrompt(sdkSessionId: string, promptNumber: number, promptText: string): number {
|
||||
const now = new Date();
|
||||
const nowEpoch = now.getTime();
|
||||
|
||||
const stmt = this.db.prepare(`
|
||||
INSERT INTO user_prompts
|
||||
(sdk_session_id, prompt_number, prompt_text, created_at, created_at_epoch)
|
||||
VALUES (?, ?, ?, ?, ?)
|
||||
`);
|
||||
|
||||
const result = stmt.run(sdkSessionId, promptNumber, promptText, now.toISOString(), nowEpoch);
|
||||
return result.lastInsertRowid as number;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Update new-hook to save user prompts
|
||||
|
||||
**File:** `src/hooks/new.ts`
|
||||
|
||||
After creating/getting the session and incrementing prompt counter, save the raw prompt:
|
||||
|
||||
```typescript
|
||||
// Around line 37, after incrementPromptCounter
|
||||
const sessionDbId = db.createSDKSession(session_id, project, prompt);
|
||||
const promptNumber = db.incrementPromptCounter(sessionDbId);
|
||||
|
||||
// Get sdk_session_id for foreign key
|
||||
const session = db.findAnySDKSession(session_id);
|
||||
if (session?.sdk_session_id) {
|
||||
db.saveUserPrompt(session.sdk_session_id, promptNumber, prompt);
|
||||
}
|
||||
|
||||
console.error(`[new-hook] Session ${sessionDbId}, prompt #${promptNumber}`);
|
||||
```
|
||||
|
||||
**Note:** We need the sdk_session_id (not just sessionDbId) for the foreign key. May need to adjust the logic to handle prompts before SDK session is fully initialized.
|
||||
|
||||
### 4. Add SessionSearch methods
|
||||
|
||||
**File:** `src/services/sqlite/SessionSearch.ts`
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* Search user prompts with full-text search
|
||||
*/
|
||||
searchUserPrompts(query: string, options: SearchOptions = {}): UserPrompt[] {
|
||||
const { limit = 20, offset = 0 } = options;
|
||||
|
||||
const stmt = this.db.prepare(`
|
||||
SELECT
|
||||
up.id,
|
||||
up.sdk_session_id,
|
||||
up.prompt_number,
|
||||
up.prompt_text,
|
||||
up.created_at,
|
||||
up.created_at_epoch
|
||||
FROM user_prompts_fts fts
|
||||
JOIN user_prompts up ON fts.rowid = up.id
|
||||
WHERE user_prompts_fts MATCH ?
|
||||
ORDER BY rank
|
||||
LIMIT ? OFFSET ?
|
||||
`);
|
||||
|
||||
return stmt.all(query, limit, offset) as UserPrompt[];
|
||||
}
|
||||
|
||||
/**
|
||||
* Get all prompts for a session
|
||||
*/
|
||||
getUserPromptsBySession(sdkSessionId: string): UserPrompt[] {
|
||||
const stmt = this.db.prepare(`
|
||||
SELECT
|
||||
id,
|
||||
sdk_session_id,
|
||||
prompt_number,
|
||||
prompt_text,
|
||||
created_at,
|
||||
created_at_epoch
|
||||
FROM user_prompts
|
||||
WHERE sdk_session_id = ?
|
||||
ORDER BY prompt_number ASC
|
||||
`);
|
||||
|
||||
return stmt.all(sdkSessionId) as UserPrompt[];
|
||||
}
|
||||
```
|
||||
|
||||
Add the `UserPrompt` type:
|
||||
|
||||
```typescript
|
||||
interface UserPrompt {
|
||||
id: number;
|
||||
sdk_session_id: string;
|
||||
prompt_number: number;
|
||||
prompt_text: string;
|
||||
created_at: string;
|
||||
created_at_epoch: number;
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Add MCP search tool
|
||||
|
||||
**File:** `src/servers/search-server.ts`
|
||||
|
||||
Add a new tool `search_user_prompts`:
|
||||
|
||||
```typescript
|
||||
{
|
||||
name: 'search_user_prompts',
|
||||
description: 'Search raw user prompts with full-text search. Use this to find what the user actually said/requested across all sessions.',
|
||||
inputSchema: zodToJsonSchema(z.object({
|
||||
query: z.string().describe('Search query for FTS5 full-text search'),
|
||||
limit: z.number().optional().default(20).describe('Maximum results'),
|
||||
offset: z.number().optional().default(0).describe('Results to skip'),
|
||||
}))
|
||||
}
|
||||
```
|
||||
|
||||
And implement the handler.
|
||||
|
||||
## Benefits
|
||||
|
||||
1. **Full context reconstruction:** See exact user language, frustration level, repeated requests
|
||||
2. **Pattern detection:** Identify when Claude isn't listening (user repeats same request)
|
||||
3. **Improved summaries:** AI can reference actual user words, not just observations
|
||||
4. **Debugging:** Trace from user request → Claude actions → outcomes
|
||||
5. **Search across time:** "How many times did user ask for X feature?"
|
||||
|
||||
## Testing
|
||||
|
||||
1. Create a new session and submit several prompts
|
||||
2. Query `user_prompts` table to verify they're saved
|
||||
3. Test FTS5 search: `SELECT * FROM user_prompts_fts WHERE user_prompts_fts MATCH 'validation'`
|
||||
4. Test MCP tool: `/claude-mem search_user_prompts "remove validation"`
|
||||
5. Verify prompt_number increments correctly
|
||||
6. Test cascade delete: delete a session, verify prompts are deleted
|
||||
|
||||
## Migration Notes
|
||||
|
||||
- This is a NEW table, no data migration needed
|
||||
- Existing sessions won't have historical prompts (that's fine)
|
||||
- FTS5 triggers will auto-populate as new prompts arrive
|
||||
|
||||
## Open Questions
|
||||
|
||||
1. **sdk_session_id timing:** New-hook runs BEFORE worker initializes SDK session. Need to either:
|
||||
- Save prompts with sessionDbId initially, update with sdk_session_id later
|
||||
- OR use sessionDbId as the foreign key instead
|
||||
|
||||
2. **Storage size:** User prompts can be large. Consider max length or compression?
|
||||
|
||||
3. **Privacy:** User prompts may contain sensitive info. Document this clearly.
|
||||
|
||||
## Implementation Order
|
||||
|
||||
1. Add schema to SessionStore constructor
|
||||
2. Add saveUserPrompt method to SessionStore
|
||||
3. Add search methods to SessionSearch
|
||||
4. Update new-hook to save prompts
|
||||
5. Add MCP tool to search-server
|
||||
6. Test end-to-end
|
||||
7. Update CLAUDE.md documentation
|
||||
@@ -33,22 +33,30 @@ Restart Claude Code. Context from previous sessions will automatically appear in
|
||||
|
||||
## Documentation
|
||||
|
||||
📚 **[View Full Documentation](docs/)** - Browse markdown docs on GitHub
|
||||
|
||||
💻 **Local Preview**: Run Mintlify docs locally:
|
||||
```bash
|
||||
cd docs
|
||||
npx mintlify dev
|
||||
```
|
||||
|
||||
### Getting Started
|
||||
- **[Installation Guide](docs/installation.md)** - Quick start & advanced installation
|
||||
- **[Usage Guide](docs/usage/getting-started.md)** - How Claude-Mem works automatically
|
||||
- **[MCP Search Tools](docs/usage/search-tools.md)** - Query your project history
|
||||
- **[Installation Guide](docs/installation.mdx)** - Quick start & advanced installation
|
||||
- **[Usage Guide](docs/usage/getting-started.mdx)** - How Claude-Mem works automatically
|
||||
- **[MCP Search Tools](docs/usage/search-tools.mdx)** - Query your project history
|
||||
|
||||
### Architecture
|
||||
- **[Overview](docs/architecture/overview.md)** - System components & data flow
|
||||
- **[Hooks](docs/architecture/hooks.md)** - 5 lifecycle hooks explained
|
||||
- **[Worker Service](docs/architecture/worker-service.md)** - HTTP API & PM2 management
|
||||
- **[Database](docs/architecture/database.md)** - SQLite schema & FTS5 search
|
||||
- **[MCP Search](docs/architecture/mcp-search.md)** - 7 search tools & examples
|
||||
- **[Overview](docs/architecture/overview.mdx)** - System components & data flow
|
||||
- **[Hooks](docs/architecture/hooks.mdx)** - 5 lifecycle hooks explained
|
||||
- **[Worker Service](docs/architecture/worker-service.mdx)** - HTTP API & PM2 management
|
||||
- **[Database](docs/architecture/database.mdx)** - SQLite schema & FTS5 search
|
||||
- **[MCP Search](docs/architecture/mcp-search.mdx)** - 7 search tools & examples
|
||||
|
||||
### Configuration & Development
|
||||
- **[Configuration](docs/configuration.md)** - Environment variables & settings
|
||||
- **[Development](docs/development.md)** - Building, testing, contributing
|
||||
- **[Troubleshooting](docs/troubleshooting.md)** - Common issues & solutions
|
||||
- **[Configuration](docs/configuration.mdx)** - Environment variables & settings
|
||||
- **[Development](docs/development.mdx)** - Building, testing, contributing
|
||||
- **[Troubleshooting](docs/troubleshooting.mdx)** - Common issues & solutions
|
||||
|
||||
---
|
||||
|
||||
@@ -82,7 +90,7 @@ Restart Claude Code. Context from previous sessions will automatically appear in
|
||||
3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
|
||||
4. **7 MCP Search Tools** - Query historical context with citations
|
||||
|
||||
See [Architecture Overview](docs/architecture/overview.md) for details.
|
||||
See [Architecture Overview](docs/architecture/overview.mdx) for details.
|
||||
|
||||
---
|
||||
|
||||
@@ -106,7 +114,7 @@ search_user_prompts with query="add dark mode"
|
||||
get_recent_context with limit=5
|
||||
```
|
||||
|
||||
See [MCP Search Tools Guide](docs/usage/search-tools.md) for detailed examples.
|
||||
See [MCP Search Tools Guide](docs/usage/search-tools.mdx) for detailed examples.
|
||||
|
||||
---
|
||||
|
||||
@@ -170,7 +178,7 @@ See [CHANGELOG.md](CHANGELOG.md) for complete version history.
|
||||
- `CLAUDE_MEM_WORKER_PORT` - Worker port (default: 37777)
|
||||
- `CLAUDE_MEM_DATA_DIR` - Data directory override (dev only)
|
||||
|
||||
See [Configuration Guide](docs/configuration.md) for details.
|
||||
See [Configuration Guide](docs/configuration.mdx) for details.
|
||||
|
||||
---
|
||||
|
||||
@@ -193,7 +201,7 @@ npm run worker:start
|
||||
npm run worker:logs
|
||||
```
|
||||
|
||||
See [Development Guide](docs/development.md) for detailed instructions.
|
||||
See [Development Guide](docs/development.mdx) for detailed instructions.
|
||||
|
||||
---
|
||||
|
||||
@@ -205,7 +213,7 @@ See [Development Guide](docs/development.md) for detailed instructions.
|
||||
- Database issues → `sqlite3 ~/.claude-mem/claude-mem.db "PRAGMA integrity_check;"`
|
||||
- Search not working → Check FTS5 tables exist
|
||||
|
||||
See [Troubleshooting Guide](docs/troubleshooting.md) for complete solutions.
|
||||
See [Troubleshooting Guide](docs/troubleshooting.mdx) for complete solutions.
|
||||
|
||||
---
|
||||
|
||||
@@ -219,7 +227,7 @@ Contributions are welcome! Please:
|
||||
4. Update documentation
|
||||
5. Submit a Pull Request
|
||||
|
||||
See [Development Guide](docs/development.md) for contribution workflow.
|
||||
See [Development Guide](docs/development.mdx) for contribution workflow.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,4 +1,6 @@
|
||||
# Claude-Mem Architecture Refactor Plan
|
||||
# Claude-Mem Architecture v3 to v4 Plan (✅ Completed)
|
||||
|
||||
This file exists as a reference to explain the path forward from v3 to v4.
|
||||
|
||||
## Core Purpose
|
||||
|
||||
@@ -1,283 +0,0 @@
|
||||
# Magic UI Components Catalog
|
||||
|
||||
Complete catalog of Magic UI components with descriptions and use cases.
|
||||
|
||||
## Animation Components
|
||||
|
||||
### 1. **Animated List**
|
||||
- **Purpose**: Animates list items sequentially with delay
|
||||
- **Use Case**: Showcasing events, notifications, feature lists
|
||||
- **Key Props**: `delay` (ms between items)
|
||||
- **Effect**: Staggered reveal animation
|
||||
|
||||
### 2. **Text Animate**
|
||||
- **Purpose**: Sophisticated text animation effects
|
||||
- **Animation Types**:
|
||||
- `blurIn` - Characters fade from blur
|
||||
- `slideUp` - Words slide up
|
||||
- `scaleUp` - Text scales up
|
||||
- `fadeIn` - Lines fade in
|
||||
- `slideLeft` - Characters slide from left
|
||||
- **Animate By**: `character`, `word`, `text`, `line`
|
||||
- **Use Case**: Hero headlines, feature announcements, storytelling
|
||||
- **Customization**: Delay, duration, custom motion variants
|
||||
|
||||
### 3. **Flip Text**
|
||||
- **Purpose**: Vertical flip animation for text
|
||||
- **Key Props**: `duration`, `delayMultiple`, custom variants
|
||||
- **Use Case**: Eye-catching headlines, call-to-actions
|
||||
|
||||
### 4. **Morphing Text**
|
||||
- **Purpose**: Dynamic text transitions between multiple strings
|
||||
- **Key Props**: `texts` array (strings to morph between)
|
||||
- **Use Case**: Dynamic value propositions, rotating benefits
|
||||
|
||||
### 5. **Word Rotate**
|
||||
- **Purpose**: Vertical rotation of words
|
||||
- **Key Props**: `words` (string array), `duration` (2500ms default)
|
||||
- **Use Case**: Rotating feature names, dynamic headlines
|
||||
|
||||
### 6. **Aurora Text**
|
||||
- **Purpose**: Beautiful aurora text effect
|
||||
- **Key Props**: `colors` array, `speed` multiplier
|
||||
- **Default Colors**: `["#FF0080", "#7928CA", "#0070F3", "#38bdf8"]`
|
||||
- **Use Case**: Premium headlines, brand emphasis
|
||||
|
||||
## Visual Effect Components
|
||||
|
||||
### 7. **Orbiting Circles**
|
||||
- **Purpose**: Circles moving in orbit along circular paths
|
||||
- **Key Props**:
|
||||
- `radius` (orbit size)
|
||||
- `duration` (animation speed)
|
||||
- `reverse` (direction)
|
||||
- `delay`, `path` (show orbit path)
|
||||
- `iconSize`, `speed`
|
||||
- **Use Case**: Technology visualization, ecosystem diagrams, feature satellites
|
||||
|
||||
### 8. **Particles**
|
||||
- **Purpose**: Animated particle background with depth and interactivity
|
||||
- **Use Case**: Hero sections, immersive backgrounds
|
||||
|
||||
### 9. **Confetti**
|
||||
- **Purpose**: Celebration confetti effect
|
||||
- **Key Props**:
|
||||
- `particleCount`, `angle`, `spread`
|
||||
- `startVelocity`, `decay`, `gravity`
|
||||
- `colors`, `shapes` (square, circle, star)
|
||||
- `origin` point
|
||||
- **Includes**: `ConfettiButton` wrapper component
|
||||
- **Use Case**: Success states, milestones, achievements
|
||||
|
||||
### 10. **Border Beam**
|
||||
- **Purpose**: Animated beam effect along borders
|
||||
- **Key Props**: `reverse`, spring animations
|
||||
- **Use Case**: Card highlights, section emphasis
|
||||
|
||||
### 11. **Shine Border**
|
||||
- **Purpose**: Animated shining border effect
|
||||
- **Key Props**: `color` array, `borderWidth`, `duration`
|
||||
- **Use Case**: Premium cards, CTAs, feature boxes
|
||||
|
||||
### 12. **Magic Card**
|
||||
- **Purpose**: Spotlight effect following mouse cursor with border highlights
|
||||
- **Key Props**:
|
||||
- `gradientSize` (200 default)
|
||||
- `gradientColor` (#262626 default)
|
||||
- `gradientOpacity` (0.8)
|
||||
- `gradientFrom`/`gradientTo` (border colors)
|
||||
- **Use Case**: Interactive feature cards, pricing tables
|
||||
|
||||
## Background Components
|
||||
|
||||
### 13. **Grid Beams**
|
||||
- **Purpose**: Dynamic grid background with animated light beams
|
||||
- **Key Props**:
|
||||
- `gridSize` (40px default)
|
||||
- `gridColor` (rgba)
|
||||
- `rayCount` (15 default)
|
||||
- `rayOpacity` (0.35)
|
||||
- `raySpeed`, `rayLength` (45vh)
|
||||
- `gridFadeStart`/`gridFadeEnd` (%)
|
||||
- `backgroundColor`
|
||||
- **Use Case**: Hero sections, feature backgrounds, immersive layouts
|
||||
|
||||
### 14. **Warp Background**
|
||||
- **Purpose**: Warped perspective grid effect
|
||||
- **Key Props**:
|
||||
- `perspective` (depth)
|
||||
- `beamsPerSide` (4 default)
|
||||
- `beamSize` (thickness)
|
||||
- `beamDuration` (speed)
|
||||
- `gridColor`
|
||||
- **Use Case**: Futuristic hero sections, tech-focused pages
|
||||
|
||||
### 15. **Dot Pattern**
|
||||
- **Purpose**: Customizable dotted background pattern (SVG)
|
||||
- **Key Props**: `width`, `height`, `cx`, `cy`, `cr` (dot radius)
|
||||
- **Effects**: Supports glow effects
|
||||
- **Use Case**: Subtle backgrounds, section dividers
|
||||
|
||||
## Interactive Components
|
||||
|
||||
### 16. **Dock**
|
||||
- **Purpose**: macOS-style dock with magnification effect
|
||||
- **Key Props**:
|
||||
- `iconMagnification` (zoom amount)
|
||||
- `iconDistance` (hover range)
|
||||
- `direction` (middle, start, end)
|
||||
- **Child Component**: `DockIcon`
|
||||
- **Use Case**: Navigation, tool showcases, social links
|
||||
|
||||
### 17. **Scratch To Reveal**
|
||||
- **Purpose**: Interactive scratch-off effect revealing hidden content
|
||||
- **Key Props**:
|
||||
- `width`, `height`
|
||||
- `minScratchPercentage` (50 default, completion threshold)
|
||||
- `onComplete` callback
|
||||
- `gradientColors`
|
||||
- **Use Case**: Interactive reveals, gamification, teasers
|
||||
|
||||
### 18. **Highlighter**
|
||||
- **Purpose**: Animated text highlighting and underlining
|
||||
- **Key Props**:
|
||||
- `color`
|
||||
- `strokeWidth`
|
||||
- `action` (underline, highlight)
|
||||
- `animationDuration`
|
||||
- `iterations`, `padding`
|
||||
- **Use Case**: Emphasis on key phrases, call-outs
|
||||
|
||||
## Layout/Display Components
|
||||
|
||||
### 19. **Marquee**
|
||||
- **Purpose**: Scrolling content (horizontal or vertical)
|
||||
- **Key Props**:
|
||||
- `reverse` (direction)
|
||||
- `pauseOnHover`
|
||||
- `vertical` (orientation)
|
||||
- `repeat` (count)
|
||||
- **Effects**: 3D perspective option
|
||||
- **Use Case**: Testimonials, logo clouds, infinite scrollers
|
||||
|
||||
### 20. **Safari**
|
||||
- **Purpose**: Safari browser mockup for showcasing
|
||||
- **Key Props**:
|
||||
- `url` (address bar)
|
||||
- `imageSrc` or `videoSrc`
|
||||
- `width` (1203 default), `height` (753)
|
||||
- `mode` (default, simple)
|
||||
- **Use Case**: Product demos, website previews
|
||||
|
||||
### 21. **Bento Grid**
|
||||
- **Purpose**: Grid layout for organizing content
|
||||
- **Use Case**: Feature showcases, portfolios
|
||||
|
||||
### 22. **Avatar Circles**
|
||||
- **Purpose**: Overlapping circles of avatars
|
||||
- **Key Props**: `numPeople` (99 default, shown in last circle)
|
||||
- **Use Case**: Social proof, team displays, user counts
|
||||
|
||||
## Timeline Components
|
||||
|
||||
### 23. **Arc Timeline**
|
||||
- **Purpose**: Curved timeline visualizing milestones
|
||||
- **Key Props**:
|
||||
- `data` (array of {time, title})
|
||||
- `arcConfig`:
|
||||
- `circleWidth` (5000 default)
|
||||
- `angleBetweenMinorSteps` (0.35)
|
||||
- `lineCountFillBetweenSteps` (10)
|
||||
- `boundaryPlaceholderLinesCount` (50)
|
||||
- `defaultActiveStep` ({time, stepIndex})
|
||||
- **Use Case**: Project roadmaps, product evolution, version history
|
||||
|
||||
## Button Components
|
||||
|
||||
### 24. **Shiny Button**
|
||||
- **Purpose**: Button with shiny effect
|
||||
- **Features**: Dark/light mode support
|
||||
- **Use Case**: Primary CTAs, important actions
|
||||
|
||||
### 25. **Pulsating Button**
|
||||
- **Purpose**: Button with pulsing wave animation
|
||||
- **Key Props**: `pulseColor` (RGB), `duration`
|
||||
- **Use Case**: Attention-grabbing CTAs, urgent actions
|
||||
|
||||
### 26. **Rainbow Button**
|
||||
- **Purpose**: Rainbow gradient button effect
|
||||
- **Variants**: Default, Outline
|
||||
- **Use Case**: Premium CTAs, playful actions
|
||||
|
||||
## Theme Components
|
||||
|
||||
### 27. **Animated Theme Toggler**
|
||||
- **Purpose**: Smooth animated light/dark mode toggle
|
||||
- **Built With**: Tailwind CSS
|
||||
- **Use Case**: Theme switching UI
|
||||
|
||||
---
|
||||
|
||||
## Installation
|
||||
|
||||
```bash
|
||||
# Via CLI (recommended)
|
||||
npx shadcn-ui@latest add [component-name]
|
||||
|
||||
# Manual installation
|
||||
npm install magicui
|
||||
# or
|
||||
yarn add magicui
|
||||
```
|
||||
|
||||
## Component Categories Summary
|
||||
|
||||
| Category | Components | Best For |
|
||||
|----------|-----------|----------|
|
||||
| **Text Animation** | Animated List, Text Animate, Flip Text, Morphing Text, Word Rotate, Aurora Text | Headlines, feature lists, dynamic content |
|
||||
| **Visual Effects** | Orbiting Circles, Particles, Confetti, Border Beam, Shine Border, Magic Card | Visual interest, interactivity, emphasis |
|
||||
| **Backgrounds** | Grid Beams, Warp Background, Dot Pattern | Hero sections, immersive layouts |
|
||||
| **Interactive** | Dock, Scratch To Reveal, Highlighter | User engagement, gamification |
|
||||
| **Layout** | Marquee, Safari, Bento Grid, Avatar Circles | Content organization, showcases |
|
||||
| **Timeline** | Arc Timeline | Roadmaps, history, progression |
|
||||
| **Buttons** | Shiny Button, Pulsating Button, Rainbow Button | CTAs, actions |
|
||||
| **Utility** | Animated Theme Toggler | UI controls |
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
Magic UI components focus on:
|
||||
- **Delight**: Unexpected animations that create joy
|
||||
- **Fluidity**: Smooth, natural motion
|
||||
- **Performance**: Optimized for web performance
|
||||
- **Flexibility**: Highly customizable via props
|
||||
- **Modern**: Built with React, Tailwind CSS, Framer Motion
|
||||
|
||||
## Use Case Recommendations by Landing Page Section
|
||||
|
||||
### Hero Sections
|
||||
- Grid Beams or Warp Background (background)
|
||||
- Aurora Text or Morphing Text (headline)
|
||||
- Pulsating Button or Rainbow Button (CTA)
|
||||
- Orbiting Circles (tech visualization)
|
||||
|
||||
### Feature Showcases
|
||||
- Bento Grid (layout)
|
||||
- Magic Card (individual features)
|
||||
- Animated List (feature details)
|
||||
- Highlighter (emphasis)
|
||||
|
||||
### Social Proof
|
||||
- Marquee (testimonials/logos)
|
||||
- Avatar Circles (user counts)
|
||||
|
||||
### Product Demos
|
||||
- Safari (browser mockups)
|
||||
- Border Beam or Shine Border (emphasis)
|
||||
|
||||
### Roadmaps/Progress
|
||||
- Arc Timeline (milestones)
|
||||
|
||||
### Interactive Elements
|
||||
- Scratch To Reveal (teasers)
|
||||
- Dock (navigation/tools)
|
||||
- Confetti (celebrations)
|
||||
@@ -1,471 +0,0 @@
|
||||
# Magic UI Landing Page Creative Ideas
|
||||
|
||||
Creative applications of Magic UI components for each section of the claude-mem landing page.
|
||||
|
||||
## Section 1: HERO - "Claude Never Forgets"
|
||||
|
||||
### Idea 1: "Fading Memory" Effect ⭐ WINNER
|
||||
**Components**: Morphing Text, Grid Beams, Orbiting Circles, Scratch To Reveal
|
||||
|
||||
**Vision**:
|
||||
- **Headline**: Morphing Text rotating between:
|
||||
- "Claude Never Forgets"
|
||||
- "Claude Always Remembers"
|
||||
- "Claude Learns Forever"
|
||||
- **Background**: Grid Beams in blue/purple gradient representing the "memory grid"
|
||||
- **Central Visual**: Orbiting Circles around a central "brain/database" icon
|
||||
- Inner orbit: File icons (representing code files)
|
||||
- Middle orbit: Lightbulb icons (decisions)
|
||||
- Outer orbit: Bug icons (fixes)
|
||||
- **Problem Statement**: Scratch To Reveal overlay
|
||||
- User must scratch to reveal: "Every /clear wipes Claude's memory"
|
||||
- Makes the pain point visceral and interactive
|
||||
- **CTA**: Pulsating Button "Give Claude a Memory"
|
||||
|
||||
### Idea 2: "Memory Timeline" Hero
|
||||
**Components**: Warp Background, Arc Timeline, Aurora Text, Word Rotate
|
||||
|
||||
**Vision**:
|
||||
- Warp Background creating perspective depth
|
||||
- Arc Timeline showing "Session 1 → Session 2 → Session 3" with memories persisting across
|
||||
- Aurora Text for main headline with flowing gradient
|
||||
- Word Rotate cycling pain points: "Repeating" → "Explaining" → "Re-discovering" → "Forgetting"
|
||||
|
||||
### Idea 3: "Brain Storage" Visualization
|
||||
**Components**: Particles, Magic Card, Highlighter, Pulsating Button
|
||||
|
||||
**Vision**:
|
||||
- Particles background (subtle, neuron-like firing)
|
||||
- Central Magic Card with spotlight effect containing headline
|
||||
- Highlighter emphasizing "Never" and "Forgets" with animated underlines
|
||||
- Pulsating Button for CTA with urgency
|
||||
|
||||
---
|
||||
|
||||
## Section 2: BEFORE/AFTER Comparison
|
||||
|
||||
### Idea 1: "Split Screen Wipe" ⭐ WINNER
|
||||
**Components**: Safari, Text Animate, Border Beam, Scratch To Reveal
|
||||
|
||||
**Vision**:
|
||||
- Two Safari browser mockups side by side
|
||||
- **Left (Before)**: Conversation fades/blurs out showing memory loss
|
||||
- **Right (After)**: Sharp, persistent content with Border Beam highlighting
|
||||
- Text Animate with slideUp for conversations appearing sequentially
|
||||
- Optional: Scratch To Reveal over "Before" side to uncover the painful reality
|
||||
|
||||
### Idea 2: "Memory Decay Visualization"
|
||||
**Components**: Text Animate, Shine Border, Magic Card, Animated Theme Toggler
|
||||
|
||||
**Vision**:
|
||||
- Before side: Text with progressive fade-out animation (opacity decreasing)
|
||||
- After side: Text with Shine Border, glowing persistently
|
||||
- Magic Card on After side with spotlight following mouse
|
||||
- Animated Theme Toggler metaphorically switching "forgetting" → "remembering"
|
||||
|
||||
### Idea 3: "Conversation Replay"
|
||||
**Components**: Animated List, Border Beam, Highlighter
|
||||
|
||||
**Vision**:
|
||||
- Animated List showing conversation history
|
||||
- Before: List items fade out and disappear sequentially
|
||||
- After: List items persist, Border Beam appears on referenced items
|
||||
- Highlighter underlining key persistent information on After side
|
||||
|
||||
---
|
||||
|
||||
## Section 3: REAL EXAMPLES (3 Scenarios)
|
||||
|
||||
### Idea 1: "Tabbed Experience"
|
||||
**Components**: Bento Grid, Magic Card, Text Animate, Flip Text, Confetti
|
||||
|
||||
**Vision**:
|
||||
- Bento Grid layout with 3 Magic Cards (one per scenario)
|
||||
- Each card has spotlight effect on hover
|
||||
- Text Animate (blurIn) for code examples appearing
|
||||
- Flip Text for headings revealing scenario names
|
||||
- Confetti burst when clicking through to third example (pattern recognized!)
|
||||
|
||||
### Idea 2: "Timeline Story" ⭐ WINNER
|
||||
**Components**: Arc Timeline, Orbiting Circles, Highlighter, Animated List
|
||||
|
||||
**Vision**:
|
||||
- Arc Timeline showing progression: "Monday Session" → "Wednesday Session"
|
||||
- Each timeline node expands to show the scenario details
|
||||
- Orbiting Circles around active node showing:
|
||||
- Files involved (icons in orbit)
|
||||
- Decisions made (decision icons)
|
||||
- Bugs fixed (bug icons)
|
||||
- Highlighter emphasizing key remembered details in the expanded content
|
||||
- Animated List revealing the bulleted "Claude remembers" items
|
||||
|
||||
### Idea 3: "Memory Card Flip"
|
||||
**Components**: Scratch To Reveal, Magic Card, Pulsating Button, Word Rotate
|
||||
|
||||
**Vision**:
|
||||
- Three cards with Scratch To Reveal overlay
|
||||
- Scratch to reveal what Claude remembers from previous sessions
|
||||
- Magic Card underneath with gradient borders
|
||||
- Pulsating Button to cycle through scenarios
|
||||
- Word Rotate showing memory types: "Patterns" → "Decisions" → "Context" → "Architecture"
|
||||
|
||||
---
|
||||
|
||||
## Section 4: HOW IT WORKS (Pipeline)
|
||||
|
||||
### Idea 1: "Animated Data Flow"
|
||||
**Components**: Magic Card, Orbiting Circles, Border Beam, Text Animate, Particles
|
||||
|
||||
**Vision**:
|
||||
- Three connected Magic Cards showing pipeline stages:
|
||||
1. "You code with Claude today"
|
||||
2. "claude-mem captures & compresses"
|
||||
3. "Tomorrow, Claude starts with context"
|
||||
- Orbiting Circles representing data flowing between stages
|
||||
- Border Beam animating along connections between cards
|
||||
- Text Animate (slideUp) for each stage description on scroll
|
||||
- Particles flowing from one stage to the next
|
||||
|
||||
### Idea 2: "Arc Timeline as Process"
|
||||
**Components**: Arc Timeline, Orbiting Circles, Warp Background, Animated List, Shine Border
|
||||
|
||||
**Vision**:
|
||||
- Arc Timeline showing 5 steps of memory system
|
||||
- Each node has Orbiting Circles showing components (hooks, worker, DB, MCP, context)
|
||||
- Warp Background creating depth
|
||||
- Animated List revealing sub-bullets under each stage
|
||||
- Shine Border on active/hovered stage
|
||||
|
||||
### Idea 3: "Layered Depth Model" ⭐ WINNER
|
||||
**Components**: Grid Beams, Magic Card, Border Beam, Morphing Text, Highlighter
|
||||
|
||||
**Vision**:
|
||||
- Grid Beams background representing the "storage layer"
|
||||
- Three floating Magic Cards in z-space (perspective/depth):
|
||||
- Top layer: "Hooks capture"
|
||||
- Middle layer: "AI compresses"
|
||||
- Bottom layer: "Database stores"
|
||||
- Arrows with Border Beam animation showing data flow downward
|
||||
- Morphing Text showing state transformation: "Capturing" → "Compressing" → "Storing" → "Retrieving"
|
||||
- Highlighter emphasizing "Automatic. Zero effort. Always on."
|
||||
|
||||
---
|
||||
|
||||
## Section 5: WHAT GETS REMEMBERED (Feature List)
|
||||
|
||||
### Idea 1: "Checkbox Delight"
|
||||
**Components**: Animated List, Text Animate, Highlighter, Confetti, Magic Card
|
||||
|
||||
**Vision**:
|
||||
- Animated List of 6 checkmark items
|
||||
- Each item appears with Text Animate (blurIn by character)
|
||||
- Highlighter underlining key words: "Decisions", "Bugs Fixed", "Code Patterns", etc.
|
||||
- Confetti burst when all items are visible (celebration of completeness)
|
||||
- Magic Card container with subtle spotlight effect
|
||||
|
||||
### Idea 2: "Memory Bank Slots" ⭐ WINNER
|
||||
**Components**: Bento Grid, Scratch To Reveal, Shine Border, Orbiting Circles, Pulsating Button
|
||||
|
||||
**Vision**:
|
||||
- Bento Grid of 6 cards (one per memory type)
|
||||
- Each card has Scratch To Reveal to discover what gets saved (gamification!)
|
||||
- Shine Border appears around revealed cards
|
||||
- Orbiting Circles showing example icons around each card type
|
||||
- Pulsating indicator on most important memory types
|
||||
|
||||
### Idea 3: "Collector Animation"
|
||||
**Components**: Magic Card, Border Beam, Flip Text, Aurora Text, Dot Pattern
|
||||
|
||||
**Vision**:
|
||||
- Six Magic Cards arranged in grid
|
||||
- Border Beam cascading through cards in sequence
|
||||
- Each card flips (Flip Text) to reveal icon + description
|
||||
- Aurora Text for section heading
|
||||
- Dot Pattern background with subtle glow on active items
|
||||
|
||||
---
|
||||
|
||||
## Section 6: POWERFUL SEARCH
|
||||
|
||||
### Idea 1: "Live Search Demo" ⭐ WINNER
|
||||
**Components**: Safari, Text Animate, Animated List, Highlighter, Border Beam, Morphing Text
|
||||
|
||||
**Vision**:
|
||||
- Safari browser mockup showing search interface
|
||||
- Text Animate typing out search queries with realistic timing:
|
||||
- "Find all database migrations..."
|
||||
- "What decisions about authentication..."
|
||||
- Animated List revealing search results sequentially
|
||||
- Highlighter emphasizing matched keywords in results
|
||||
- Border Beam around result cards
|
||||
- Morphing Text cycling search types: "Migrations" → "Decisions" → "Patterns" → "Bugs"
|
||||
|
||||
### Idea 2: "Search Radar"
|
||||
**Components**: Orbiting Circles, Magic Card, Particles, Text Animate, Grid Beams
|
||||
|
||||
**Vision**:
|
||||
- Orbiting Circles representing different search dimensions:
|
||||
- Inner orbit: File search
|
||||
- Middle orbit: Concept search
|
||||
- Outer orbit: Type/date filters
|
||||
- Central Magic Card with search query
|
||||
- Particles radiating outward to show search happening
|
||||
- Results appear with Text Animate (slideUp)
|
||||
- Grid Beams background representing indexed database
|
||||
|
||||
### Idea 3: "Memory Retrieval Visualization"
|
||||
**Components**: Warp Background, Aurora Text, Magic Card, Shine Border, Dock, Confetti
|
||||
|
||||
**Vision**:
|
||||
- Warp Background creating depth into "memory storage"
|
||||
- Search query in Aurora Text
|
||||
- Seven Magic Cards (one per search tool) with Shine Border
|
||||
- Dock component at bottom showing 7 search tool icons
|
||||
- Confetti when "perfect match" is found
|
||||
|
||||
---
|
||||
|
||||
## Section 7: THE NUMBERS (Metrics Table)
|
||||
|
||||
### Idea 1: "Counting Animation"
|
||||
**Components**: Safari, Text Animate, Aurora Text, Confetti, Border Beam
|
||||
|
||||
**Vision**:
|
||||
- Safari mockup showing comparison table
|
||||
- Text Animate for each metric value counting up
|
||||
- "Before" values in faded text
|
||||
- "After" values with Aurora Text effect (glowing)
|
||||
- Confetti when hovering over dramatic improvements
|
||||
- Border Beam highlighting entire "After" column
|
||||
|
||||
### Idea 2: "Progress Bar Transformation" ⭐ WINNER
|
||||
**Components**: Magic Card, Morphing Text, Shine Border, Pulsating Button
|
||||
|
||||
**Vision**:
|
||||
- Five Magic Cards, one per metric
|
||||
- Animated progress bars showing transformation:
|
||||
- Before (low/red) → After (high/green)
|
||||
- Visual representation of improvement
|
||||
- Morphing Text cycling through metrics
|
||||
- Shine Border on cards with biggest improvements
|
||||
- Pulsating Button: "See the Difference"
|
||||
|
||||
### Idea 3: "Flip Cards Reveal"
|
||||
**Components**: Scratch To Reveal, Magic Card, Highlighter, Animated List
|
||||
|
||||
**Vision**:
|
||||
- Five cards with Scratch To Reveal
|
||||
- Scratch "Before" to reveal "After" metrics
|
||||
- Each card has Magic Card spotlight effect
|
||||
- Highlighter emphasizing: "Never", "0 seconds", "Rare"
|
||||
- Animated List showing additional benefits below table
|
||||
|
||||
---
|
||||
|
||||
## Section 8: INSTALLATION (Quick Start)
|
||||
|
||||
### Idea 1: "Copy-Paste Delight" ⭐ WINNER
|
||||
**Components**: Safari, Text Animate, Shiny Button, Confetti, Animated List, Highlighter
|
||||
|
||||
**Vision**:
|
||||
- Safari mockup showing terminal window
|
||||
- Text Animate typing out commands with realistic timing (typewriter effect)
|
||||
- Shiny Button next to each command for copy
|
||||
- Confetti celebration when installation completes
|
||||
- Animated List showing 3 steps with checkmarks appearing
|
||||
- Highlighter emphasizing "2 minutes"
|
||||
|
||||
### Idea 2: "Progress Stepper"
|
||||
**Components**: Arc Timeline, Border Beam, Magic Card, Pulsating Button, Word Rotate
|
||||
|
||||
**Vision**:
|
||||
- Arc Timeline with 3 nodes: Clone → Add → Install
|
||||
- Each step expands to show code when active
|
||||
- Border Beam connecting steps as they complete
|
||||
- Magic Card for code blocks with spotlight
|
||||
- Pulsating Button for "Get Started"
|
||||
- Word Rotate: "Simple" → "Fast" → "Easy" → "Done"
|
||||
|
||||
### Idea 3: "Interactive Terminal"
|
||||
**Components**: Grid Beams, Safari, Text Animate, Orbiting Circles, Rainbow Button, Shine Border
|
||||
|
||||
**Vision**:
|
||||
- Grid Beams background (tech aesthetic)
|
||||
- Safari terminal mockup
|
||||
- Text Animate simulating command execution
|
||||
- Orbiting Circles showing installed components appearing
|
||||
- Rainbow Button for final "Installation Complete" CTA
|
||||
- Shine Border around success message
|
||||
|
||||
---
|
||||
|
||||
## Section 9: UNDER THE HOOD (Architecture)
|
||||
|
||||
### Idea 1: "System Diagram"
|
||||
**Components**: Bento Grid, Magic Card, Orbiting Circles, Border Beam, Dot Pattern, Text Animate, Highlighter
|
||||
|
||||
**Vision**:
|
||||
- Bento Grid showing 5 architecture components:
|
||||
- Hooks, Worker, Database, MCP, Context Injection
|
||||
- Each grid cell is a Magic Card with spotlight
|
||||
- Orbiting Circles showing data flow between components
|
||||
- Border Beam animating along connections
|
||||
- Dot Pattern background
|
||||
- Text Animate for each component description
|
||||
- Highlighter on "Zero maintenance. Just works."
|
||||
|
||||
### Idea 2: "Layered Stack" ⭐ WINNER
|
||||
**Components**: Magic Card, Warp Background, Morphing Text, Particles, Shine Border
|
||||
|
||||
**Vision**:
|
||||
- Five Magic Cards stacked with perspective (z-depth)
|
||||
- Each layer slides out on scroll to reveal architecture:
|
||||
1. Hooks (top)
|
||||
2. Worker Service
|
||||
3. SQLite Database (center)
|
||||
4. MCP Server
|
||||
5. Context Injection (bottom)
|
||||
- Warp Background creating depth
|
||||
- Morphing Text showing active layer: "Hooks" → "Worker" → "SQLite" → "MCP" → "Context"
|
||||
- Particles flowing between layers
|
||||
- Shine Border on active layer
|
||||
|
||||
### Idea 3: "Technical Orbits"
|
||||
**Components**: Orbiting Circles, Grid Beams, Magic Card, Text Animate
|
||||
|
||||
**Vision**:
|
||||
- Central "SQLite DB" icon
|
||||
- Orbiting Circles representing different systems:
|
||||
- Inner orbit: 5 hooks (SessionStart, UserPrompt, PostTool, Summary, SessionEnd)
|
||||
- Middle orbit: Worker service (PM2 process)
|
||||
- Outer orbit: MCP server (7 search tools)
|
||||
- Farthest orbit: Context injection
|
||||
- Grid Beams background
|
||||
- Magic Card for each orbit explanation
|
||||
- Text Animate (slideUp) for technical details
|
||||
|
||||
---
|
||||
|
||||
## Section 10: USE CASES (User Types)
|
||||
|
||||
### Idea 1: "User Journey Cards"
|
||||
**Components**: Bento Grid, Magic Card, Avatar Circles, Animated List, Flip Text, Border Beam
|
||||
|
||||
**Vision**:
|
||||
- Four Magic Cards in Bento Grid layout
|
||||
- Each card has different gradient colors (gradientFrom/To)
|
||||
- Avatar Circles showing user type icon
|
||||
- Animated List of benefits per user type
|
||||
- Flip Text for headings revealing user types
|
||||
- Border Beam highlighting active/hovered card
|
||||
|
||||
### Idea 2: "Role Selector" ⭐ WINNER
|
||||
**Components**: Dock, Magic Card, Text Animate, Highlighter, Confetti
|
||||
|
||||
**Vision**:
|
||||
- Dock component with 4 icons representing user types:
|
||||
- Solo Developer icon
|
||||
- Team icon
|
||||
- Learning/Student icon
|
||||
- Large Refactor icon
|
||||
- Click icon to expand that use case
|
||||
- Magic Card expands with spotlight effect
|
||||
- Text Animate revealing use case details
|
||||
- Highlighter emphasizing key benefits
|
||||
- Confetti celebration when selecting "your" use case (engagement!)
|
||||
|
||||
### Idea 3: "Story Scenarios"
|
||||
**Components**: Arc Timeline, Safari, Orbiting Circles, Morphing Text, Shine Border, Animated List
|
||||
|
||||
**Vision**:
|
||||
- Arc Timeline showing progression for each user type
|
||||
- Safari mockup showing actual usage scenario
|
||||
- Orbiting Circles around timeline nodes showing features being used
|
||||
- Morphing Text cycling through user types
|
||||
- Shine Border on selected use case
|
||||
- Animated List showing specific benefits
|
||||
|
||||
---
|
||||
|
||||
## Section 11: FAQ
|
||||
|
||||
### Idea 1: "Expandable Cards"
|
||||
**Components**: Magic Card, Text Animate, Border Beam, Highlighter, Dot Pattern, Animated List
|
||||
|
||||
**Vision**:
|
||||
- Six Magic Cards with questions visible
|
||||
- Click to expand with Text Animate (blurIn)
|
||||
- Border Beam appears on expanded card
|
||||
- Highlighter emphasizing key answer points
|
||||
- Dot Pattern background
|
||||
- Animated List for multi-point answers
|
||||
|
||||
### Idea 2: "Scratch to Answer" ⭐ WINNER
|
||||
**Components**: Scratch To Reveal, Confetti, Magic Card, Morphing Text
|
||||
|
||||
**Vision**:
|
||||
- Questions visible, answers hidden under scratch surface
|
||||
- Scratch To Reveal to see answers (highly engaging!)
|
||||
- Confetti on revealing particularly important answers (e.g., "Fully private")
|
||||
- Magic Card container with spotlight
|
||||
- Morphing Text cycling through common concerns: "Cost?" → "Speed?" → "Privacy?" → "Storage?"
|
||||
|
||||
### Idea 3: "Interactive Q&A"
|
||||
**Components**: Bento Grid, Border Beam, Shine Border, Text Animate, Pulsating Button, Avatar Circles
|
||||
|
||||
**Vision**:
|
||||
- Bento Grid of question cards
|
||||
- Hover triggers Border Beam
|
||||
- Click expands with Shine Border
|
||||
- Text Animate typing out answers
|
||||
- Pulsating Button for "More Questions?"
|
||||
- Avatar Circles showing "5,000+ developers trust claude-mem"
|
||||
|
||||
---
|
||||
|
||||
## BONUS: Testimonials Section (Not in Original)
|
||||
|
||||
### Idea 1: "Social Proof Marquee"
|
||||
**Components**: Marquee (3D), Magic Card, Avatar Circles, Highlighter, Shine Border
|
||||
|
||||
**Vision**:
|
||||
- Marquee component in 3D mode scrolling developer testimonials
|
||||
- Each testimonial in a Magic Card
|
||||
- Avatar Circles showing total developer count
|
||||
- Highlighter on impactful quote fragments
|
||||
- Shine Border around featured testimonial
|
||||
|
||||
---
|
||||
|
||||
## Component Usage Summary
|
||||
|
||||
| Component | Times Used (Winners) | Primary Purpose |
|
||||
|-----------|---------------------|-----------------|
|
||||
| **Magic Card** | 9 | Spotlight effects, containers |
|
||||
| **Text Animate** | 7 | Typing effects, reveals |
|
||||
| **Border Beam** | 6 | Connections, highlights |
|
||||
| **Highlighter** | 6 | Emphasis on key text |
|
||||
| **Animated List** | 5 | Sequential reveals |
|
||||
| **Confetti** | 5 | Celebrations, milestones |
|
||||
| **Shine Border** | 5 | Premium emphasis |
|
||||
| **Morphing Text** | 4 | Dynamic headlines |
|
||||
| **Orbiting Circles** | 4 | Data flow, ecosystems |
|
||||
| **Safari** | 4 | Browser mockups |
|
||||
| **Scratch To Reveal** | 4 | Interactive discovery |
|
||||
| **Pulsating Button** | 4 | CTAs |
|
||||
| **Grid Beams** | 3 | Tech backgrounds |
|
||||
| **Warp Background** | 3 | Depth, perspective |
|
||||
| **Arc Timeline** | 2 | Progress, history |
|
||||
| **Dock** | 1 | Navigation selector |
|
||||
| **Aurora Text** | 1 | Premium headlines |
|
||||
| **Bento Grid** | 1 | Layout organization |
|
||||
|
||||
## Design Principles
|
||||
|
||||
1. **Show, Don't Tell**: Use animations to demonstrate concepts (memory persistence, data flow)
|
||||
2. **Interactive Discovery**: Scratch-to-reveal and interactive elements engage users
|
||||
3. **Visual Metaphors**: Orbiting circles for data flow, layers for architecture
|
||||
4. **Celebration**: Confetti at key moments creates joy
|
||||
5. **Progressive Disclosure**: Animated lists and timelines reveal information naturally
|
||||
6. **Spatial Depth**: Warp backgrounds and z-space create dimensional understanding
|
||||
7. **Consistent Magic**: Reuse components (Magic Card, Border Beam) for cohesion
|
||||
@@ -1,389 +0,0 @@
|
||||
# Landing Page Ideas - Ranked Analysis
|
||||
|
||||
Ranking criteria (1-10 scale):
|
||||
1. **Creativity**: How novel and unexpected is the approach?
|
||||
2. **Storytelling**: How effectively does it communicate the value?
|
||||
3. **Intuitive**: How easily will users understand it?
|
||||
4. **Feasibility**: How practical is implementation?
|
||||
5. **Delight**: How much joy does it create?
|
||||
|
||||
---
|
||||
|
||||
## HERO SECTION Rankings
|
||||
|
||||
### Idea 1: "Fading Memory" Effect ⭐ WINNER (42/50)
|
||||
- **Creativity**: 9/10 - Scratch-to-reveal pain point is unexpected
|
||||
- **Storytelling**: 9/10 - Morphing text and orbiting circles tell complete story
|
||||
- **Intuitive**: 8/10 - Orbiting content makes memory concept clear
|
||||
- **Feasibility**: 7/10 - Multiple complex components need coordination
|
||||
- **Delight**: 9/10 - Interactive scratch creates engagement
|
||||
|
||||
**Why it wins**: The scratch-to-reveal pain point makes the problem visceral. Orbiting circles create immediate visual understanding of what gets remembered.
|
||||
|
||||
### Idea 2: "Memory Timeline" Hero (39/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 8/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
### Idea 3: "Brain Storage" Visualization (36/50)
|
||||
- **Creativity**: 6/10
|
||||
- **Storytelling**: 7/10
|
||||
- **Intuitive**: 7/10
|
||||
- **Feasibility**: 9/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
---
|
||||
|
||||
## BEFORE/AFTER COMPARISON Rankings
|
||||
|
||||
### Idea 1: "Split Screen Wipe" ⭐ WINNER (44/50)
|
||||
- **Creativity**: 8/10 - Clean comparison approach
|
||||
- **Storytelling**: 10/10 - Side-by-side is the clearest possible comparison
|
||||
- **Intuitive**: 10/10 - Immediately obvious what's different
|
||||
- **Feasibility**: 8/10 - Safari mockups are well-supported
|
||||
- **Delight**: 8/10 - Fade vs persist is satisfying
|
||||
|
||||
**Why it wins**: Safari browser mockups provide immediate familiarity. The contrast between fading (Before) and persistent with Border Beam (After) is crystal clear storytelling.
|
||||
|
||||
### Idea 2: "Memory Decay Visualization" (40/50)
|
||||
- **Creativity**: 9/10
|
||||
- **Storytelling**: 9/10
|
||||
- **Intuitive**: 8/10
|
||||
- **Feasibility**: 7/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
### Idea 3: "Conversation Replay" (40/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 9/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
---
|
||||
|
||||
## REAL EXAMPLES Rankings
|
||||
|
||||
### Idea 2: "Timeline Story" ⭐ WINNER (44/50)
|
||||
- **Creativity**: 9/10 - Arc timeline for session progression is novel
|
||||
- **Storytelling**: 10/10 - Timeline naturally shows progression over time
|
||||
- **Intuitive**: 9/10 - Timeline metaphor is universally understood
|
||||
- **Feasibility**: 7/10 - Complex interaction between timeline and orbiting elements
|
||||
- **Delight**: 9/10 - Orbiting context around nodes is magical
|
||||
|
||||
**Why it wins**: Arc Timeline naturally communicates the "across sessions" aspect. Orbiting circles showing related context (files, decisions, bugs) is brilliant visual storytelling.
|
||||
|
||||
### Idea 1: "Tabbed Experience" (41/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 9/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 3: "Memory Card Flip" (35/50)
|
||||
- **Creativity**: 8/10
|
||||
- **Storytelling**: 7/10
|
||||
- **Intuitive**: 6/10
|
||||
- **Feasibility**: 6/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
---
|
||||
|
||||
## HOW IT WORKS Rankings
|
||||
|
||||
### Idea 3: "Layered Depth Model" ⭐ WINNER (43/50)
|
||||
- **Creativity**: 9/10 - Spatial depth for understanding layers is clever
|
||||
- **Storytelling**: 9/10 - Visual depth communicates layered architecture
|
||||
- **Intuitive**: 10/10 - Layers immediately convey hierarchy and flow
|
||||
- **Feasibility**: 6/10 - Z-space perspective requires careful implementation
|
||||
- **Delight**: 9/10 - Morphing text showing transformation is satisfying
|
||||
|
||||
**Why it wins**: Depth/perspective creates intuitive understanding of the layered architecture. Morphing text showing state transformation ("Capturing" → "Storing") tells the story perfectly.
|
||||
|
||||
### Idea 1: "Animated Data Flow" (42/50)
|
||||
- **Creativity**: 8/10
|
||||
- **Storytelling**: 9/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 8/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 2: "Arc Timeline as Process" (37/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 8/10
|
||||
- **Feasibility**: 7/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
---
|
||||
|
||||
## WHAT GETS REMEMBERED Rankings
|
||||
|
||||
### Idea 2: "Memory Bank Slots" ⭐ WINNER (41/50)
|
||||
- **Creativity**: 9/10 - Memory bank metaphor with scratch-to-reveal
|
||||
- **Storytelling**: 8/10 - Discovery process tells the story
|
||||
- **Intuitive**: 8/10 - Bank slot metaphor is clear
|
||||
- **Feasibility**: 7/10 - Six scratch-to-reveal elements need optimization
|
||||
- **Delight**: 9/10 - Gamification through scratching is highly engaging
|
||||
|
||||
**Why it wins**: Scratch-to-reveal gamification makes exploring features fun. Discovering what gets saved creates memorable engagement.
|
||||
|
||||
### Idea 3: "Collector Animation" (41/50 - tied)
|
||||
- **Creativity**: 8/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 8/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 1: "Checkbox Delight" (40/50)
|
||||
- **Creativity**: 6/10
|
||||
- **Storytelling**: 7/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 10/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
---
|
||||
|
||||
## POWERFUL SEARCH Rankings
|
||||
|
||||
### Idea 1: "Live Search Demo" ⭐ WINNER (44/50)
|
||||
- **Creativity**: 7/10 - Straightforward but effective
|
||||
- **Storytelling**: 10/10 - Actually showing search in action is perfect
|
||||
- **Intuitive**: 10/10 - Real search demo is immediately clear
|
||||
- **Feasibility**: 9/10 - Safari + Text Animate + Animated List is achievable
|
||||
- **Delight**: 8/10 - Watching search happen is satisfying
|
||||
|
||||
**Why it wins**: Showing actual search with real queries and results is the most effective storytelling. Users immediately understand the capability.
|
||||
|
||||
### Idea 2: "Search Radar" (39/50)
|
||||
- **Creativity**: 9/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 7/10
|
||||
- **Feasibility**: 6/10
|
||||
- **Delight**: 9/10
|
||||
|
||||
### Idea 3: "Memory Retrieval Visualization" (38/50)
|
||||
- **Creativity**: 8/10
|
||||
- **Storytelling**: 7/10
|
||||
- **Intuitive**: 8/10
|
||||
- **Feasibility**: 8/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
---
|
||||
|
||||
## THE NUMBERS Rankings
|
||||
|
||||
### Idea 2: "Progress Bar Transformation" ⭐ WINNER (45/50)
|
||||
- **Creativity**: 8/10 - Progress bars are familiar but effective
|
||||
- **Storytelling**: 10/10 - Visual transformation from bad to good is powerful
|
||||
- **Intuitive**: 10/10 - Everyone understands progress bars
|
||||
- **Feasibility**: 8/10 - Animated progress bars are well-supported
|
||||
- **Delight**: 9/10 - Watching bars transform is satisfying
|
||||
|
||||
**Why it wins**: Visual transformation of progress bars (red/low → green/high) is incredibly effective storytelling. Everyone intuitively understands the improvement.
|
||||
|
||||
### Idea 1: "Counting Animation" (42/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 9/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 9/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 3: "Flip Cards Reveal" (39/50)
|
||||
- **Creativity**: 8/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 7/10
|
||||
- **Feasibility**: 7/10
|
||||
- **Delight**: 9/10
|
||||
|
||||
---
|
||||
|
||||
## INSTALLATION Rankings
|
||||
|
||||
### Idea 1: "Copy-Paste Delight" ⭐ WINNER (44/50)
|
||||
- **Creativity**: 7/10 - Simple but right
|
||||
- **Storytelling**: 8/10 - Shows exactly what to do
|
||||
- **Intuitive**: 10/10 - Terminal + copy buttons is universal pattern
|
||||
- **Feasibility**: 10/10 - Very achievable
|
||||
- **Delight**: 9/10 - Confetti celebration seals the deal
|
||||
|
||||
**Why it wins**: Simplicity wins for installation instructions. Confetti celebration when done creates satisfying completion.
|
||||
|
||||
### Idea 2: "Progress Stepper" (42/50)
|
||||
- **Creativity**: 8/10
|
||||
- **Storytelling**: 9/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 8/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 3: "Interactive Terminal" (41/50)
|
||||
- **Creativity**: 9/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 8/10
|
||||
- **Feasibility**: 7/10
|
||||
- **Delight**: 9/10
|
||||
|
||||
---
|
||||
|
||||
## UNDER THE HOOD Rankings
|
||||
|
||||
### Idea 2: "Layered Stack" ⭐ WINNER (44/50)
|
||||
- **Creativity**: 9/10 - Layers with z-depth is clever
|
||||
- **Storytelling**: 9/10 - Stacking shows dependency hierarchy
|
||||
- **Intuitive**: 10/10 - Stack metaphor is perfect for architecture
|
||||
- **Feasibility**: 7/10 - Perspective effects require work
|
||||
- **Delight**: 9/10 - Slides revealing layers is satisfying
|
||||
|
||||
**Why it wins**: Layered stack with perspective visually explains the architecture hierarchy perfectly. Each layer sliding out to reveal itself tells the dependency story.
|
||||
|
||||
### Idea 3: "Technical Orbits" (43/50)
|
||||
- **Creativity**: 10/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 8/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 1: "System Diagram" (40/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 9/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
---
|
||||
|
||||
## USE CASES Rankings
|
||||
|
||||
### Idea 2: "Role Selector" ⭐ WINNER (46/50)
|
||||
- **Creativity**: 9/10 - Dock as role selector is novel
|
||||
- **Storytelling**: 9/10 - Interactive selection tells personalized stories
|
||||
- **Intuitive**: 10/10 - Dock interface is familiar and clear
|
||||
- **Feasibility**: 8/10 - Dock + expanding cards is achievable
|
||||
- **Delight**: 10/10 - Confetti for "your" use case is pure joy
|
||||
|
||||
**Why it wins**: Interactive Dock selector with confetti when you find "your" use case creates personal connection and delight. Highest delight score overall!
|
||||
|
||||
### Idea 3: "Story Scenarios" (41/50)
|
||||
- **Creativity**: 8/10
|
||||
- **Storytelling**: 10/10
|
||||
- **Intuitive**: 8/10
|
||||
- **Feasibility**: 7/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 1: "User Journey Cards" (40/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 9/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
---
|
||||
|
||||
## FAQ Rankings
|
||||
|
||||
### Idea 2: "Scratch to Answer" ⭐ WINNER (42/50)
|
||||
- **Creativity**: 9/10 - Making FAQ interactive is fresh
|
||||
- **Storytelling**: 8/10 - Discovery process engages
|
||||
- **Intuitive**: 8/10 - Scratch metaphor is understood
|
||||
- **Feasibility**: 7/10 - Multiple scratch elements need optimization
|
||||
- **Delight**: 10/10 - Scratching makes FAQs fun!
|
||||
|
||||
**Why it wins**: Scratch-to-reveal makes FAQs engaging instead of boring. Confetti on important answers (like "Fully private") creates moments of delight.
|
||||
|
||||
### Idea 3: "Interactive Q&A" (41/50)
|
||||
- **Creativity**: 7/10
|
||||
- **Storytelling**: 8/10
|
||||
- **Intuitive**: 9/10
|
||||
- **Feasibility**: 9/10
|
||||
- **Delight**: 8/10
|
||||
|
||||
### Idea 1: "Expandable Cards" (40/50)
|
||||
- **Creativity**: 6/10
|
||||
- **Storytelling**: 7/10
|
||||
- **Intuitive**: 10/10
|
||||
- **Feasibility**: 10/10
|
||||
- **Delight**: 7/10
|
||||
|
||||
---
|
||||
|
||||
## Overall Component Winners
|
||||
|
||||
### Most Effective Components
|
||||
1. **Magic Card** (9 winning sections) - Versatile spotlight effects
|
||||
2. **Text Animate** (7 sections) - Essential for reveals and typing effects
|
||||
3. **Border Beam** (6 sections) - Perfect for connections and highlights
|
||||
4. **Scratch To Reveal** (4 sections) - Highest delight factor
|
||||
5. **Confetti** (5 sections) - Celebration moments
|
||||
|
||||
### Highest Delight Components
|
||||
1. Scratch To Reveal - 10/10 in FAQ, 9/10 in Features
|
||||
2. Confetti - Creates joy at key moments
|
||||
3. Dock - 10/10 for use case selection
|
||||
4. Orbiting Circles - 9/10 for data visualization
|
||||
|
||||
### Best Storytelling Components
|
||||
1. Arc Timeline - Perfect for progression narratives
|
||||
2. Safari - Immediately familiar, great for demos
|
||||
3. Progress Bars - Universal understanding of improvement
|
||||
4. Layered Stack - Architecture hierarchy storytelling
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
### High Priority (Core Experience)
|
||||
1. **Hero** - First impression is critical
|
||||
2. **Before/After** - Core value proposition
|
||||
3. **Installation** - Conversion point
|
||||
4. **The Numbers** - Proof of value
|
||||
|
||||
### Medium Priority (Supporting Narrative)
|
||||
1. **Real Examples** - Concrete use cases
|
||||
2. **How It Works** - Understanding the system
|
||||
3. **Powerful Search** - Feature highlight
|
||||
|
||||
### Lower Priority (Deep Dive)
|
||||
1. **What Gets Remembered** - Feature details
|
||||
2. **Under The Hood** - Technical deep dive
|
||||
3. **Use Cases** - Audience segmentation
|
||||
4. **FAQ** - Support content
|
||||
|
||||
---
|
||||
|
||||
## Technical Considerations
|
||||
|
||||
### Performance Concerns
|
||||
- **Scratch To Reveal**: 4 instances across page - needs optimization
|
||||
- **Orbiting Circles**: Multiple orbits can be CPU intensive
|
||||
- **Particles**: Use sparingly, can impact performance
|
||||
- **Z-space/Perspective**: May have cross-browser issues
|
||||
|
||||
### Accessibility Considerations
|
||||
- **Scratch To Reveal**: Needs keyboard alternative
|
||||
- **Confetti**: Should respect `prefers-reduced-motion`
|
||||
- **Animations**: All should be pausable/stoppable
|
||||
- **Color Contrast**: Aurora/gradient text needs testing
|
||||
|
||||
### Browser Compatibility
|
||||
- **Safari Component**: Meta - using Safari to show Safari
|
||||
- **Grid Beams/Warp**: Check WebGL support
|
||||
- **Perspective transforms**: Test in Firefox, Safari
|
||||
|
||||
---
|
||||
|
||||
## Final Winning Lineup
|
||||
|
||||
1. **Hero**: Fading Memory (42/50)
|
||||
2. **Before/After**: Split Screen Wipe (44/50)
|
||||
3. **Real Examples**: Timeline Story (44/50)
|
||||
4. **How It Works**: Layered Depth Model (43/50)
|
||||
5. **What Gets Remembered**: Memory Bank Slots (41/50)
|
||||
6. **Powerful Search**: Live Search Demo (44/50)
|
||||
7. **The Numbers**: Progress Bar Transformation (45/50) ⭐ HIGHEST SCORE
|
||||
8. **Installation**: Copy-Paste Delight (44/50)
|
||||
9. **Under The Hood**: Layered Stack (44/50)
|
||||
10. **Use Cases**: Role Selector (46/50) ⭐ HIGHEST DELIGHT
|
||||
11. **FAQ**: Scratch to Answer (42/50)
|
||||
|
||||
**Average Score**: 43.5/50 (87%)
|
||||
**Total Delight**: 94/110 (85%)
|
||||
@@ -1,134 +0,0 @@
|
||||
# Phase 1 Implementation - Complete ✅
|
||||
|
||||
Phase 1 of the REFACTOR-PLAN.md has been successfully implemented and tested.
|
||||
|
||||
## What Was Implemented
|
||||
|
||||
### 1. Database Schema (Migration 004)
|
||||
Created four new tables to support the SDK agent architecture:
|
||||
|
||||
- **`sdk_sessions`** - Tracks SDK streaming sessions
|
||||
- **`observation_queue`** - Message queue for pending observations
|
||||
- **`observations`** - Stores extracted observations from SDK
|
||||
- **`session_summaries`** - Stores structured session summaries
|
||||
|
||||
All tables include proper indexes for performance and foreign key constraints for data integrity.
|
||||
|
||||
### 2. Shared Database Layer
|
||||
Created `HooksDatabase` class ([src/services/sqlite/HooksDatabase.ts](src/services/sqlite/HooksDatabase.ts)) that provides:
|
||||
|
||||
- Simple, synchronous database operations for hooks
|
||||
- No complex logic - just basic CRUD operations
|
||||
- Optimized SQLite settings (WAL mode, foreign keys enabled)
|
||||
- Methods for all hook operations:
|
||||
- `getRecentSummaries()` - Retrieve session context
|
||||
- `createSDKSession()` - Initialize new session
|
||||
- `queueObservation()` - Add observation to queue
|
||||
- `storeObservation()` - Save SDK observations
|
||||
- `storeSummary()` - Save session summaries
|
||||
- And more...
|
||||
|
||||
### 3. Hook Functions
|
||||
Implemented all four hook functions in [src/hooks/](src/hooks/):
|
||||
|
||||
#### **context.ts** - SessionStart Hook
|
||||
- Shows user recent session context on startup
|
||||
- Formats summaries in markdown for Claude
|
||||
- Exits silently if no context or errors occur
|
||||
|
||||
#### **save.ts** - PostToolUse Hook
|
||||
- Queues tool observations for SDK processing
|
||||
- Skips low-value tools (TodoWrite, ListMcpResourcesTool)
|
||||
- Non-blocking - returns immediately
|
||||
|
||||
#### **new.ts** - UserPromptSubmit Hook
|
||||
- Initializes SDK session in database
|
||||
- Prepares for SDK worker spawn (TODO in Phase 2)
|
||||
- Non-blocking - returns immediately
|
||||
|
||||
#### **summary.ts** - Stop Hook
|
||||
- Queues FINALIZE message for SDK
|
||||
- Signals SDK to generate session summary
|
||||
- Non-blocking - returns immediately
|
||||
|
||||
### 4. CLI Integration
|
||||
Added four new commands to [src/bin/cli.ts](src/bin/cli.ts:227-274):
|
||||
|
||||
```bash
|
||||
claude-mem context # SessionStart hook
|
||||
claude-mem new # UserPromptSubmit hook
|
||||
claude-mem save # PostToolUse hook
|
||||
claude-mem summary # Stop hook
|
||||
```
|
||||
|
||||
All commands read JSON input from stdin and execute the corresponding hook function.
|
||||
|
||||
### 5. Testing
|
||||
Created comprehensive test suite ([test-phase1.ts](test-phase1.ts)) that validates:
|
||||
|
||||
- ✅ Database schema migration 004 applied correctly
|
||||
- ✅ All four tables exist
|
||||
- ✅ SDK session creation and retrieval
|
||||
- ✅ Observation queue operations
|
||||
- ✅ Observation and summary storage
|
||||
- ✅ Session status transitions
|
||||
|
||||
**All tests pass! 🎉**
|
||||
|
||||
## What's Left for Phase 2
|
||||
|
||||
The foundation is complete. Next steps:
|
||||
|
||||
1. **SDK Worker Process** - Implement the background agent that:
|
||||
- Polls observation queue
|
||||
- Sends observations to Claude SDK
|
||||
- Parses XML responses (`<observation>` and `<summary>` blocks)
|
||||
- Stores results in database
|
||||
|
||||
2. **SDK Prompts** - Implement the three prompt builders:
|
||||
- `buildInitPrompt()` - Initialize SDK agent
|
||||
- `buildObservationPrompt()` - Send tool observation
|
||||
- `buildFinalizePrompt()` - Request session summary
|
||||
|
||||
3. **Process Management** - Update [src/hooks/new.ts](src/hooks/new.ts:35-42) to spawn SDK worker as detached process
|
||||
|
||||
4. **End-to-End Testing** - Test with real Claude Code session
|
||||
|
||||
## File Changes
|
||||
|
||||
### New Files
|
||||
- [src/services/sqlite/HooksDatabase.ts](src/services/sqlite/HooksDatabase.ts) - Shared database layer
|
||||
- [src/hooks/context.ts](src/hooks/context.ts) - SessionStart hook
|
||||
- [src/hooks/save.ts](src/hooks/save.ts) - PostToolUse hook
|
||||
- [src/hooks/new.ts](src/hooks/new.ts) - UserPromptSubmit hook
|
||||
- [src/hooks/summary.ts](src/hooks/summary.ts) - Stop hook
|
||||
- [src/hooks/index.ts](src/hooks/index.ts) - Exports
|
||||
- [test-phase1.ts](test-phase1.ts) - Test suite
|
||||
|
||||
### Modified Files
|
||||
- [src/services/sqlite/migrations.ts](src/services/sqlite/migrations.ts:205-315) - Added migration 004
|
||||
- [src/services/sqlite/index.ts](src/services/sqlite/index.ts:13) - Exported HooksDatabase
|
||||
- [src/bin/cli.ts](src/bin/cli.ts:227-274) - Added hook commands
|
||||
|
||||
## Verification
|
||||
|
||||
To verify Phase 1 implementation:
|
||||
|
||||
```bash
|
||||
# Build
|
||||
bun run build
|
||||
|
||||
# Run tests
|
||||
bun test-phase1.ts
|
||||
|
||||
# Check hook commands exist
|
||||
./dist/claude-mem.min.js --help | grep -A 1 'context\|new\|save\|summary'
|
||||
```
|
||||
|
||||
All should pass without errors.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Ready to proceed to Phase 2: **SDK Worker Implementation**
|
||||
|
||||
The architecture is sound, the database layer is working, and all hook functions are ready to integrate with the SDK worker process.
|
||||
@@ -1,175 +0,0 @@
|
||||
# Phase 2 Implementation Complete
|
||||
|
||||
## Summary
|
||||
|
||||
Phase 2 of the SDK Worker Process has been successfully implemented. This phase adds the background agent architecture that processes tool observations and generates session summaries.
|
||||
|
||||
## Implementation Date
|
||||
|
||||
October 15, 2025
|
||||
|
||||
## Files Created
|
||||
|
||||
### 1. SDK Prompts Module
|
||||
- **File**: [src/sdk/prompts.ts](src/sdk/prompts.ts)
|
||||
- **Purpose**: Generates prompts for the Claude Agent SDK
|
||||
- **Functions**:
|
||||
- `buildInitPrompt()` - Initialize the memory agent
|
||||
- `buildObservationPrompt()` - Send tool observations to agent
|
||||
- `buildFinalizePrompt()` - Request session summary
|
||||
|
||||
### 2. XML Parser Module
|
||||
- **File**: [src/sdk/parser.ts](src/sdk/parser.ts)
|
||||
- **Purpose**: Parse XML responses from SDK agent
|
||||
- **Functions**:
|
||||
- `parseObservations()` - Extract observation blocks
|
||||
- `parseSummary()` - Extract session summary
|
||||
- **Features**:
|
||||
- Validates observation types (decision, bugfix, feature, refactor, discovery)
|
||||
- Validates all required summary fields
|
||||
- Handles file arrays in summaries
|
||||
- No external dependencies (uses regex)
|
||||
|
||||
### 3. SDK Worker Process
|
||||
- **File**: [src/sdk/worker.ts](src/sdk/worker.ts)
|
||||
- **Purpose**: Background agent that processes observations
|
||||
- **Features**:
|
||||
- Runs as detached background process
|
||||
- Uses Claude Agent SDK streaming input mode
|
||||
- Polls observation queue every 1 second
|
||||
- Parses and stores observations and summaries
|
||||
- Handles graceful shutdown via FINALIZE message
|
||||
- Automatic error handling and session status updates
|
||||
|
||||
### 4. SDK Index Module
|
||||
- **File**: [src/sdk/index.ts](src/sdk/index.ts)
|
||||
- **Purpose**: Export all SDK module functionality
|
||||
|
||||
### 5. Test Suite
|
||||
- **File**: [test-phase2.ts](test-phase2.ts)
|
||||
- **Coverage**:
|
||||
- SDK prompt generation (3 tests)
|
||||
- XML observation parsing (4 tests)
|
||||
- XML summary parsing (4 tests)
|
||||
- Database integration (3 tests)
|
||||
- **Result**: ✅ All 14 tests passing
|
||||
|
||||
## Files Modified
|
||||
|
||||
### 1. newHook Implementation
|
||||
- **File**: [src/hooks/new.ts](src/hooks/new.ts:38-61)
|
||||
- **Changes**:
|
||||
- Uncommented SDK worker spawn code
|
||||
- Added worker path resolution (dev vs production)
|
||||
- Spawns worker as detached process with stdio: 'ignore'
|
||||
- Worker receives session DB ID as argument
|
||||
|
||||
## Architecture Validation
|
||||
|
||||
### SDK Worker Flow
|
||||
1. ✅ newHook spawns worker as detached process
|
||||
2. ✅ Worker loads session from database
|
||||
3. ✅ Worker initializes SDK agent with streaming input
|
||||
4. ✅ Worker polls observation queue continuously
|
||||
5. ✅ Worker sends observations to SDK agent
|
||||
6. ✅ Worker parses XML responses
|
||||
7. ✅ Worker stores observations and summaries
|
||||
8. ✅ Worker handles FINALIZE message
|
||||
9. ✅ Worker updates session status
|
||||
|
||||
### Data Flow
|
||||
```
|
||||
User Prompt → newHook → Create SDK Session → Spawn Worker
|
||||
↓
|
||||
Initialize SDK Agent
|
||||
↓
|
||||
← Poll Observation Queue
|
||||
↓
|
||||
Send Observations to SDK
|
||||
↓
|
||||
← Parse XML Response
|
||||
↓
|
||||
Store in Database
|
||||
↓
|
||||
Wait for FINALIZE
|
||||
↓
|
||||
Generate Summary → Exit
|
||||
```
|
||||
|
||||
## Test Results
|
||||
|
||||
```bash
|
||||
$ bun test ./test-phase2.ts
|
||||
|
||||
✅ SDK Prompts (3 tests)
|
||||
✅ should build init prompt with all required sections
|
||||
✅ should build observation prompt with tool details
|
||||
✅ should build finalize prompt with session context
|
||||
|
||||
✅ XML Parser (8 tests)
|
||||
✅ parseObservations
|
||||
✅ should parse single observation
|
||||
✅ should parse multiple observations
|
||||
✅ should skip observations with invalid types
|
||||
✅ should handle observations with surrounding text
|
||||
✅ parseSummary
|
||||
✅ should parse complete summary with all fields
|
||||
✅ should handle empty file arrays
|
||||
✅ should return null if required fields are missing
|
||||
✅ should return null if no summary block found
|
||||
|
||||
✅ HooksDatabase Integration (3 tests)
|
||||
✅ should store and retrieve observations
|
||||
✅ should store and retrieve summaries
|
||||
✅ should queue and process observations
|
||||
|
||||
14 pass, 0 fail, 53 expect() calls
|
||||
Ran 14 tests across 1 file. [60.00ms]
|
||||
```
|
||||
|
||||
## Build Verification
|
||||
|
||||
```bash
|
||||
$ npm run build
|
||||
|
||||
📌 Version: 3.9.16
|
||||
✓ Bun detected
|
||||
✓ Cleaned dist directory
|
||||
✓ Bundle created
|
||||
✓ Shebang added
|
||||
✓ Made executable
|
||||
✅ Build complete! (344.57 KB)
|
||||
```
|
||||
|
||||
## Success Criteria
|
||||
|
||||
All Phase 2 success criteria have been met:
|
||||
|
||||
- [x] SDK worker runs as detached process
|
||||
- [x] Worker polls observation queue continuously
|
||||
- [x] Worker sends observations to Claude SDK
|
||||
- [x] Worker parses `<observation>` and `<summary>` XML correctly
|
||||
- [x] Worker stores results in database using HooksDatabase
|
||||
- [x] Worker handles FINALIZE message and exits gracefully
|
||||
- [x] All tests pass
|
||||
- [x] No blocking of main Claude Code session
|
||||
|
||||
## Known Limitations
|
||||
|
||||
1. **Bundled CLI**: The worker process is currently bundled into the main CLI. For production use, we may want to extract it as a separate executable.
|
||||
2. **No logging**: Worker runs with `stdio: 'ignore'` for non-blocking behavior. Consider adding file-based logging for debugging.
|
||||
|
||||
## Next Steps
|
||||
|
||||
Phase 2 is complete and ready for integration testing with a real Claude Code session. The next phase would involve:
|
||||
|
||||
1. Testing the full end-to-end flow with actual tool observations
|
||||
2. Implementing the `saveHook` to queue observations
|
||||
3. Implementing the `summaryHook` to send FINALIZE message
|
||||
4. Verifying the context hook retrieves summaries correctly
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [REFACTOR-PLAN.md](REFACTOR-PLAN.md) - Original refactor plan
|
||||
- [PHASE1-COMPLETE.md](PHASE1-COMPLETE.md) - Phase 1 completion
|
||||
- [PHASE2-PROMPT.md](PHASE2-PROMPT.md) - Phase 2 implementation requirements
|
||||
@@ -1,118 +0,0 @@
|
||||
# Phase 2 Implementation Prompt
|
||||
|
||||
Use this prompt to start a new chat for Phase 2 implementation:
|
||||
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
I'm implementing a refactor of the claude-mem memory system based on [REFACTOR-PLAN.md](REFACTOR-PLAN.md).
|
||||
|
||||
**Phase 1 is complete** (see [PHASE1-COMPLETE.md](PHASE1-COMPLETE.md)):
|
||||
- ✅ Database schema with migration 004
|
||||
- ✅ HooksDatabase shared layer
|
||||
- ✅ All four hook functions (context, new, save, summary)
|
||||
- ✅ CLI integration and tests passing
|
||||
|
||||
## Task
|
||||
|
||||
Implement **Phase 2: SDK Worker Process**
|
||||
|
||||
According to [REFACTOR-PLAN.md](REFACTOR-PLAN.md#2-userpromptsubmit-hook) (lines 296-423), I need to:
|
||||
|
||||
1. **Create SDK Worker Process** (`src/sdk/worker.ts`)
|
||||
- Uses Agent SDK streaming input mode
|
||||
- AsyncIterable message generator that:
|
||||
- Yields initial prompt
|
||||
- Polls observation_queue table
|
||||
- Yields observation prompts
|
||||
- Handles FINALIZE message
|
||||
- Parses SDK responses for `<observation>` and `<summary>` XML blocks
|
||||
- Stores results using HooksDatabase methods
|
||||
|
||||
2. **Create SDK Prompts** (`src/sdk/prompts.ts`)
|
||||
- `buildInitPrompt()` - Initialize agent (see REFACTOR-PLAN.md:537-595)
|
||||
- `buildObservationPrompt()` - Send tool observation (see REFACTOR-PLAN.md:601-634)
|
||||
- `buildFinalizePrompt()` - Request summary (see REFACTOR-PLAN.md:640-692)
|
||||
|
||||
3. **Create XML Parser** (`src/sdk/parser.ts`)
|
||||
- Parse `<observation>` blocks with `<type>` and `<text>`
|
||||
- Parse `<summary>` blocks with 8 required fields
|
||||
- Extract file arrays from `<file>` child elements
|
||||
|
||||
4. **Update newHook** ([src/hooks/new.ts](src/hooks/new.ts:35-42))
|
||||
- Uncomment SDK worker spawn code
|
||||
- Pass session ID to worker
|
||||
- Detached process with stdio: 'ignore'
|
||||
|
||||
5. **Test End-to-End**
|
||||
- Create test that simulates full lifecycle
|
||||
- Verify observations are queued, processed, and stored
|
||||
- Verify summary generation works
|
||||
|
||||
## Key Requirements
|
||||
|
||||
From [REFACTOR-PLAN.md](REFACTOR-PLAN.md):
|
||||
|
||||
- Use `@anthropic-ai/claude-agent-sdk` query function with streaming input mode
|
||||
- Model: `claude-sonnet-4-5`
|
||||
- Use `disallowedTools: ['Glob', 'Grep', 'ListMcpResourcesTool', 'WebSearch']`
|
||||
- Message generator yields `{ role: "user", content: string }` objects
|
||||
- Capture SDK session ID from system init message
|
||||
- Poll observation queue every 1 second
|
||||
- Use AbortController for graceful cancellation
|
||||
- Parse XML with a library (not regex) - suggest fast-xml-parser
|
||||
- Store observations and summaries using HooksDatabase methods
|
||||
|
||||
## Architecture Reference
|
||||
|
||||
The SDK worker is a **synthesis engine** that:
|
||||
- Receives tool observations (not raw data)
|
||||
- Extracts meaningful insights
|
||||
- Stores atomic observations in SQLite
|
||||
- Generates structured summaries at session end
|
||||
|
||||
See [REFACTOR-PLAN.md](REFACTOR-PLAN.md#visual-overview) (lines 69-119) for the full architecture diagram.
|
||||
|
||||
## Files to Create
|
||||
|
||||
1. `src/sdk/worker.ts` - Main SDK worker process
|
||||
2. `src/sdk/prompts.ts` - Prompt builders
|
||||
3. `src/sdk/parser.ts` - XML response parser
|
||||
4. `src/sdk/index.ts` - Exports
|
||||
5. `test-phase2.ts` - End-to-end tests
|
||||
|
||||
## Files to Modify
|
||||
|
||||
1. [src/hooks/new.ts](src/hooks/new.ts:35-42) - Spawn worker process
|
||||
2. [package.json](package.json) - May need to add fast-xml-parser dependency
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
1. Unit tests for prompts (verify prompt structure)
|
||||
2. Unit tests for parser (verify XML parsing)
|
||||
3. Integration test for worker (mock SDK responses)
|
||||
4. End-to-end test (simulate full observation → summary flow)
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] SDK worker runs as detached process
|
||||
- [ ] Worker polls observation queue continuously
|
||||
- [ ] Worker sends observations to Claude SDK
|
||||
- [ ] Worker parses `<observation>` and `<summary>` XML correctly
|
||||
- [ ] Worker stores results in database using HooksDatabase
|
||||
- [ ] Worker handles FINALIZE message and exits gracefully
|
||||
- [ ] All tests pass
|
||||
- [ ] No blocking of main Claude Code session
|
||||
|
||||
## Notes
|
||||
|
||||
- Keep hooks fast and non-blocking (they already are)
|
||||
- SDK worker is fire-and-forget background process
|
||||
- Use HooksDatabase methods (already implemented in Phase 1)
|
||||
- Follow the exact prompt formats from REFACTOR-PLAN.md
|
||||
- Use proper TypeScript types from Agent SDK
|
||||
|
||||
---
|
||||
|
||||
**Start with:** Create the SDK prompts module first, then the parser, then the worker. Test each piece before integrating.
|
||||
@@ -1,271 +0,0 @@
|
||||
# Phase 3 Implementation Complete ✅
|
||||
|
||||
## Summary
|
||||
|
||||
Phase 3 of the claude-mem architecture refactor has been successfully completed. This phase integrated all hook functions with the database layer and validated the complete end-to-end lifecycle through comprehensive testing.
|
||||
|
||||
## Implementation Date
|
||||
|
||||
October 15, 2025
|
||||
|
||||
## What Was Implemented
|
||||
|
||||
### 1. Hook Integration Verification
|
||||
|
||||
All four hook functions were verified to be working correctly with the database layer:
|
||||
|
||||
#### **[contextHook](src/hooks/context.ts)** - SessionStart Hook
|
||||
- ✅ Retrieves recent session summaries from database
|
||||
- ✅ Formats summaries in markdown for Claude consumption
|
||||
- ✅ Handles missing summaries gracefully
|
||||
- ✅ Only runs on startup (skips resume)
|
||||
- ✅ Fast, non-blocking operation (< 50ms)
|
||||
|
||||
#### **[newHook](src/hooks/new.ts)** - UserPromptSubmit Hook
|
||||
- ✅ Creates SDK session record in database
|
||||
- ✅ Spawns SDK worker as detached background process
|
||||
- ✅ Handles duplicate sessions gracefully
|
||||
- ✅ Fast, non-blocking operation (< 50ms)
|
||||
- ✅ Returns immediately with suppressed output
|
||||
|
||||
#### **[saveHook](src/hooks/save.ts)** - PostToolUse Hook
|
||||
- ✅ Queues tool observations to database
|
||||
- ✅ Filters out low-value tools (TodoWrite, ListMcpResourcesTool)
|
||||
- ✅ Handles missing sessions gracefully
|
||||
- ✅ Fast, non-blocking operation (< 50ms)
|
||||
- ✅ Stores JSON-stringified tool input/output
|
||||
|
||||
#### **[summaryHook](src/hooks/summary.ts)** - Stop Hook
|
||||
- ✅ Sends FINALIZE message to observation queue
|
||||
- ✅ Triggers SDK worker to generate session summary
|
||||
- ✅ Handles missing sessions gracefully
|
||||
- ✅ Fast, non-blocking operation (< 50ms)
|
||||
|
||||
### 2. Comprehensive Test Suite
|
||||
|
||||
Created two new comprehensive test files:
|
||||
|
||||
#### **[test-phase3-integration.ts](test-phase3-integration.ts)**
|
||||
Tests individual hook database integration:
|
||||
- ✅ Session management (create, find, update, complete)
|
||||
- ✅ Observation queue (queue, retrieve, process, FINALIZE)
|
||||
- ✅ Observations storage (store and retrieve)
|
||||
- ✅ Summaries (store and retrieve, project isolation)
|
||||
- **9 tests, all passing**
|
||||
|
||||
#### **[test-phase3-e2e.ts](test-phase3-e2e.ts)**
|
||||
Tests complete session lifecycle:
|
||||
- ✅ Full lifecycle: new → save → summary → context
|
||||
- ✅ Performance requirements (< 50ms per operation)
|
||||
- ✅ Interrupted sessions (observations remain in queue)
|
||||
- ✅ Multiple concurrent projects (project isolation)
|
||||
- **4 tests, all passing**
|
||||
|
||||
### 3. Database Integration
|
||||
|
||||
All hooks correctly use the [HooksDatabase](src/services/sqlite/HooksDatabase.ts) layer:
|
||||
- ✅ Simple, synchronous database operations
|
||||
- ✅ Foreign key constraints enforced
|
||||
- ✅ Proper session lifecycle management
|
||||
- ✅ Atomic operations with WAL mode
|
||||
- ✅ No complex logic in hooks (delegated to SDK worker)
|
||||
|
||||
### 4. CLI Commands
|
||||
|
||||
All four CLI commands verified working:
|
||||
- ✅ `claude-mem context` - [src/bin/cli.ts:228-234](src/bin/cli.ts#L228-L234)
|
||||
- ✅ `claude-mem new` - [src/bin/cli.ts:237-243](src/bin/cli.ts#L237-L243)
|
||||
- ✅ `claude-mem save` - [src/bin/cli.ts:246-252](src/bin/cli.ts#L246-L252)
|
||||
- ✅ `claude-mem summary` - [src/bin/cli.ts:255-261](src/bin/cli.ts#L255-L261)
|
||||
|
||||
All commands:
|
||||
- Read JSON from stdin
|
||||
- Execute corresponding hook function
|
||||
- Return proper JSON response
|
||||
- Exit with code 0
|
||||
|
||||
## Test Results
|
||||
|
||||
### All Tests Passing
|
||||
```bash
|
||||
Phase 1: ✅ Database schema and HooksDatabase tests
|
||||
Phase 2: ✅ 14 tests (SDK prompts, parser, database integration)
|
||||
Phase 3: ✅ 13 tests (9 integration + 4 e2e)
|
||||
Total: ✅ 27+ tests passing
|
||||
```
|
||||
|
||||
### Performance Validation
|
||||
```
|
||||
Average operation time: 0.04ms (well under 50ms requirement)
|
||||
Maximum operation time: 1.60ms (well under 100ms threshold)
|
||||
```
|
||||
|
||||
### Build Verification
|
||||
```bash
|
||||
✅ Build complete! (344.57 KB)
|
||||
Output: dist/claude-mem.min.js
|
||||
```
|
||||
|
||||
## Architecture Validation
|
||||
|
||||
### ✅ Complete Hook Lifecycle
|
||||
|
||||
```
|
||||
1. SessionStart (contextHook)
|
||||
↓ Retrieves recent summaries from database
|
||||
↓ Formats for Claude consumption
|
||||
↓
|
||||
2. UserPromptSubmit (newHook)
|
||||
↓ Creates SDK session
|
||||
↓ Spawns background SDK worker
|
||||
↓
|
||||
3. PostToolUse (saveHook)
|
||||
↓ Queues observations
|
||||
↓ SDK worker polls queue
|
||||
↓ SDK processes observations
|
||||
↓ SDK stores meaningful insights
|
||||
↓
|
||||
4. Stop (summaryHook)
|
||||
↓ Sends FINALIZE message
|
||||
↓ SDK generates structured summary
|
||||
↓ SDK stores summary in database
|
||||
↓
|
||||
5. Next SessionStart
|
||||
↓ New context retrieved
|
||||
⟲ Cycle repeats
|
||||
```
|
||||
|
||||
### ✅ Non-Blocking Requirements
|
||||
|
||||
All hooks meet the < 50ms performance requirement:
|
||||
- **contextHook**: Retrieves summaries (simple SELECT query)
|
||||
- **newHook**: Creates session + spawns detached process
|
||||
- **saveHook**: Inserts into queue (simple INSERT)
|
||||
- **summaryHook**: Inserts FINALIZE message (simple INSERT)
|
||||
|
||||
SDK worker runs in background independently of main session.
|
||||
|
||||
### ✅ Error Handling
|
||||
|
||||
All hooks handle errors gracefully:
|
||||
- Database errors → log + continue
|
||||
- Missing sessions → silently continue
|
||||
- Process spawn failures → log + continue
|
||||
- Never block Claude Code session
|
||||
|
||||
### ✅ Data Integrity
|
||||
|
||||
Foreign key constraints enforce referential integrity:
|
||||
- Observations reference SDK sessions
|
||||
- Summaries reference SDK sessions
|
||||
- Queue items reference SDK sessions
|
||||
- Sessions reference Claude sessions
|
||||
|
||||
## Success Criteria Met
|
||||
|
||||
All Phase 3 success criteria have been achieved:
|
||||
|
||||
- [x] saveHook queues observations to database
|
||||
- [x] summaryHook sends FINALIZE message
|
||||
- [x] contextHook retrieves and formats summaries
|
||||
- [x] End-to-end test passes (full lifecycle)
|
||||
- [x] All hooks respond in < 50ms
|
||||
- [x] Worker processes observations and generates summary
|
||||
- [x] CLI commands work correctly
|
||||
- [x] All tests pass (27+ tests)
|
||||
- [x] Build succeeds (344.57 KB)
|
||||
- [x] Database foreign key constraints enforced
|
||||
- [x] Multiple concurrent projects supported
|
||||
- [x] Interrupted sessions handled gracefully
|
||||
|
||||
## Files Modified
|
||||
|
||||
### Hook Implementations (Already Complete)
|
||||
- [src/hooks/context.ts](src/hooks/context.ts) - SessionStart hook
|
||||
- [src/hooks/save.ts](src/hooks/save.ts) - PostToolUse hook
|
||||
- [src/hooks/new.ts](src/hooks/new.ts) - UserPromptSubmit hook
|
||||
- [src/hooks/summary.ts](src/hooks/summary.ts) - Stop hook
|
||||
|
||||
### Test Files Created
|
||||
- [test-phase3-integration.ts](test-phase3-integration.ts) - Hook database integration tests
|
||||
- [test-phase3-e2e.ts](test-phase3-e2e.ts) - End-to-end lifecycle tests
|
||||
|
||||
### CLI Integration (Already Complete)
|
||||
- [src/bin/cli.ts](src/bin/cli.ts) - CLI commands for all hooks
|
||||
|
||||
## Install Flow Updates
|
||||
|
||||
### ✅ CLI-Based Hook Architecture
|
||||
|
||||
Updated the install flow to use the new CLI-based architecture:
|
||||
|
||||
**Before (Old Architecture):**
|
||||
- Installed hook template files (`session-start.js`, etc.)
|
||||
- Copied shared helper modules
|
||||
- Configured settings.json to point to hook files
|
||||
|
||||
**After (New Architecture):**
|
||||
- Hooks are CLI commands: `claude-mem context`, `claude-mem new`, `claude-mem save`, `claude-mem summary`
|
||||
- Settings.json configured directly with CLI commands
|
||||
- No separate hook files needed
|
||||
- Simpler installation and maintenance
|
||||
|
||||
**Updated Install Steps:**
|
||||
```javascript
|
||||
settings.hooks.SessionStart = [{ type: "command", command: "claude-mem context", timeout: 180 }]
|
||||
settings.hooks.Stop = [{ type: "command", command: "claude-mem summary", timeout: 60 }]
|
||||
settings.hooks.UserPromptSubmit = [{ type: "command", command: "claude-mem new", timeout: 60 }]
|
||||
settings.hooks.PostToolUse = [{ type: "command", command: "claude-mem save", timeout: 180, matcher: "*" }]
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
- ✅ Single source of truth (CLI implementation)
|
||||
- ✅ No hook file synchronization issues
|
||||
- ✅ Easier debugging (just test CLI commands)
|
||||
- ✅ Simpler installation process
|
||||
- ✅ Better maintainability
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [REFACTOR-PLAN.md](REFACTOR-PLAN.md) - Complete architecture plan
|
||||
- [PHASE1-COMPLETE.md](PHASE1-COMPLETE.md) - Database & HooksDatabase layer
|
||||
- [PHASE2-COMPLETE.md](PHASE2-COMPLETE.md) - SDK worker process
|
||||
- **PHASE3-COMPLETE.md** (this document) - Hook integration & testing
|
||||
|
||||
## Next Steps
|
||||
|
||||
Phase 3 is complete! The claude-mem system is now ready for real-world testing with actual Claude Code sessions.
|
||||
|
||||
### Recommended Next Actions
|
||||
|
||||
1. **Manual Testing**
|
||||
- Configure hooks in `~/.config/claude-code/settings.json`
|
||||
- Run a real Claude Code session
|
||||
- Verify observations are queued
|
||||
- Verify summaries are generated
|
||||
- Verify context is injected on next session
|
||||
|
||||
2. **Monitoring & Debugging**
|
||||
- Add file-based logging to SDK worker
|
||||
- Monitor `~/.claude-mem/claude-mem.db` for data
|
||||
- Check observation queue processing
|
||||
- Verify summary generation
|
||||
|
||||
3. **Future Enhancements**
|
||||
- Extract SDK worker as separate executable (not bundled)
|
||||
- Add resumption support for interrupted SDK sessions
|
||||
- Implement retry logic for failed observations
|
||||
- Add telemetry and error reporting
|
||||
- Optimize database queries with additional indexes
|
||||
|
||||
## Conclusion
|
||||
|
||||
Phase 3 successfully completes the claude-mem architecture refactor. All three phases are now complete:
|
||||
|
||||
- ✅ **Phase 1**: Database schema and shared layer
|
||||
- ✅ **Phase 2**: SDK worker process and prompts
|
||||
- ✅ **Phase 3**: Hook integration and end-to-end testing
|
||||
|
||||
The system is architecturally sound, fully tested, and ready for production use!
|
||||
|
||||
🎉 **Refactor Complete!** 🎉
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Database Architecture"
|
||||
description: "SQLite schema, FTS5 search, and data storage"
|
||||
---
|
||||
|
||||
# Database Architecture
|
||||
|
||||
Claude-Mem uses SQLite 3 with the better-sqlite3 native module for persistent storage and FTS5 for full-text search.
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Plugin Hooks"
|
||||
description: "5 lifecycle hooks that power Claude-Mem"
|
||||
---
|
||||
|
||||
# Plugin Hooks
|
||||
|
||||
Claude-Mem integrates with Claude Code through 5 lifecycle hooks that capture events and inject context.
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "MCP Search Server"
|
||||
description: "7 search tools with examples and usage patterns"
|
||||
---
|
||||
|
||||
# MCP Search Server
|
||||
|
||||
Claude-Mem includes a Model Context Protocol (MCP) server that exposes 7 specialized search tools for querying stored observations and sessions.
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Architecture Overview"
|
||||
description: "System components and data flow in Claude-Mem"
|
||||
---
|
||||
|
||||
# Architecture Overview
|
||||
|
||||
## System Components
|
||||
@@ -148,13 +153,13 @@ claude-mem/
|
||||
## Component Details
|
||||
|
||||
### 1. Plugin Hooks
|
||||
See [hooks.md](hooks.md) for detailed hook documentation.
|
||||
See [Plugin Hooks](/architecture/hooks) for detailed hook documentation.
|
||||
|
||||
### 2. Worker Service
|
||||
See [worker-service.md](worker-service.md) for HTTP API and endpoints.
|
||||
See [Worker Service](/architecture/worker-service) for HTTP API and endpoints.
|
||||
|
||||
### 3. Database Layer
|
||||
See [database.md](database.md) for schema and FTS5 search.
|
||||
See [Database Architecture](/architecture/database) for schema and FTS5 search.
|
||||
|
||||
### 4. MCP Search Server
|
||||
See [mcp-search.md](mcp-search.md) for search tools and examples.
|
||||
See [MCP Search Server](/architecture/mcp-search) for search tools and examples.
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Worker Service"
|
||||
description: "HTTP API and PM2 process management"
|
||||
---
|
||||
|
||||
# Worker Service
|
||||
|
||||
The worker service is a long-running HTTP API built with Express.js and managed by PM2. It processes observations through the Claude Agent SDK separately from hook execution to prevent timeout issues.
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Configuration"
|
||||
description: "Environment variables and settings for Claude-Mem"
|
||||
---
|
||||
|
||||
# Configuration
|
||||
|
||||
## Environment Variables
|
||||
@@ -293,6 +298,6 @@ If port 37777 is already in use:
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Architecture Overview](architecture/overview.md) - Understand the system
|
||||
- [Troubleshooting](troubleshooting.md) - Common issues
|
||||
- [Development](development.md) - Building from source
|
||||
- [Architecture Overview](architecture/overview) - Understand the system
|
||||
- [Troubleshooting](troubleshooting) - Common issues
|
||||
- [Development](development) - Building from source
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Development"
|
||||
description: "Build from source, run tests, and contribute to Claude-Mem"
|
||||
---
|
||||
|
||||
# Development Guide
|
||||
|
||||
## Building from Source
|
||||
@@ -552,6 +557,6 @@ rm -rf plugin/scripts/*.js plugin/scripts/*.cjs
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Architecture Overview](architecture/overview.md) - Understand the system
|
||||
- [Configuration](configuration.md) - Customize Claude-Mem
|
||||
- [Troubleshooting](troubleshooting.md) - Common issues
|
||||
- [Architecture Overview](architecture/overview) - Understand the system
|
||||
- [Configuration](configuration) - Customize Claude-Mem
|
||||
- [Troubleshooting](troubleshooting) - Common issues
|
||||
@@ -0,0 +1,70 @@
|
||||
{
|
||||
"$schema": "https://mintlify.com/schema.json",
|
||||
"name": "Claude-Mem",
|
||||
"logo": {
|
||||
"dark": "/logo/dark.svg",
|
||||
"light": "/logo/light.svg"
|
||||
},
|
||||
"favicon": "/favicon.svg",
|
||||
"colors": {
|
||||
"primary": "#3B82F6",
|
||||
"light": "#EFF6FF",
|
||||
"dark": "#1E40AF",
|
||||
"background": {
|
||||
"dark": "#0F172A",
|
||||
"light": "#FFFFFF"
|
||||
}
|
||||
},
|
||||
"topbarLinks": [
|
||||
{
|
||||
"name": "GitHub",
|
||||
"url": "https://github.com/thedotmack/claude-mem"
|
||||
}
|
||||
],
|
||||
"topbarCtaButton": {
|
||||
"name": "Install",
|
||||
"url": "https://github.com/thedotmack/claude-mem#quick-start"
|
||||
},
|
||||
"tabs": [
|
||||
{
|
||||
"name": "Documentation",
|
||||
"url": "/"
|
||||
},
|
||||
{
|
||||
"name": "Architecture",
|
||||
"url": "/architecture"
|
||||
}
|
||||
],
|
||||
"navigation": [
|
||||
{
|
||||
"group": "Get Started",
|
||||
"pages": [
|
||||
"introduction",
|
||||
"installation",
|
||||
"usage/getting-started",
|
||||
"usage/search-tools"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Configuration & Development",
|
||||
"pages": [
|
||||
"configuration",
|
||||
"development",
|
||||
"troubleshooting"
|
||||
]
|
||||
},
|
||||
{
|
||||
"group": "Architecture",
|
||||
"pages": [
|
||||
"architecture/overview",
|
||||
"architecture/hooks",
|
||||
"architecture/worker-service",
|
||||
"architecture/database",
|
||||
"architecture/mcp-search"
|
||||
]
|
||||
}
|
||||
],
|
||||
"footerSocials": {
|
||||
"github": "https://github.com/thedotmack/claude-mem"
|
||||
}
|
||||
}
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Installation"
|
||||
description: "Install Claude-Mem plugin for persistent memory across sessions"
|
||||
---
|
||||
|
||||
# Installation Guide
|
||||
|
||||
## Quick Start
|
||||
@@ -99,10 +104,10 @@ v4.0.0 introduces breaking changes:
|
||||
- **MCP Search Server**: 7 new search tools with full-text search and citations
|
||||
- **Enhanced Architecture**: Improved plugin integration and data organization
|
||||
|
||||
See [CHANGELOG.md](../CHANGELOG.md) for complete details.
|
||||
See [CHANGELOG](https://github.com/thedotmack/claude-mem/blob/main/CHANGELOG.md) for complete details.
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Getting Started Guide](usage/getting-started.md) - Learn how Claude-Mem works automatically
|
||||
- [MCP Search Tools](usage/search-tools.md) - Query your project history
|
||||
- [Configuration](configuration.md) - Customize Claude-Mem behavior
|
||||
- [Getting Started Guide](usage/getting-started) - Learn how Claude-Mem works automatically
|
||||
- [MCP Search Tools](usage/search-tools) - Query your project history
|
||||
- [Configuration](configuration) - Customize Claude-Mem behavior
|
||||
@@ -0,0 +1,96 @@
|
||||
---
|
||||
title: "Introduction"
|
||||
description: "Persistent memory compression system for Claude Code"
|
||||
---
|
||||
|
||||
# Claude-Mem
|
||||
|
||||
**Persistent memory compression system for Claude Code**
|
||||
|
||||
Claude-Mem seamlessly preserves context across sessions by automatically capturing tool usage observations, generating semantic summaries, and making them available to future sessions. This enables Claude to maintain continuity of knowledge about projects even after sessions end or reconnect.
|
||||
|
||||
## Quick Start
|
||||
|
||||
Start a new Claude Code session in the terminal and enter the following commands:
|
||||
|
||||
```bash
|
||||
/plugin marketplace add thedotmack/claude-mem
|
||||
/plugin install claude-mem
|
||||
```
|
||||
|
||||
Restart Claude Code. Context from previous sessions will automatically appear in new sessions.
|
||||
|
||||
## Key Features
|
||||
|
||||
- 🧠 **Persistent Memory** - Context survives across sessions
|
||||
- 🔍 **7 Search Tools** - Query your project history via MCP
|
||||
- 🤖 **Automatic Operation** - No manual intervention required
|
||||
- 📊 **FTS5 Search** - Fast full-text search across observations
|
||||
- 🔗 **Citations** - Reference past decisions with `claude-mem://` URIs
|
||||
|
||||
## How It Works
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Session Start → Inject context from last 10 sessions │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ User Prompts → Create session, save user prompts │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Tool Executions → Capture observations (Read, Write, etc.) │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Worker Processes → Extract learnings via Claude Agent SDK │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
↓
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ Session Ends → Generate summary, ready for next session │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Core Components:**
|
||||
1. **5 Lifecycle Hooks** - SessionStart, UserPromptSubmit, PostToolUse, Stop, SessionEnd
|
||||
2. **Worker Service** - HTTP API on port 37777 managed by PM2
|
||||
3. **SQLite Database** - Stores sessions, observations, summaries with FTS5 search
|
||||
4. **7 MCP Search Tools** - Query historical context with citations
|
||||
|
||||
See [Architecture Overview](architecture/overview) for details.
|
||||
|
||||
## System Requirements
|
||||
|
||||
- **Node.js**: 18.0.0 or higher
|
||||
- **Claude Code**: Latest version with plugin support
|
||||
- **PM2**: Process manager (bundled - no global install required)
|
||||
- **SQLite 3**: For persistent storage (bundled)
|
||||
|
||||
## What's New in v4.2.3
|
||||
|
||||
**Security:**
|
||||
- Fixed FTS5 injection vulnerability in search functions
|
||||
- Added comprehensive test suite with 332 injection attack tests
|
||||
|
||||
**Fixes:**
|
||||
- Fixed ESM/CJS compatibility for getDirname function
|
||||
- Fixed Windows PowerShell compatibility in SessionStart hook
|
||||
- Cross-platform dependency installation now works on Windows, macOS, and Linux
|
||||
|
||||
## Next Steps
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Installation" icon="download" href="/installation">
|
||||
Quick start & advanced installation
|
||||
</Card>
|
||||
<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>
|
||||
<Card title="Search Tools" icon="magnifying-glass" href="/usage/search-tools">
|
||||
Query your project history
|
||||
</Card>
|
||||
</CardGroup>
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Troubleshooting"
|
||||
description: "Common issues and solutions for Claude-Mem"
|
||||
---
|
||||
|
||||
# Troubleshooting Guide
|
||||
|
||||
## Worker Service Issues
|
||||
@@ -664,6 +669,6 @@ If none of these solutions work:
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Configuration](configuration.md) - Customize Claude-Mem
|
||||
- [Development](development.md) - Build from source
|
||||
- [Architecture](architecture/overview.md) - Understand the system
|
||||
- [Configuration](configuration) - Customize Claude-Mem
|
||||
- [Development](development) - Build from source
|
||||
- [Architecture](architecture/overview) - Understand the system
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "Getting Started"
|
||||
description: "Learn how Claude-Mem works automatically in the background"
|
||||
---
|
||||
|
||||
# Getting Started with Claude-Mem
|
||||
|
||||
## Automatic Operation
|
||||
@@ -166,6 +171,6 @@ When you use `/clear`, the session doesn't end - it continues with a new prompt
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [MCP Search Tools](search-tools.md) - Learn how to search your project history
|
||||
- [Architecture Overview](../architecture/overview.md) - Understand how it works
|
||||
- [Troubleshooting](../troubleshooting.md) - Common issues and solutions
|
||||
- [MCP Search Tools](/usage/search-tools) - Learn how to search your project history
|
||||
- [Architecture Overview](/architecture/overview) - Understand how it works
|
||||
- [Troubleshooting](/troubleshooting) - Common issues and solutions
|
||||
@@ -1,3 +1,8 @@
|
||||
---
|
||||
title: "MCP Search Tools"
|
||||
description: "Query your project history with 7 specialized search tools"
|
||||
---
|
||||
|
||||
# MCP Search Tools Usage
|
||||
|
||||
Once claude-mem is installed as a plugin, 7 search tools become available in your Claude Code sessions for querying project history.
|
||||
@@ -416,6 +421,6 @@ search_sessions with query="[YOUR PROJECT NAME]" and orderBy="date_desc"
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [MCP Search Architecture](../architecture/mcp-search.md) - Technical details
|
||||
- [Database Schema](../architecture/database.md) - Understanding the data
|
||||
- [Getting Started](getting-started.md) - Automatic operation
|
||||
- [MCP Search Architecture](/architecture/mcp-search) - Technical details
|
||||
- [Database Schema](/architecture/database) - Understanding the data
|
||||
- [Getting Started](/usage/getting-started) - Automatic operation
|
||||
Reference in New Issue
Block a user