Eidetic

Eidetic is an Agent-Agnostic Memory MCP Server. It provides a structured, long-term memory system via the Model Context Protocol (MCP).

Eidetic enables memory portability: a memory created by one agent (e.g. Claude Code) can be instantly recalled by another (e.g. Cursor).

Agents can automatically store, recall, deduplicate, and review project knowledge—such as architectural decisions, user preferences, and bug resolutions—so they never have to start from scratch.

Index

• Installation
• Agent Integration
• Features
• Storage Backends
  • Memwal
  • SQLite
  • File
• MCP Tools
• Harbor Backups & Artifacts
• TUI Storage Inspector
• License

Eidetic stores and recalls model generated artifacts (like images) that you can view in your system's default viewer.

Installation

You can install Eidetic in two ways:

1. Via NPM (Recommended)

You can install the pre-compiled binary wrapper globally using npm:

npm install -g eidetic-mcp

Or run it directly using npx:

npx eidetic-mcp

2. Via Cargo (From Source)

If you prefer to build from source, you can use Cargo:

git clone https://github.com/mcxross/eidetic.git
cd eidetic
cargo install --path .

Account Setup: Memwal & Harbor

Memwal Setup To fully automate the creation, registration, and funding of a Memwal backend account on the Sui network, use:

eidetic setup memwal

This interactive command guides you through generating an identity

Harbor Setup To enable secure database backups and artifact storage, configure Harbor:

eidetic setup harbor

You will be prompted for your Harbor API Key and Service Private Key. These are stored securely in your system's native keychain.

Agent Integration

Eidetic features a built-in auto-setup command to easily inject itself into the configuration files of popular coding agents.

Run the following command to register Eidetic with your agent of choice:

eidetic setup <agent>

Supported Agents

• claude - Claude Code CLI
• claude-desktop - Claude Desktop App
• cursor (or pi) - Cursor IDE
• vscode - Visual Studio Code
• opencode - OpenCode
• gemini-cli - Gemini CLI
• codex - OpenAI Codex CLI

Example:

eidetic setup cursor

This will automatically parse your ~/.cursor/mcp.json file, safely merge Eidetic as an available MCP server, and point the agent to the exact Eidetic executable path.

Features

MCP Server

Start the MCP server manually (usually handled automatically by your agent):

eidetic serve

By default, the server uses Memwal to store semantic memories.

Configuration

Eidetic persists its configuration in ~/.eidetic/config.json. This includes your storage backend preferences, custom paths, and Memwal configurations.

You can view the active configuration and backend details via:

eidetic info

Storage Backends

Eidetic supports multiple storage layers through --storage-backend or the EIDETIC_STORAGE_BACKEND environment variable.

Available backends:

| memwal | Default semantic memory network | | sqlite | Local relational database | | file | Simple JSON file storage |

Use --storage-path or EIDETIC_STORAGE_PATH to choose the local storage/index directory.

Memwal (Default)

Memwal is the default decentralized semantic memory network for Eidetic.

Start the MCP server with Memwal (default behavior):

eidetic serve

Or configure it with environment variables:

export EIDETIC_STORAGE_BACKEND=memwal
export EIDETIC_MEMWAL_REGISTRY_ID=0x...
eidetic serve

Memwal account selection is handled by Eidetic's authentication layer:

1. On startup, Eidetic reads ~/.sui/sui_config/client.yaml, sui.aliases, and the configured sui.keystore.
2. It derives available Ed25519 Sui accounts locally from private key material.
3. It defaults to client.yaml.active_address when that account has usable key material.
4. The memory storage layer receives only the active Memwal client/configuration; it does not manage private keys directly.

Memwal configuration options:

| CLI flag | Environment variable | Description | | --- | --- | --- | | --memwal-account-id | EIDETIC_MEMWAL_ACCOUNT_ID | Existing Memwal account object ID to reuse | | --memwal-registry-id | EIDETIC_MEMWAL_REGISTRY_ID | Memwal registry object ID for account reuse/creation | | --memwal-server-url | EIDETIC_MEMWAL_SERVER_URL | Memwal relayer/server URL | | --memwal-relayer-config-url | EIDETIC_MEMWAL_RELAYER_CONFIG_URL | Explicit relayer config URL | | --memwal-namespace | EIDETIC_MEMWAL_NAMESPACE | Memory namespace, defaults to eidetic | | --memwal-delegate-label | EIDETIC_MEMWAL_DELEGATE_LABEL | Delegate key label, defaults to eidetic-mcp | | --sui-config-dir | EIDETIC_SUI_CONFIG_DIR | Override Sui config directory, defaults to ~/.sui/sui_config |

Memwal MCP utility tools:

| Tool | Purpose | | --- | --- | | mem_sui_accounts | Lists usable Sui accounts discovered from ~/.sui without exposing private keys | | mem_select_sui_account | Selects the account used by Memwal operations for the current server process | | mem_memwal_config | Shows redacted active Memwal configuration and backend status |

Example account flow:

mem_sui_accounts
mem_select_sui_account { "selector": "my-sui-alias-or-0x-address" }
mem_memwal_config

Account selection is process-local. Eidetic does not persist the selected Memwal account across server restarts. If no account is selected after restart, Eidetic reloads ~/.sui and falls back to Sui's active_address.

Other Storage Options

If you prefer to store data strictly locally, Eidetic offers alternative backends.

SQLite

SQLite requires no external services:

eidetic --storage-backend sqlite serve

Choose a custom database directory:

eidetic --storage-backend sqlite --storage-path ~/.local/share/eidetic-mcp/storage serve

File

The file backend stores JSON documents directly on disk:

eidetic --storage-backend file serve

Choose a custom file storage directory:

eidetic --storage-backend file --storage-path ~/.local/share/eidetic-mcp/files serve

Use this backend when you want easy inspection or simple portable JSON files. SQLite is generally a better default for normal use.

MCP Tools

Eidetic exposes the following MCP tools to connected agents.

Core Memory

| Tool | Purpose | | --- | --- | | mem_save | Save a structured observation such as a decision, bugfix, pattern, discovery, task, note, or learning | | mem_update | Update an existing observation by ID | | mem_delete | Delete an observation; soft delete is the default, hard delete is optional | | mem_search | Full-text search across memories for the current or specified project | | mem_get_observation | Fetch the full content and metadata for a specific memory | | mem_suggest_topic_key | Suggest a stable topic_key before saving evolving topic-based memories | | mem_save_prompt | Save a user prompt for future context |

Sessions

| Tool | Purpose | | --- | --- | | mem_session_start | Register the start of a work session | | mem_session_end | Mark a session as completed | | mem_context | Retrieve recent context from previous sessions and observations | | mem_session_summary | Save an end-of-session summary |

Projects

| Tool | Purpose | | --- | --- | | mem_current_project | Detect the current project from a working directory; recommended as a first call | | mem_merge_projects | Merge project name variants into a canonical project |

Advanced Review and Relations

| Tool | Purpose | | --- | --- | | mem_timeline | Get chronological context around a specific observation | | mem_capture_passive | Extract learnings from text output and save them as memories | | mem_review | List observations whose review lifecycle is stale; can mark items reviewed | | mem_judge | Record a verdict for a pending memory conflict surfaced by mem_save | | mem_compare | Persist a semantic relation verdict between two existing observations |

Diagnostics and Configuration

| Tool | Purpose | | --- | --- | | mem_stats | Return memory system statistics for a project | | mem_doctor | Run read-only diagnostics for project detection and storage health | | eidetic_status | Return server health, current config, and actionable Memwal gas errors |

Artifact Management

| Tool | Purpose | | --- | --- | | mem_save_artifact | Upload raw bytes (code, images, etc.) to Harbor and save a reference locally or semantically | | mem_get_artifact | Download and decode an artifact from Harbor using its File ID |

Memwal Account Tools

These tools are available when the server is running with --storage-backend memwal.

| Tool | Purpose | | --- | --- | | mem_sui_accounts | List usable Sui accounts discovered from ~/.sui without exposing private keys | | mem_select_sui_account | Select the Sui account used by Memwal operations for the current server process | | mem_memwal_config | Show redacted active Memwal account and backend configuration |

Harbor Backups & Artifacts

Eidetic natively integrates with Harbor for secure object storage. Once configured (eidetic setup harbor), you can safely backup your local database or store model-generated artifacts.

Database Backups

Snapshot and upload your local database to Harbor:

eidetic backup

Restore a specific backup:

eidetic restore monday

Artifacts

When an agent creates an artifact (like code or images), it is sent directly to Harbor. A semantic reference is then saved to your active memory backend. Agents can seamlessly recall and download these artifacts using their natural context.

TUI Storage Inspector

Eidetic comes with a built-in Terminal UI to easily inspect, search, review, and delete the memories stored by your agents.

eidetic tui

Controls:

• Tab - Switch views (Projects, Observations, Sessions, Search)
• Enter - View details for an observation
• d - Soft-delete an observation
• D - Hard-delete an observation
• r - Mark an observation as reviewed
• / - Open search

Debugging and Inspector

If you want to manually inspect and debug the Eidetic MCP server, you can use the official MCP Inspector.

To run the inspector using npx:

npx @modelcontextprotocol/inspector eidetic serve

If you are developing locally from source, you can also run:

npx @modelcontextprotocol/inspector cargo run -- serve

For more details on inspecting and debugging, please refer to the official MCP documentation:

• MCP Inspector
• MCP Debugging

License

Apache 2.0