cccmemory 1.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 xiaolai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,349 @@
+# CCCMemory MCP
+
+An MCP server that gives Claude long-term memory by indexing conversation history with semantic search, decision tracking, and cross-project search.
+
+---
+
+## ⚠️ Breaking Changes in v1.8.0
+
+**This package has been renamed from `claude-conversation-memory-mcp` to `cccmemory`.**
+
+If you were using the old package, follow these migration steps:
+
+### 1. Uninstall the old package
+
+```bash
+npm uninstall -g claude-conversation-memory-mcp
+```
+
+### 2. Install the new package
+
+```bash
+npm install -g cccmemory
+```
+
+### 3. Update your MCP configuration
+
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "cccmemory": {
+      "command": "npx",
+      "args": ["-y", "cccmemory"]
+    }
+  }
+}
+```
+
+**Claude Code** (`~/.claude.json`):
+```json
+{
+  "mcpServers": {
+    "cccmemory": {
+      "command": "npx",
+      "args": ["-y", "cccmemory"]
+    }
+  }
+}
+```
+
+**Codex** (`~/.codex/config.toml`):
+```toml
+[mcp_servers.cccmemory]
+command = "npx"
+args = ["-y", "cccmemory"]
+```
+
+### 4. Database migration (automatic)
+
+Your conversation history is preserved. The database files are automatically migrated:
+- `.claude-conversations-memory.db` → `.cccmemory.db`
+- `.codex-conversations-memory.db` → `.cccmemory.db`
+
+No manual action required - the migration happens on first run.
+
+---
+
+## Features
+
+- **Search conversations** - Natural language search across your chat history
+- **Track decisions** - Remember why you made technical choices
+- **Prevent mistakes** - Learn from past errors
+- **Git integration** - Link conversations to commits
+- **Cross-project search** - Search across all your projects globally
+- **Project migration** - Keep history when renaming/moving projects
+- **Semantic search** - Uses Transformers.js embeddings (bundled, works offline)
+
+## Installation
+
+### Node.js version
+
+CCCMemory supports **Node.js 20 or 22 LTS**. Using other versions can break native
+modules (like `better-sqlite3`). If you switch Node versions, reinstall the
+package (or run `npm rebuild better-sqlite3` in a local clone).
+
+```bash
+npm install -g cccmemory
+```
+
+Verify installation:
+
+```bash
+cccmemory --version
+```
+
+## Configuration
+
+### For Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "cccmemory": {
+      "command": "npx",
+      "args": ["-y", "cccmemory"]
+    }
+  }
+}
+```
+
+Then restart Claude Desktop.
+
+### For Claude Code
+
+Edit `~/.claude.json` (note: this file is in your home directory, not inside `~/.claude/`):
+
+```json
+{
+  "mcpServers": {
+    "cccmemory": {
+      "command": "npx",
+      "args": ["-y", "cccmemory"]
+    }
+  }
+}
+```
+
+Or if installed globally:
+
+```json
+{
+  "mcpServers": {
+    "cccmemory": {
+      "command": "cccmemory"
+    }
+  }
+}
+```
+
+### For Codex CLI
+
+Codex stores MCP settings in `~/.codex/config.toml` (shared by the CLI and the IDE extension).
+
+**Recommended (CLI):**
+```bash
+codex mcp add cccmemory -- npx -y cccmemory
+```
+
+**Manual config (`~/.codex/config.toml`):**
+```toml
+[mcp_servers.cccmemory]
+command = "npx"
+args = ["-y", "cccmemory"]
+```
+
+If you installed globally, you can use:
+```toml
+[mcp_servers.cccmemory]
+command = "cccmemory"
+```
+
+Open Codex and run `/mcp` in the TUI to verify the server is active.
+
+### Storage Paths
+
+By default, CCCMemory stores per-project databases in:
+
+- `~/.claude/projects/<project>/.cccmemory.db`
+- Global index: `~/.claude/.cccmemory-global.db`
+
+If your home directory is not writable (common in sandboxed Codex/Claude setups where
+`~/.claude` and `~/.codex` are locked), the server will exit with a clear error.
+Set explicit paths to a writable location:
+
+```bash
+export CCCMEMORY_DB_PATH="/path/to/cccmemory.db"
+export CCCMEMORY_GLOBAL_INDEX_PATH="/path/to/cccmemory-global.db"
+```
+
+For MCP configs, add these env vars in your server definition. CCCMemory will not
+silently create new databases outside `~/.claude`; it only uses an existing
+project-local DB if one already exists and logs a warning.
+
+### Embedding Configuration (Optional)
+
+The MCP uses **Transformers.js** by default for semantic search (bundled, works offline, no setup required).
+
+**Model download & cache behavior (Transformers.js):**  
+On first use, `@xenova/transformers` downloads the model weights and caches them in its own default cache directory. CCCMemory does not manage or relocate that cache. Subsequent runs reuse the cached model and work fully offline.
+
+To customize, create `~/.claude-memory-config.json`:
+
+```json
+{
+  "embedding": {
+    "provider": "transformers",
+    "model": "Xenova/all-MiniLM-L6-v2",
+    "dimensions": 384
+  }
+}
+```
+
+**Alternative providers:**
+
+<details>
+<summary>Ollama (faster, requires Ollama running)</summary>
+
+```bash
+# Install Ollama
+curl -fsSL https://ollama.com/install.sh | sh
+ollama pull mxbai-embed-large
+ollama serve
+```
+
+Config:
+```json
+{
+  "embedding": {
+    "provider": "ollama",
+    "model": "mxbai-embed-large",
+    "dimensions": 1024
+  }
+}
+```
+</details>
+
+<details>
+<summary>OpenAI (requires API key)</summary>
+
+```json
+{
+  "embedding": {
+    "provider": "openai",
+    "model": "text-embedding-3-small",
+    "dimensions": 1536
+  }
+}
+```
+
+Set `OPENAI_API_KEY` environment variable.
+</details>
+
+## MCP Tools
+
+### Indexing
+| Tool | Description |
+|------|-------------|
+| `index_conversations` | Index current project's conversations |
+| `index_all_projects` | Index all Claude Code + Codex projects |
+
+### Search
+| Tool | Description |
+|------|-------------|
+| `search_conversations` | Search messages in current project |
+| `search_all_conversations` | Search across all indexed projects |
+| `get_decisions` | Find architectural decisions |
+| `get_all_decisions` | Decisions across all projects |
+| `search_mistakes` | Find past errors and fixes |
+| `search_all_mistakes` | Mistakes across all projects |
+| `find_similar_sessions` | Find related conversations |
+
+### Context
+| Tool | Description |
+|------|-------------|
+| `check_before_modify` | Get context before editing a file |
+| `get_file_evolution` | See file history with commits |
+| `search_by_file` | Find all context related to a file |
+| `list_recent_sessions` | List recent sessions with summaries |
+| `recall_and_apply` | Recall past work for current task |
+| `get_requirements` | Look up component requirements |
+| `get_tool_history` | Query tool usage history |
+| `link_commits_to_conversations` | Connect git commits to sessions |
+
+### Project Management
+| Tool | Description |
+|------|-------------|
+| `discover_old_conversations` | Find folders from renamed projects |
+| `migrate_project` | Migrate/merge conversation history |
+| `forget_by_topic` | Delete conversations by keyword |
+| `generate_documentation` | Generate docs from conversations |
+
+## CLI Usage
+
+The package includes a standalone CLI:
+
+```bash
+# Interactive mode
+cccmemory
+
+# Single commands
+cccmemory status
+cccmemory index
+cccmemory "search authentication"
+cccmemory help
+```
+
+## Supported Platforms
+
+| Platform | Status | Conversation Location |
+|----------|--------|----------------------|
+| Claude Code | ✅ Supported | `~/.claude/projects/` |
+| Claude Desktop | ✅ Supported | (indexes Claude Code history) |
+| Codex | ✅ Supported | `~/.codex/sessions/` |
+
+**Why only Claude Code and Codex CLI today?**
+CCCMemory indexes local session history from stable, parseable on-disk formats. Claude Code and Codex CLI both store full conversation logs locally with consistent schemas. Other tools either do not expose full local history, only support partial/manual saves, or do not provide a stable file format to parse reliably. Without deterministic local storage, there is nothing safe to index or resume.
+
+## Architecture
+
+```
+Per-Project Databases (isolation)
+├── ~/.claude/projects/{project}/.cccmemory.db (Claude Code default)
+├── ~/.codex/.cccmemory.db (Codex default)
+└── {project}/.cccmemory/.cccmemory.db (fallback in restricted sandboxes)
+
+Global Registry (cross-project search)
+├── ~/.claude/.cccmemory-global.db (default)
+└── {project}/.cccmemory/global-index.db (fallback in restricted sandboxes)
+```
+
+## Troubleshooting
+
+### Claude Desktop shows JSON parse errors
+
+Upgrade to v1.7.3+:
+```bash
+npm update -g cccmemory
+```
+
+### MCP not loading in Claude Code
+
+1. Check config location is `~/.claude.json` (not `~/.claude/config.json`)
+2. Verify JSON syntax is valid
+3. Restart Claude Code
+
+### Embeddings not working
+
+Check provider status:
+```bash
+cccmemory status
+```
+
+Default Transformers.js should work out of the box. If you opt into Ollama, ensure it's running (`ollama serve`).
+
+## License
+
+MIT

package/dist/ConversationMemory.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Main Orchestrator - Coordinates all components for conversation memory indexing and retrieval.
+ *
+ * ConversationMemory is the primary interface for the cccmemory-mcp system.
+ * It orchestrates parsing, storage, extraction, and search of Claude Code conversation history.
+ *
+ * @example
+ * ```typescript
+ * const memory = new ConversationMemory();
+ * await memory.indexConversations({
+ *   projectPath: '/path/to/project',
+ *   enableGitIntegration: true
+ * });
+ * ```
+ */
+import { ConversationStorage } from "./storage/ConversationStorage.js";
+import { SemanticSearch } from "./search/SemanticSearch.js";
+/**
+ * Configuration options for indexing conversations.
+ */
+export interface IndexOptions {
+    /** Absolute path to the project directory to index */
+    projectPath: string;
+    /** Optional: Index only a specific session ID instead of all sessions */
+    sessionId?: string;
+    /**
+     * Whether to include thinking blocks in the index.
+     * Thinking blocks can be large and are excluded by default.
+     * @default false
+     */
+    includeThinking?: boolean;
+    /**
+     * Enable git integration to link commits to conversations.
+     * Requires the project to be a git repository.
+     * @default true
+     */
+    enableGitIntegration?: boolean;
+    /**
+     * Exclude MCP tool conversations from indexing.
+     * - `false`: Index all conversations (default)
+     * - `'self-only'`: Exclude only cccmemory MCP conversations (prevents self-referential loops)
+     * - `'all-mcp'` or `true`: Exclude all MCP tool conversations
+     * @default false
+     */
+    excludeMcpConversations?: boolean | 'self-only' | 'all-mcp';
+    /**
+     * List of specific MCP server names to exclude.
+     * More granular than `excludeMcpConversations`.
+     * @example ['cccmemory', 'code-graph-rag']
+     */
+    excludeMcpServers?: string[];
+    /**
+     * Optional timestamp to skip unchanged conversation files.
+     * Files with mtime older than this will be skipped.
+     */
+    lastIndexedMs?: number;
+}
+/**
+ * Main orchestrator for conversation memory operations.
+ *
+ * Coordinates parsing, storage, extraction, and search across:
+ * - Conversation parsing from JSONL files
+ * - Decision, mistake, and requirement extraction
+ * - Git commit integration
+ * - Semantic search with embeddings
+ */
+export declare class ConversationMemory {
+    private sqliteManager;
+    private storage;
+    private parser;
+    private decisionExtractor;
+    private mistakeExtractor;
+    private requirementsExtractor;
+    private semanticSearch;
+    constructor();
+    /**
+     * Index conversations for a project.
+     *
+     * This is the main entry point for processing conversation history.
+     * It performs the following operations:
+     * 1. Parse conversation JSONL files from the project
+     * 2. Store conversations, messages, and tool interactions
+     * 3. Extract decisions, mistakes, and requirements
+     * 4. Link git commits (if enabled)
+     * 5. Generate semantic embeddings for search
+     *
+     * @param options - Configuration options for indexing
+     * @returns Result object containing:
+     * - `embeddings_generated`: Whether embeddings were successfully generated
+     * - `embedding_error`: Error message if embedding generation failed
+     * - `indexed_folders`: List of folders that were indexed
+     * - `database_path`: Path to the SQLite database
+     *
+     * @throws {Error} If project path doesn't exist or conversation files can't be parsed
+     *
+     * @example
+     * ```typescript
+     * const result = await memory.indexConversations({
+     *   projectPath: '/Users/me/my-project',
+     *   enableGitIntegration: true,
+     *   excludeMcpConversations: 'self-only'
+     * });
+     *
+     * if (result.embeddings_generated) {
+     *   console.error('Indexed folders:', result.indexed_folders);
+     * } else {
+     *   console.warn('Embeddings failed:', result.embedding_error);
+     * }
+     * ```
+     */
+    indexConversations(options: IndexOptions): Promise<{
+        embeddings_generated: boolean;
+        embedding_error?: string;
+        indexed_folders?: string[];
+        database_path?: string;
+    }>;
+    /**
+     * Search conversations using natural language query.
+     *
+     * Uses semantic search with embeddings if available, otherwise falls back to full-text search.
+     *
+     * @param query - Natural language search query
+     * @param limit - Maximum number of results to return (default: 10)
+     * @returns Array of search results with messages, conversations, and similarity scores
+     *
+     * @example
+     * ```typescript
+     * const results = await memory.search('authentication bug fix', 5);
+     * results.forEach(r => {
+     *   console.error(`${r.similarity}: ${r.snippet}`);
+     * });
+     * ```
+     */
+    search(query: string, limit?: number): Promise<import("./search/SemanticSearch.js").SearchResult[]>;
+    /**
+     * Search for decisions using natural language query.
+     *
+     * Searches through extracted decisions to find relevant architectural choices and technical decisions.
+     *
+     * @param query - Natural language search query
+     * @param limit - Maximum number of results to return (default: 10)
+     * @returns Array of decision search results with similarity scores
+     *
+     * @example
+     * ```typescript
+     * const decisions = await memory.searchDecisions('database choice', 3);
+     * decisions.forEach(d => {
+     *   console.error(`Decision: ${d.decision.decision_text}`);
+     *   console.error(`Rationale: ${d.decision.rationale}`);
+     * });
+     * ```
+     */
+    searchDecisions(query: string, limit?: number): Promise<import("./search/SemanticSearch.js").DecisionSearchResult[]>;
+    /**
+     * Get the timeline of changes for a specific file.
+     *
+     * Returns all edits, commits, and related conversations for a file across its history.
+     *
+     * @param filePath - Path to the file (relative to project root)
+     * @returns Timeline of file changes with conversations and commits
+     *
+     * @example
+     * ```typescript
+     * const timeline = memory.getFileTimeline('src/index.ts');
+     * console.error(`${timeline.length} changes to this file`);
+     * ```
+     */
+    getFileTimeline(filePath: string): {
+        file_path: string;
+        edits: import("./parsers/ConversationParser.js").FileEdit[];
+        commits: import("./parsers/GitIntegrator.js").GitCommit[];
+        decisions: import("./parsers/DecisionExtractor.js").Decision[];
+    };
+    /**
+     * Get statistics about the indexed conversation data.
+     *
+     * @returns Object containing counts for conversations, messages, decisions, mistakes, and commits
+     *
+     * @example
+     * ```typescript
+     * const stats = memory.getStats();
+     * console.error(`Indexed ${stats.conversations.count} conversations`);
+     * console.error(`Extracted ${stats.decisions.count} decisions`);
+     * ```
+     */
+    getStats(): {
+        conversations: {
+            count: number;
+        };
+        messages: {
+            count: number;
+        };
+        decisions: {
+            count: number;
+        };
+        mistakes: {
+            count: number;
+        };
+        git_commits: {
+            count: number;
+        };
+    };
+    /**
+     * Get the underlying storage instance for direct database access.
+     *
+     * Use with caution - prefer using the high-level methods when possible.
+     *
+     * @returns ConversationStorage instance
+     * @internal
+     */
+    getStorage(): ConversationStorage;
+    /**
+     * Get the semantic search instance for advanced search operations.
+     *
+     * @returns SemanticSearch instance
+     * @internal
+     */
+    getSemanticSearch(): SemanticSearch;
+    /**
+     * Filter MCP conversations from parse results.
+     *
+     * Implements the exclusion logic for MCP tool conversations to prevent
+     * self-referential loops and reduce noise in the index.
+     *
+     * Strategy: Filter at MESSAGE level, not conversation level.
+     * - Keep all conversations
+     * - Exclude only messages that invoke specified MCP tools and their responses
+     */
+    private filterMcpConversations;
+}
+//# sourceMappingURL=ConversationMemory.d.ts.map

package/dist/ConversationMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConversationMemory.d.ts","sourceRoot":"","sources":["../src/ConversationMemory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAGH,OAAO,EAAE,mBAAmB,EAAE,MAAM,kCAAkC,CAAC;AAMvE,OAAO,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAG5D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IAEpB,yEAAyE;IACzE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAE/B;;;;;;OAMG;IACH,uBAAuB,CAAC,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAAC;IAE5D;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;GAQG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,qBAAqB,CAAwB;IACrD,OAAO,CAAC,cAAc,CAAiB;;IAiBvC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,kBAAkB,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC;QACvD,oBAAoB,EAAE,OAAO,CAAC;QAC9B,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;QAC3B,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IAiIF;;;;;;;;;;;;;;;;OAgBG;IACG,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW;IAI9C;;;;;;;;;;;;;;;;;OAiBG;IACG,eAAe,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,GAAE,MAAW;IAIvD;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,QAAQ,EAAE,MAAM;;;;;;IAIhC;;;;;;;;;;;OAWG;IACH,QAAQ;;;;;;;;;;;;;;;;;IAIR;;;;;;;OAOG;IACH,UAAU;IAIV;;;;;OAKG;IACH,iBAAiB;IAIjB;;;;;;;;;OASG;IACH,OAAO,CAAC,sBAAsB;CA6E/B"}