### Install MyChatArchive from Source

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Use these commands to clone the repository and install the package from source. This is the recommended installation method for now.

```bash
git clone https://github.com/1ch1n/mychatarchive.git
cd mychatarchive
pip install .
```

--------------------------------

### Install and Initialize MyChatArchive

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Clone the repository, install the package, and initialize the tool to set up the drop folder and auto-discovery.

```bash
git clone https://github.com/1ch1n/mychatarchive.git
cd mychatarchive
pip install .

# 1. Set up (creates drop folder, configures auto-discovery)
mychatarchive init
```

--------------------------------

### Start MCP Server

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Start the MCP server to allow connected AI tools to query your chat archive. Configuration for clients is provided after starting.

```bash
# 5. Start the MCP server
mychatarchive serve
```

--------------------------------

### MyChatArchive Configuration Example

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Example JSON configuration for the MyChatArchive plugin, specifying database path, recall mode, and prefetch limit.

```json
{
  "db_path": "~/.mychatarchive/archive.db",
  "recall_mode": "hybrid",
  "prefetch_limit": 5
}
```

--------------------------------

### Install Development Dependencies

Source: https://github.com/1ch1n/mychatarchive/blob/main/CONTRIBUTING.md

Install the project in development mode with all necessary development dependencies. This allows you to make changes and test them locally.

```bash
pip install -e ".[dev]"
```

--------------------------------

### Clone Repository

Source: https://github.com/1ch1n/mychatarchive/blob/main/CONTRIBUTING.md

Clone the MyChatArchive repository to your local machine. This is the first step to start contributing.

```bash
git clone https://github.com/<your-username>/mychatarchive.git
cd mychatarchive
```

--------------------------------

### Install MyChatArchive Package

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/hermes-plugin-design.md

Install the mychatarchive package into the Hermes Python environment using pip. Use the editable install option for local development.

```bash
pip install git+https://github.com/1ch1n/mychatarchive
# or for local development:
pip install -e /path/to/mychatarchive
```

--------------------------------

### Run Tests

Source: https://github.com/1ch1n/mychatarchive/blob/main/CONTRIBUTING.md

Execute the test suite to ensure that your changes do not break existing functionality. This should be run after installing dependencies and before committing changes.

```bash
pytest
```

--------------------------------

### Install MyChatArchive

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Install the MyChatArchive package into your Hermes Agent Python environment using pip.

```bash
pip install git+https://github.com/1ch1n/mychatarchive
```

--------------------------------

### Configure Hermes MyChatArchive Provider

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/PR-description.md

Set up the MyChatArchive memory provider within Hermes. This involves running the setup command and selecting the 'mychatarchive' option.

```bash
hermes memory setup
```

--------------------------------

### Activate MyChatArchive Provider

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Activate the MyChatArchive memory provider via the Hermes setup wizard or by manually configuring the `config.yaml` file.

```bash
hermes memory setup
```

```yaml
memory:
  provider: mychatarchive
```

--------------------------------

### MyChatArchive Full Pipeline Workflow

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Execute the full chat archive processing pipeline. This includes syncing data, generating LLM thread summaries, creating vector embeddings, and starting the MCP server.

```bash
mychatarchive sync           # import from all sources
mychatarchive summarize      # LLM thread summaries (optional, needs API key)
mychatarchive embed          # generate vector embeddings locally
mychatarchive serve          # start MCP server
```

--------------------------------

### Configure Claude Desktop Client

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Configure MyChatArchive to connect with the Claude Desktop client. The output should be added to the specified configuration file.

```bash
mychatarchive mcp-config --client claude-desktop
```

--------------------------------

### Serve MyChatArchive via SSE

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Run MyChatArchive as a server using Server-Sent Events (SSE) transport on a specified port. This enables remote access from other devices.

```bash
mychatarchive serve --transport sse --port 8420
```

--------------------------------

### Configure Cursor Client

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Configure MyChatArchive to connect with the Cursor client. The output should be added to the Cursor MCP settings.

```bash
mychatarchive mcp-config --client cursor
```

--------------------------------

### Configure MCP Client

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Generate configuration output for clients like Claude Desktop or Cursor to connect to the MyChatArchive MCP server.

```bash
mychatarchive mcp-config
```

--------------------------------

### Populate MyChatArchive

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/PR-description.md

Sync and embed data into your MyChatArchive database. This step is necessary to prepare the archive for Hermes.

```bash
mychatarchive sync && mychatarchive embed
```

--------------------------------

### MyChatArchive Workflow Diagram

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

This diagram illustrates the MyChatArchive workflow, from data ingestion (auto-discovery, drop folder, named sources) through processing (parsing, deduplication, embeddings) to storage (SQLite with FTS5 and sqlite-vec) and serving (MCP server).

```text
Auto-discovery (Claude Code, Cursor)  --+
Drop folder (ChatGPT, Claude, Grok)   --+--> Parse + SHA1 dedup --> SQLite (FTS5)
Named sources (NAS, custom paths)     --+              |
                                                       v
                                           sentence-transformers (local)
                                                       |
                                                       v
                                           sqlite-vec (cosine KNN)
                                                       |
                                                       v
                                           MCP server (stdio / SSE)
                                                       |
                                          Claude Desktop / Cursor /
                                          Claude Code / Claude Mobile
```

--------------------------------

### Create and Manage Thread Groups

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Organize threads into named groups for scoped search. Commands include creating groups with descriptions, showing group contents, adding threads by ID, and scoping searches to a group.

```bash
# Create groups
mychatarchive groups create jarvis --description "Daily personal chats"
mychatarchive groups create coding --description "Dev work and technical threads"

# Browse threads to find IDs
mychatarchive groups show jarvis

# Add threads
mychatarchive groups add jarvis <thread_id> <thread_id>

# Scope search to a group
mychatarchive search "what did I decide" --group jarvis

# In MCP tools: search_brain(query="...", group="jarvis")
```

--------------------------------

### Project Structure Overview

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

This is a visual representation of the MyChatArchive project's directory and file structure.

```text
mychatarchive/
+-- src/mychatarchive/
|   +-- cli.py              # Unified CLI
|   +-- config.py           # Paths, constants, config management
|   +-- db.py               # Data access layer (delegates to backends)
|   +-- embeddings.py       # Local embedding pipeline
|   +-- chunker.py          # Message chunking for embeddings
|   +-- ingest.py           # Import engine with SHA1 dedup
|   +-- summarizer.py       # LLM thread summarization pipeline
|   +-- parsers/
|   |   +-- chatgpt.py      # ChatGPT conversations.json
|   |   +-- anthropic.py    # Claude export format
|   |   +-- grok.py         # Grok/X.AI export format
|   |   +-- claude_code.py  # Claude Code JSONL sessions
|   |   +-- cursor.py       # Cursor IDE SQLite databases
|   +-- backends/           # Pluggable storage, embeddings, transport
|   +-- mcp/
|       +-- server.py       # MCP server (6 tools)
+-- tests/
+-- pyproject.toml
+-- ROADMAP.md
```

--------------------------------

### Sync All Chat Archives

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Import all chat data by syncing from the drop folder and auto-discovered sessions. This command is used after initialization.

```bash
# 2. Import everything in one command
#    Auto-discovers Claude Code + Cursor, scans your drop folder
mychatarchive sync
```

--------------------------------

### MyChatArchive Sync Command

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Initiate the data synchronization process. This command imports data from all configured sources. The `--embed` flag can be added to generate embeddings concurrently.

```bash
mychatarchive sync           # import from all sources
mychatarchive sync --embed   # sync + generate embeddings in one shot
```

--------------------------------

### Copy Plugin to Hermes

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Copy the MyChatArchive plugin directory into your Hermes Agent plugins folder. Symlinking is also an option.

```bash
cp -r plugins/memory/mychatarchive/ /path/to/hermes-agent/plugins/memory/mychatarchive/
```

```bash
ln -s $(pwd)/plugins/memory/mychatarchive /path/to/hermes-agent/plugins/memory/mychatarchive
```

--------------------------------

### MyChatArchive Plugin File Structure

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/hermes-plugin-design.md

Standard file layout for a Hermes plugin, including initialization, configuration, and optional CLI components.

```text
plugins/memory/mychatarchive/
  __init__.py     # MyChatArchiveMemoryProvider + register()
  plugin.yaml     # name, description, hooks
  README.md       # setup instructions
```

```text
  cli.py          # hermes mychatarchive status|stats
```

--------------------------------

### Create a New Branch

Source: https://github.com/1ch1n/mychatarchive/blob/main/CONTRIBUTING.md

Create a new branch from the main branch to isolate your changes. Use a descriptive name for your branch.

```bash
git checkout -b your-branch-name
```

--------------------------------

### Generate Thread Summaries

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Optionally generate summaries for threads to enhance context retrieval. Requires an API key to be set (OPENROUTER_API_KEY or ANTHROPIC_API_KEY).

```bash
# 3. (Optional) Generate thread summaries for richer context retrieval
#    Needs an API key: set OPENROUTER_API_KEY or ANTHROPIC_API_KEY
mychatarchive summarize
```

--------------------------------

### Default Data Location Structure

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

This outlines the default directory structure for MyChatArchive data, including the SQLite database, configuration file, and import folder.

```text
~/.mychatarchive/
+-- archive.db          # SQLite database (messages + vectors + thoughts)
+-- config.json         # Backend + source configuration
+-- imports/            # Drop folder for export files
```

--------------------------------

### Add Memory to Platform Toolset

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/PR-description.md

If using a gateway, ensure the 'memory' tool is included in your platform's toolset configuration to enable memory functionalities.

```yaml
platform_toolsets:
  telegram:
  - hermes-telegram
  - memory
```

--------------------------------

### MyChatArchive Pipeline Shortcut

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Use this shortcut command to perform both synchronization and embedding in a single step. This is useful for quickly updating the archive with new messages and their embeddings.

```bash
mychatarchive sync --embed   # sync + embed in one shot
mychatarchive serve
```

--------------------------------

### Summarize Chat Threads

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Use the 'summarize' command to generate LLM thread summaries. You can specify the model, pass an API key inline, or set a limit for testing.

```bash
mychatarchive summarize                              # default model via OpenRouter
mychatarchive summarize --model gpt-4o-mini          # specify model
mychatarchive summarize --key sk-...                 # pass API key inline
mychatarchive summarize --limit 50                   # process first 50 threads (for testing)
```

--------------------------------

### MyChatArchive Config Schema

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/hermes-plugin-design.md

Defines the configuration schema for the MyChatArchive plugin, including database path, recall mode, and prefetch limit. No secrets or API keys are required.

```python
get_config_schema() -> [
    {"key": "db_path", "description": "Path to MCA database",
     "default": "~/.mychatarchive/archive.db"},
    {"key": "recall_mode", "description": "Memory integration mode",
     "default": "hybrid", "choices": ["hybrid", "context", "tools"]},
    {"key": "prefetch_limit", "description": "Max chunks injected per turn",
     "default": "5"},
]
```

--------------------------------

### Lint and Format Code

Source: https://github.com/1ch1n/mychatarchive/blob/main/CONTRIBUTING.md

Use Ruff to check for linting errors and automatically format the code according to project standards. This should be done before committing changes.

```bash
ruff check src/ tests/
ruff format src/ tests/
```

--------------------------------

### mca_recall Tool Usage

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Utilize `mca_recall` for rich contextual retrieval based on a topic, combining message chunks, thread summaries, and captured thoughts.

```tool_usage
mca_recall(topic: str, limit: int = 5, platform: str = None, group: str = None)
```

--------------------------------

### Add New Parser Structure

Source: https://github.com/1ch1n/mychatarchive/blob/main/CONTRIBUTING.md

Define the structure for a new parser by creating a Python file in the parsers directory. This includes the `parse` function that yields normalized messages.

```python
from typing import Iterator

def parse(input_path: str) -> Iterator[dict]:
    """Yield normalized messages."""
    yield {
        "thread_id": "unique-thread-id",
        "thread_title": "Conversation Title",
        "role": "user",
        "content": "Message text",
        "created_at": 1700000000.0,
    }
```

--------------------------------

### Check Archive Statistics

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Use the 'mychatarchive info' command to display statistics about your chat archive, including message counts, thread information, and platform-specific data.

```bash
mychatarchive info
```

--------------------------------

### Generate Local Embeddings

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Create local embeddings for your chat data to enable semantic search capabilities.

```bash
# 4. Generate local embeddings
mychatarchive embed
```

--------------------------------

### mca_provenance Tool Usage

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Employ `mca_provenance` to retrieve the full source context for a specific chunk or thought ID obtained from `mca_search` or `mca_recall`.

```tool_usage
mca_provenance(chunk_id: str = None, thought_id: str = None)
```

--------------------------------

### mca_remember Tool Usage

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Use `mca_remember` to capture specific thoughts or insights into your archive, optionally with tags for better organization.

```tool_usage
mca_remember(content: str, tags: str = None)
```

--------------------------------

### mca_recall Tool Design

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/hermes-plugin-design.md

Defines the mca_recall tool for retrieving rich contextual information about a topic. It combines message chunks, thread summaries, and captured thoughts, returning a structured context bundle.

```python
def mca_recall(topic: str, limit: int = 5, platform: str = None, group: str = None) -> dict:
    """Rich contextual retrieval for a topic."""
    # ... implementation details ...
    pass
```

--------------------------------

### Export Chat Archive

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Export chat history in various formats including JSON, CSV, and SQLite. Supports platform filtering and including thoughts.

```bash
mychatarchive export archive.json           # full structured export
```

```bash
mychatarchive export archive.csv            # spreadsheet-friendly
```

```bash
mychatarchive export archive.db             # full SQLite copy with embeddings
```

```bash
mychatarchive export chatgpt.json --platform chatgpt
```

```bash
mychatarchive export everything.json --include-thoughts
```

--------------------------------

### mca_recall

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Retrieves rich contextual information including message chunks, thread summaries, and captured thoughts for a given topic.

```APIDOC
## mca_recall

### Description
Rich contextual retrieval combining message chunks, thread summaries, and captured thoughts for a given topic.

### Method
Not applicable (Tool function)

### Endpoint
Not applicable (Tool function)

### Parameters
#### Query Parameters
- **topic** (string) - Required - Topic to recall context about.
- **limit** (int) - Optional - Max items per category (default: 5).
- **platform** (string) - Optional - Filter to a platform.
- **group** (string) - Optional - Filter to a named thread group.
```

--------------------------------

### mca_provenance

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Looks up the full source context for a chunk or thought ID returned by mca_search or mca_recall.

```APIDOC
## mca_provenance

### Description
Look up the full source context for a chunk or thought ID returned by mca_search or mca_recall. Exactly one of `chunk_id` or `thought_id` is required.

### Method
Not applicable (Tool function)

### Endpoint
Not applicable (Tool function)

### Parameters
#### Query Parameters
- **chunk_id** (string) - Optional - A chunk ID from search/recall results.
- **thought_id** (string) - Optional - A thought ID from search/recall results.
```

--------------------------------

### MyChatArchive Information Output

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

This output details the contents of your chat archive database, showing the total number of messages, threads, summaries, embedded chunks, thoughts, groups, and a breakdown by platform.

```text
MyChatArchive - ~/.mychatarchive/archive.db
----------------------------------------
  Messages:    47,832
  Threads:     1,204
  Summaries:   1,204
  Embedded:    51,388 chunks
  Thoughts:    12
  Groups:      3
  Platforms:
    chatgpt: 38,541
    anthropic: 8,291
    grok: 1,000
```

--------------------------------

### mca_provenance Tool Design

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/hermes-plugin-design.md

Defines the mca_provenance tool for retrieving the full source context of a given chunk or thought ID. It returns detailed information about the origin and surrounding messages.

```python
def mca_provenance(chunk_id: str = None, thought_id: str = None) -> dict:
    """Given a chunk or thought ID, retrieve the full source context."""
    # ... implementation details ...
    pass
```

--------------------------------

### mca_search Tool Design

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/hermes-plugin-design.md

Defines the mca_search tool for semantic and keyword searching across the archive. It supports various filtering options and returns a JSON array of search results.

```python
def mca_search(query: str, mode: str = "semantic", limit: int = 10, platform: str = None, group: str = None, hours_back: int = None) -> list[dict]:
    """Semantic + keyword search across the entire archive."""
    # ... implementation details ...
    pass
```

--------------------------------

### mca_search Tool Usage

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Use the `mca_search` tool to find past conversations in your archive. Supports semantic, keyword, or hybrid search modes with various filtering options.

```tool_usage
mca_search(query: str, mode: str = 'semantic', limit: int = 10, platform: str = None, group: str = None, hours_back: int = None)
```

--------------------------------

### mca_remember Tool Design

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/docs/hermes-plugin-design.md

Defines the mca_remember tool for capturing new thoughts or insights into the archive. It generates an embedding for the thought and stores it with associated metadata and tags.

```python
def mca_remember(thought: str, tags: str = None) -> dict:
    """Capture a new thought/insight into the archive."""
    # ... implementation details ...
    pass
```

--------------------------------

### mca_remember

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Captures a thought or insight into the archive for future retrieval, optionally with tags.

```APIDOC
## mca_remember

### Description
Capture a thought or insight into the archive for future retrieval.

### Method
Not applicable (Tool function)

### Endpoint
Not applicable (Tool function)

### Parameters
#### Query Parameters
- **content** (string) - Required - The thought or fact to remember.
- **tags** (string) - Optional - Comma-separated tags.
```

--------------------------------

### Search Chat History

Source: https://github.com/1ch1n/mychatarchive/blob/main/README.md

Perform semantic or keyword searches on chat history. Supports filtering by mode, platform, time (hours/since), sorting, and grouping.

```bash
mychatarchive search "database architecture decisions"
```

```bash
mychatarchive search "python error handling" --mode keyword
```

```bash
mychatarchive search "auth flow" --platform claude_code --group coding
```

```bash
mychatarchive search "what did I build" --hours 168 --sort time
```

```bash
mychatarchive search "api design" --since 2026-01-01
```

--------------------------------

### mca_search

Source: https://github.com/1ch1n/mychatarchive/blob/main/integrations/hermes/README.md

Searches the archive for past conversations based on a query. Supports various filtering and sorting options.

```APIDOC
## mca_search

### Description
Search the archive for past conversations.

### Method
Not applicable (Tool function)

### Endpoint
Not applicable (Tool function)

### Parameters
#### Query Parameters
- **query** (string) - Required - What to search for.
- **mode** (string) - Optional - `semantic` (default), `keyword`, or `hybrid`.
- **limit** (int) - Optional - Max results (default: 10).
- **platform** (string) - Optional - Filter to a platform (chatgpt, anthropic, grok, claude_code, cursor).
- **group** (string) - Optional - Filter to a named thread group.
- **hours_back** (int) - Optional - Only search messages from the last N hours.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.