Claude Conversation Memory System

Upgrading an install that points at a checkout?scripts/switch_mcp_config.pyrewrites both config formats in place — dry run by default,--applyto write.

git clone https://github.com/adamkwhite/universal-memory-mcp.git cd universal-memory-mcp python3 -m venv .venv && source .venv/bin/activate pip install -e . python3 tests/validate_system.py # optional: verify the install

Point your client at<checkout>/.venv/bin/python3 -m universal_memory_mcp.server_fastmcp. The package uses relative imports, so running the file directly cannot work —python3 src/universal_memory_mcp/server_fastmcp.pyfails withattempted relative import with no known parent package.

Your client starts the server for you; run it by hand only to debug.

universal-memory-mcp # installed from PyPI python3 -m universal_memory_mcp.server_fastmcp # from source

# Import conversations from JSON export python3 scripts/bulk_import_enhanced.py your_conversations.json

Full-text search across all stored conversations with relevance ranking. Query text is treated as literal Unicode terms, so punctuation and FTS5 operators do not change the query semantics. Results include conversation IDs for exact retrieval.

get_conversation(conversation_id, max_chars=12000)

Retrieve a stored conversation by an ID returned from a search tool. Content is read from the authoritative JSON store and truncated tomax_charsto protect the model context.max_charsmust be between 1 and 50,000.

Find conversations tagged with a specific topic.

Store a new conversation with automatic topic extraction and FTS indexing.

Generate insights and patterns from recent conversations.

View search engine statistics — index size, topic counts, and engine status.

update_conversation(conversation_id, content=None, title=None, add_tags=None, remove_tags=None, set_tags=None, conversation_type=None, session_id=None, user_id=None, change_note=None, record_audit=True)

Update fields on an existing conversation in place. Passconversation_idplus any subset of fields to change; unspecified fields are left alone. By default, the first line of stored content is rewritten with a self-documenting audit line —[update <iso-timestamp> — <change_note>]— chained across repeated updates. Ifchange_noteis omitted, it is derived from the changed fields.

Setrecord_audit=Falseonly for authoritative imports whose content must remain an exact replica of the source system. Normal interactive updates should retain the default audit record.

Tag operations:set_tagsreplaces the full tag list and is mutually exclusive withadd_tags/remove_tags(passset_tags=[]to clear all tags);add_tags/remove_tagsmutate the existing list.

Returns a status string. On success:Status: successplus a summary message and, when enabled, the audit line. On failure (malformed ID, conversation not found, no changes provided, conflicting tag ops, or an I/O error):Status: errorplus a message describing the problem.

Find conversations tagged with a specific tag — a universal metadata field populated by importers or set viaupdate_conversation(e.g.starred,archived,workspace:my-project). Exact match, case-sensitive. Requires SQLite FTS to be enabled; without it, returns an error message.

search_by_session_id(session_id, limit=10)

Find all conversations sharing asession_id, useful for reconstructing a multi-turn session that spans several stored conversation records (e.g. a Cursor working session, a Claude thread continued across days). Results are sorted chronologically (oldest first). Requires SQLite FTS to be enabled; without it, returns an error message.

search_by_conversation_type(conversation_type, limit=10)

Find conversations byconversation_type(e.g.chat,code,analysis). Exact match, most recent first. Requires SQLite FTS to be enabled; without it, returns an error message.

~/claude-memory/ ├── conversations/ │ ├── 2025/ │ │ └── 06-june/ │ │ └── 2025-06-01_topic-name.md │ ├── index.json # Search index │ └── topics.json # Topic frequency └── summaries/ └── weekly/ └── week-2025-06-01.md

{ "mcpServers": { "universal-memory-mcp": { "command": "universal-memory-mcp" } } }

Installed from source rather than PyPI? Pointcommandat your virtualenv's interpreter and run the module:

{ "mcpServers": { "universal-memory-mcp": { "command": "/absolute/path/to/universal-memory-mcp/.venv/bin/python3", "args": ["-m", "universal_memory_mcp.server_fastmcp"] } } }

Upgrading from before the package move (#225):configs used to name the server script directly (src/server_fastmcp.py). That no longer works in any form — the modules moved undersrc/universal_memory_mcp/, and the package now uses relative imports, so running the file raisesattempted relative import with no known parent package. Switch to the console script or the-mform above.

As an alternative to environment variables, settings can be placed in~/.claude-memory/config.json. The file is optional — a missing file falls back to platform-profile/built-in defaults. Example:

{ "storage_path": "~/claude-memory", "log_format": "json", "log_level": "INFO", "enable_sqlite": true, "console_output": false, "platform_profile": "default" }

Unknown keys in the file raise a configuration error rather than being silently ignored. Environment variables still override anything set here.

SQLite FTS5 search is enabled by default. On platforms where SQLite/FTS5 is unavailable (e.g. some Windows Python builds), disable it to fall back to JSON-based linear search:

export CLAUDE_MEMORY_DISABLE_SQLITE=true

Switch between human-readable text logs (default) and structured JSON logs for production:

# JSON format (for production log aggregation) export CLAUDE_MCP_LOG_FORMAT=json # Text format (default, for development) export CLAUDE_MCP_LOG_FORMAT=text

{ "timestamp": "2025-01-15T10:30:45", "level": "INFO", "logger": "claude_memory_mcp", "function": "add_conversation", "line": 145, "message": "Added conversation successfully", "context": { "type": "performance", "duration_seconds": 0.045, "conversation_id": "conv_abc123" } }

- Production deployments with log aggregation (Datadog, ELK, CloudWatch)
- Automated monitoring and alerting
- Structured log analysis and querying
- Performance tracking and debugging

Seedocs/json-logging.mdfor detailed JSON logging documentation.

universal-memory-mcp/ ├── src/ │ ├── server_fastmcp.py # Main MCP server │ ├── conversation_memory.py # Core memory engine + SQLite FTS5 │ ├── format_detector.py # Auto-detect AI platform format │ ├── validators.py # Input validation │ ├── logging_config.py # Structured logging (text/JSON) │ ├── importers/ # Platform-specific importers │ │ ├── chatgpt_importer.py │ │ ├── claude_importer.py │ │ ├── cursor_importer.py │ │ └── generic_importer.py │ └── schemas/ # JSON schema validation ├── tests/ # 435 tests, 98.68% coverage ├── data/ # Consolidated app data ├── scripts/ # Import and utility scripts └── docs/ # Documentation

scripts/benchmark_search.pywas broken (unawaited async calls, measuring coroutine construction instead of real search time) from October 2025 until this was found and fixed. The previous numbers below were never actually measured and have been replaced with real ones. Reproduce with:

python scripts/generate_test_data.py --conversations 159 python scripts/benchmark_search.py --storage-path ~/claude-memory-test --iterations 5

Measured on a 159-conversation / 7.7MB local dataset (WSL2, Python 3.12) — treat as order-of-magnitude, not a precise SLA, results vary by machine:

- Search Speed (SQLite FTS5): mean 15–18ms, median 10–13ms per query, range 0.5–82ms across 12 query types (was claimed 0.2–0.5ms; that figure was never measured)
- Search vs. linear JSON scan: SQLite FTS5 is ~10x faster (mean 14.7ms vs 154.2ms; median 10.5ms vs 152.0ms) — the old "4.4x" claim had the right direction but was also never actually measured
- Topic Search: mean 3.4ms, median 2.5ms (was claimed 0.3–0.4ms; that figure was never measured)
- Write Speed: mean 14ms, median 14ms per ~49KB conversation, SQLite indexing included (was claimed ~33ms; that figure was never measured)
- Capacity: 371 conversations in production use over 10 months
- Test Coverage: 98.68% (435 tests) — 0 code smells, 0 security hotspots (SonarCloud verified)