claude-mem/src-analysis.md

Claude-Mem Source Code Analysis Report

Executive Summary

Analyzed all 58 files in the /Users/alexnewman/Scripts/claude-mem/src directory. This report categorizes each file by purpose, usage status, and documents the cleanup of dead code files.

Cleanup Status: ✅ 7 dead code files successfully removed (51 files remaining)

---

Directory: src/bin (2 files)

src/bin/cleanup-duplicates.ts

• Purpose: Utility script to remove duplicate observations and summaries from the database
• Used?: No - Standalone CLI utility, not imported anywhere
• Notes: Maintenance tool for database cleanup. Keeps earliest entry (MIN(id)) for each duplicate group. Not part of the runtime system.

src/bin/import-xml-observations.ts

• Purpose: Import tool to restore XML observations back into SQLite database
• Used?: No - Standalone CLI utility, not imported anywhere
• Notes: Data migration tool. Parses XML timestamps and matches them to transcript files. Not part of the runtime system.

---

Directory: src/hooks (7 files, 1 deleted)

src/hooks/cleanup-hook.ts

• Purpose: SessionEnd hook that marks sessions as completed and notifies worker
• Used?: Yes - Built to plugin/scripts/cleanup-hook.js, registered in plugin/hooks/hooks.json
• Notes: Core hook, actively used

src/hooks/context-hook.ts

• Purpose: SessionStart hook that injects recent observations into Claude Code sessions
• Used?: Yes - Built to plugin/scripts/context-hook.js, registered in hooks.json, also called by user-message-hook
• Notes: Core hook displaying context timeline with progressive disclosure (index view)

src/hooks/hook-response.ts

• Purpose: Utility module for creating standardized hook responses
• Used?: Yes - Imported by new-hook.ts, save-hook.ts, summary-hook.ts
• Notes: Shared helper for hook JSON output

src/hooks/index.ts 🗑️ DELETED

• Purpose: Export barrel for hooks module
• Used?: No - Not imported anywhere
• Notes: DELETED. Exports were outdated (referenced context.js, save.js, etc. which don't exist). The actual hooks are built as standalone executables, not imported as modules.

src/hooks/new-hook.ts

• Purpose: UserPromptSubmit hook that creates session records and saves raw user prompts
• Used?: Yes - Built to plugin/scripts/new-hook.js, registered in hooks.json
• Notes: Core hook, actively used

src/hooks/save-hook.ts

• Purpose: PostToolUse hook that captures tool executions and sends to worker
• Used?: Yes - Built to plugin/scripts/save-hook.js, registered in hooks.json
• Notes: Core hook, actively used

src/hooks/summary-hook.ts

• Purpose: Stop hook that requests session summaries from worker
• Used?: Yes - Built to plugin/scripts/summary-hook.js, registered in hooks.json
• Notes: Core hook, actively used

src/hooks/user-message-hook.ts

• Purpose: SessionStart hook that displays context to users via stderr
• Used?: Yes - Built to plugin/scripts/user-message-hook.js, registered in hooks.json
• Notes: Runs context-hook via execSync to show colored output. Active hook.

---

Directory: src/sdk (3 files, 1 deleted)

src/sdk/index.ts 🗑️ DELETED

• Purpose: Export barrel for SDK module
• Used?: No - Not imported anywhere
• Notes: DELETED. Exported SDK functions but nothing imported from this module directly. Files import directly from prompts.ts and parser.ts instead.

src/sdk/parser.test.ts

• Purpose: Regression tests for XML parsing (v4.2.5 and v4.2.6 bugfixes)
• Used?: No - Test file, not part of runtime
• Notes: Test suite with 18 tests validating observation/summary parsing edge cases

src/sdk/parser.ts

• Purpose: XML parser for observation and summary blocks from SDK responses
• Used?: Yes - Imported by worker-service.ts
• Notes: Core parsing logic, actively used

src/sdk/prompts.ts

• Purpose: Prompt builders for Claude Agent SDK
• Used?: Yes - Imported by worker-service.ts
• Notes: Generates init, observation, and summary prompts for SDK agent

---

Directory: src/servers (1 file)

src/servers/search-server.ts

• Purpose: MCP search server exposing 9 search tools with hybrid Chroma + FTS5 search
• Used?: Yes - Built to plugin/search-server.mjs, configured in plugin/.mcp.json
• Notes: 1,782 lines. Core search server providing progressive disclosure search tools.

---

Directory: src/services/sqlite (6 files)

src/services/sqlite/Database.ts

• Purpose: Base database class with better-sqlite3
• Used?: Yes - Imported by SessionStore.ts, SessionSearch.ts, index.ts
• Notes: Foundation class for SQLite operations

src/services/sqlite/index.ts

• Purpose: Export barrel for sqlite module
• Used?: Yes - Imported by storage.ts
• Notes: Exports all store types and utilities

src/services/sqlite/migrations.ts

• Purpose: Database migration function for schema changes
• Used?: Yes - Imported by index.ts
• Notes: Handles SQLite schema migrations

src/services/sqlite/SessionSearch.ts

• Purpose: FTS5 full-text search implementation
• Used?: Yes - Imported by search-server.ts
• Notes: Provides searchObservations, searchSessions, searchUserPrompts, findByConcept, findByFile, findByType

src/services/sqlite/SessionStore.ts

• Purpose: CRUD operations for sessions, observations, summaries, user prompts
• Used?: Yes - Imported by all hooks, worker-service.ts, search-server.ts, bin utilities
• Notes: Core database store, heavily used throughout the system

src/services/sqlite/types.ts

• Purpose: TypeScript type definitions for database records
• Used?: Yes - Imported by search-server.ts
• Notes: Defines ObservationSearchResult, SessionSummarySearchResult, UserPromptSearchResult

---

Directory: src/services/sync (1 file)

src/services/sync/ChromaSync.ts

• Purpose: Vector database synchronization service for semantic search
• Used?: Yes - Imported by worker-service.ts
• Notes: 737 lines. Manages Chroma vector embeddings for observations, summaries, and prompts. Critical for hybrid search.

---

Directory: src/services (1 file)

src/services/worker-service.ts

• Purpose: Express HTTP server managed by PM2, handles SDK agent sessions
• Used?: Yes - Built to plugin/worker-service.cjs, started by PM2
• Notes: 1,173 lines. Core worker service with 14 HTTP/SSE endpoints. Serves viewer UI, manages SDK sessions, broadcasts SSE updates.

---

Directory: src/shared (2 files, 3 deleted)

src/shared/config.ts 🗑️ DELETED

• Purpose: Package configuration (name, version, description)
• Used?: No - Not imported anywhere
• Notes: DELETED. Read from package.json but no code used these exports. The actual version reading happens inline in worker-service.ts.

src/shared/paths.ts

• Purpose: Path utilities and directory management
• Used?: Yes - Imported by search-server.ts
• Notes: Provides VECTOR_DB_DIR and other path constants. Actively used.

src/shared/storage.ts 🗑️ DELETED

• Purpose: Unified storage provider interface (SQLite abstraction layer)
• Used?: No - Not imported anywhere
• Notes: DELETED. Defined IStorageProvider interface and SQLiteStorageProvider but nothing used this abstraction. Direct SessionStore usage is preferred.

src/shared/types.ts 🗑️ DELETED

• Purpose: Core type definitions (Settings interface)
• Used?: No - Not imported anywhere
• Notes: DELETED. Defined Settings interface but no code imported it. Settings are read/written as raw JSON objects.

src/shared/worker-utils.ts

• Purpose: Worker health checks and PM2 management
• Used?: Yes - Imported by context-hook.ts, new-hook.ts, save-hook.ts, summary-hook.ts, cleanup-hook.ts, user-message-hook.ts
• Notes: Core utility, actively used by all hooks

---

Directory: src/utils (1 file, 2 deleted)

src/utils/logger.ts

• Purpose: Structured logging with correlation IDs and data flow tracking
• Used?: Yes - Imported by parser.ts, save-hook.ts, summary-hook.ts, worker-service.ts
• Notes: Core logger, actively used

src/utils/platform.ts 🗑️ DELETED

• Purpose: Platform-specific utilities for Windows/Unix compatibility
• Used?: No - Not imported anywhere
• Notes: DELETED. Provided installUv(), getShellConfigPaths(), getAliasDefinition() but nothing used these. Likely leftover from earlier installer/setup code.

src/utils/usage-logger.ts 🗑️ DELETED

• Purpose: Usage data logger for API cost tracking (JSONL files)
• Used?: No - Not imported anywhere
• Notes: DELETED. Defined UsageLogger class but it was never instantiated. Usage tracking may be handled differently now.

---

Directory: src/ui (24 files + assets)

src/ui/claude-mem-logo-for-dark-mode.webp

• Purpose: Logo asset for dark mode
• Used?: Yes - Referenced in Header.tsx, bundled into viewer.html
• Notes: Web UI asset

src/ui/claude-mem-logomark.webp

• Purpose: Logomark asset
• Used?: Yes - Referenced in Header.tsx, bundled into viewer.html
• Notes: Web UI asset

src/ui/viewer-template.html

• Purpose: HTML template for viewer UI
• Used?: Yes - Build process uses this to generate plugin/ui/viewer.html
• Notes: Build artifact template

src/ui/viewer/App.tsx

• Purpose: Root React component for viewer UI
• Used?: Yes - Entry point for viewer, imported by index.tsx
• Notes: Main app component

src/ui/viewer/index.tsx

• Purpose: React app entry point
• Used?: Yes - Built by esbuild into viewer-bundle.js
• Notes: Mounts React app

src/ui/viewer/types.ts

• Purpose: TypeScript types for viewer UI
• Used?: Yes - Imported by multiple viewer components
• Notes: Type definitions for Observation, Summary, UserPrompt, etc.

src/ui/viewer/assets/fonts/ (2 files)

• monaspace-radon-var.woff and monaspace-radon-var.woff2
• Purpose: Monaspace Radon font files for viewer UI
• Used?: Yes - Embedded in viewer.html via esbuild
• Notes: Font assets

src/ui/viewer/components/ (8 files)

All actively used by App.tsx:

• ErrorBoundary.tsx - Error boundary wrapper
• Feed.tsx - Infinite scroll feed component
• Header.tsx - Top navigation with project selector, stats, settings
• ObservationCard.tsx - Observation display card
• PromptCard.tsx - User prompt display card
• Sidebar.tsx - Project filtering sidebar
• SummaryCard.tsx - Session summary display card
• ThemeToggle.tsx - Light/dark mode toggle

src/ui/viewer/constants/ (4 files)

All actively used by viewer components:

• api.ts - API endpoint URLs
• settings.ts - Default settings constants
• timing.ts - Timing constants (reconnect delays, polling intervals)
• ui.ts - UI constants (page sizes, etc.)

src/ui/viewer/hooks/ (5 files)

All actively used by viewer components:

• usePagination.ts - Infinite scroll pagination hook
• useSSE.ts - Server-sent events hook for real-time updates
• useSettings.ts - Settings management hook
• useStats.ts - Worker stats fetching hook
• useTheme.ts - Theme (light/dark) management hook

src/ui/viewer/utils/ (2 files)

All actively used by viewer components:

• data.ts - Data merging and deduplication utilities
• formatters.ts - Date/time formatting utilities

---

Dead Code Summary

🗑️ Deleted Files (7 files - all removed)

1. src/hooks/index.ts ✅ DELETED - Outdated export barrel, referenced non-existent files
2. src/shared/config.ts ✅ DELETED - Package config not used anywhere, version read inline instead
3. src/shared/storage.ts ✅ DELETED - Abstraction layer not used, direct SessionStore usage preferred
4. src/shared/types.ts ✅ DELETED - Settings interface not imported anywhere
5. src/sdk/index.ts ✅ DELETED - Export barrel, but imports happened directly from parser/prompts instead
6. src/utils/platform.ts ✅ DELETED - Platform utilities not used, legacy installer code
7. src/utils/usage-logger.ts ✅ DELETED - UsageLogger class never instantiated

Utility/Maintenance Scripts (not dead, just not runtime code) (2 files)

8. src/bin/cleanup-duplicates.ts - Maintenance CLI tool
9. src/bin/import-xml-observations.ts - Data migration CLI tool

Test Files (not dead, just not runtime code) (1 file)

10. src/sdk/parser.test.ts - Regression test suite

---

File Count Summary

• Total files (before cleanup): 58
• Total files (after cleanup): 51 ✅
• Deleted dead code: 7 files 🗑️
• Actively used at runtime: 43 files
• Utility/maintenance scripts: 2 files
• Test files: 1 file
• Build templates: 1 file (viewer-template.html)
• Assets: 4 files (2 logos, 2 fonts)

---

Cleanup Actions Completed ✅

1. ✅ Removed all dead code (7 files deleted):

   • ✅ Deleted src/hooks/index.ts
   • ✅ Deleted src/shared/config.ts
   • ✅ Deleted src/shared/storage.ts
   • ✅ Deleted src/shared/types.ts
   • ✅ Deleted src/sdk/index.ts
   • ✅ Deleted src/utils/platform.ts
   • ✅ Deleted src/utils/usage-logger.ts

2. ✅ Kept utility scripts for maintenance purposes:

   • ✅ Kept src/bin/cleanup-duplicates.ts
   • ✅ Kept src/bin/import-xml-observations.ts

3. ✅ Kept test files for regression testing:

   • ✅ Kept src/sdk/parser.test.ts

Next Steps

1. Build and test to ensure no broken imports:

   npm run build
   

2. Run TypeScript diagnostics to catch any missing references:

   npx tsc --noEmit
   

3. Commit the cleanup:

   git add -A
   git commit -m "Remove dead code files"