Eve Memory Client

eve-memory-client is the Python distribution for the local eve CLI. It connects supported AI tools to the hosted Eve memory service.

It detects local tools, configures MCP, installs Eve-managed prompt and hook files where supported, manages auth, and can verify, repair, or remove the integration later. It can also import local history from supported clients.

How Eve Works

When you run eve install, Eve configures four lifecycle hooks that run automatically — no commands needed during your sessions.

Lifecycle hooks are available on Claude Code and Gemini CLI. Eve also connects to Codex CLI and other MCP-compatible clients using prompt seeding, so you get memory across all your tools.

Quick Start — 5 minutes

1. Get an Eve workspace

Request access at evemem.com. After provisioning, sign in and create an API key at evemem.com/app/overview.

2. Install the client

uv tool install eve-memory-client

No uv? Use:

pipx install eve-memory-client

Verify: eve version

Security note: install the PyPI package named eve-memory-client. Do not install eve-client; that PyPI name is owned by a third party.

3. Connect Claude Code (swap --tool gemini-cli for Gemini CLI)

eve connect --tool claude-code --api-key <your-eve-api-key>

This combines auth, install, and verify. For step-by-step, see API key flow below.

Expected output:

✓ MCP config written
✓ CLAUDE.md companion updated
✓ Lifecycle hooks configured — Eve auto-injects memory context on every session
✓ Eve memory is connected and responding

What just happened? Eve installed four lifecycle hooks. From this point forward, every Claude Code session starts with your memory context pre-loaded, and ends with new learnings captured. You never need to ask Claude to use Eve.

If eve connect fails: run eve doctor --tool claude-code and check the diagnostics output. Open an issue at github.com/evememory/eve-client.

4. Test memory across sessions

In Claude Code, tell Claude:

"Remember that I use PostgreSQL with a users table — email and created_at columns."

Start a new Claude Code session and ask:

"What database setup did I mention?"

Claude will recall it via Eve. ✓

See examples/ for manual MCP config snippets (no installer needed).

For distribution-channel status across Claude, Codex, ChatGPT, Gemini, Cursor, VS Code, and Windsurf, see CHANNELS.md.

Hermes CLI

Eve supports profile-scoped Hermes connections with Hermes 0.20.5 or newer. Hermes supports two separate Eve memory paths.

Native Eve memory provider

Install eve-memory-client into the same Python environment that runs Hermes:

<hermes-python> -m pip install eve-memory-client

The base client does not install or replace the host application's MCP Python SDK. The optional local eve-mcp-server bridge uses MCP SDK 2 through the server extra.

Configure the active named profile:

hermes --profile work memory setup

Select eve when prompted. Hermes stores EVE_API_KEY in that profile's secret environment. It stores other Eve values in that profile's eve.json. session_end_timeout_seconds defaults to 20 seconds and accepts values from 5 through 30. It is a behavioral setting in eve.json, not an environment variable. The native provider gives bounded automatic recall, pre-compaction memory processing, and end-of-session extraction. It exposes no model-callable Eve tools.

Existing Eve MCP connector

Connect or reauthenticate a named Hermes profile with the existing OAuth path:

eve connect --tool hermes --profile work

Verify that the profile points to the Eve MCP endpoint and that Hermes can reach it:

eve verify --tool hermes --profile work

This is the OAuth path for explicit Eve MCP tools. The native provider and MCP connector do not share credentials. Neither path replaces the other.

Existing profiles use fresh reauthentication when you run eve connect again. To upgrade Hermes itself, use its official updater:

hermes update

To upgrade the Eve client:

uv tool upgrade eve-memory-client

If you installed with pipx, use pipx upgrade eve-memory-client instead.

Install

Before installing the client, get an Eve workspace:

• Request access: https://evemem.com
• After your workspace is provisioned, sign in to the Eve dashboard:
  • https://evemem.com/app/overview
• If you plan to use API-key auth, create or rotate a tenant key from the Eve admin/user setup flow before connecting your client.

From PyPI

Preferred:

uv tool install eve-memory-client

Alternative:

pipx install eve-memory-client

The PyPI distribution is eve-memory-client; eve-client is not used as the PyPI name because that namespace is occupied by a third party. Official PyPI page: pypi.org/project/eve-memory-client.

Development install from GitHub

Use this only when testing unreleased client changes:

uv tool install git+https://github.com/evememory/eve-client.git

Or via the standalone bash installer. Save it first; do not pipe remote shell directly into sh:

curl -fsSL https://raw.githubusercontent.com/evememory/eve-client/main/install.sh -o install-eve.sh
sh install-eve.sh

Then confirm:

eve version
eve --help

Manual config (no installer)

See examples/ for ready-to-paste MCP config snippets for Claude Code, Gemini CLI, and Codex CLI.

What Eve Client Does

• detects supported local AI clients
• shows an install plan before changing files
• writes Eve-managed MCP config
• installs prompt/companion files where supported
• installs four lifecycle hooks that auto-inject memory context on every session (SessionStart, UserPromptSubmit, PreCompact, Stop)
• stores auth locally using file-based credential storage
• provides eve memory search and eve memory status commands for direct memory access
• verifies, repairs, rolls back, and uninstalls Eve-managed changes
• imports local conversation history into Eve from supported clients

Importing Local History

Supported importer sources today:

• Claude Code
• Codex CLI
• Gemini CLI

Core commands:

eve import scan --source claude-code
eve import preview --source claude-code --path <session_file>
eve import jobs                              # list scan jobs
eve auth login --tool claude-code
eve import upload --job <scan_job_id> --use-auth-from claude-code
eve import runs                              # list upload runs
eve import resume --run <run_id>
eve import cleanup --days 30
eve import cleanup --days 30 --apply

How it works:

• parses local history on your machine
• uploads normalized batches to the managed Eve service
• keeps a local SQLite ledger for scan jobs, upload runs, replay, and resume
• supports dry-run cleanup of old completed local importer runs by default

Importer maintenance:

• eve import cleanup is a generic local ledger maintenance command, not a client-specific import source feature

Auth note:

• avoid passing secrets directly on the command line when possible
• prefer eve auth login ... first, then run importer commands without repeating the API key
• in an interactive shell, eve auth login --tool claude-code prompts for the key securely

Current rollout note:

• correctness and resume are solid
• very large imports, especially Claude-heavy ones, may still be slower than ideal while batching defaults continue to be tuned

Supported Clients

Claude Code

Supported today:

• MCP config
• CLAUDE.md companion file
• package-managed hooks
• importer support: scan, preview, upload, resume

Primary auth path today:

• Eve API key

Gemini CLI

Supported today:

• MCP config
• GEMINI.md companion file
• package-managed hooks
• importer support: scan, preview, upload, resume

Primary auth path today:

• Eve API key

Codex CLI

Supported today:

• MCP config
• Eve-owned OAuth login
• runtime bearer token injection
• importer support: scan, preview, upload, resume

Primary auth path today:

• Eve OAuth

Important:

• native Codex MCP login is not the supported Eve path

Claude Desktop

Not auto-configured locally for hosted Eve.

For the hosted remote MCP connector path, see connectors/claude-desktop/.

ChatGPT

ChatGPT uses Eve's hosted MCP endpoint through a custom MCP app or connector flow. It is not installed by the local CLI.

For validation and submission notes, see connectors/chatgpt/.

Authentication Requirements

You need an Eve workspace and either:

• an Eve API key, or
• Eve OAuth access for supported flows

Current auth expectations:

• Claude Code: API key
• Gemini CLI: API key
• Codex CLI: Eve OAuth

OAuth browser flow exists for more clients, but it is still experimental outside the Codex path and should not be treated as the default production installer flow yet.

Basic Usage

First run

eve quickstart
eve connect --tool claude-code
eve verify --tool claude-code

API key flow

eve auth login --tool claude-code --api-key <eve-key>
eve install --tool claude-code --apply --yes  # --apply writes config, --yes skips confirmation
eve verify --tool claude-code

Codex OAuth flow

eve auth login --tool codex-cli --auth-mode oauth
eve install --tool codex-cli --auth-mode oauth --apply --yes
eve verify --tool codex-cli --auth-mode oauth

Memory commands

eve memory search "what database do we use" --context naya
eve memory search "auth patterns" --limit 5 --json
eve memory status
eve memory status --json

Common commands

eve quickstart
eve connect
eve install --dry-run
eve install --apply --yes --tool claude-code
eve status
eve doctor
eve verify
eve repair --tool gemini-cli --apply --yes
eve uninstall --tool claude-code --yes
eve run --tool codex-cli -- exec "Use Eve memory to search for my latest preference."

Manual MCP Configuration

If you do not want the installer to edit client config for you, add the hosted Eve MCP server manually.

Shared hosted MCP endpoint

https://mcp.evemem.com/mcp

Claude Code / Gemini CLI (API key)

Use a tenant API key from the Eve admin panel.

{
  "eve-memory": {
    "type": "http",
    "url": "https://mcp.evemem.com/mcp",
    "headers": {
      "X-API-Key": "eve_<tenant>_...",
      "X-Source-Agent": "claude_code"
    }
  }
}

For Gemini, keep the same shape and change:

X-Source-Agent = gemini_cli

Codex CLI (OAuth)

Codex should use an Eve-owned bearer token, not native codex mcp login.

[mcp_servers.eve-memory]
url = "https://mcp.evemem.com/mcp"
bearer_token_env_var = "EVE_CODEX_BEARER_TOKEN"
startup_timeout_sec = 60

[mcp_servers.eve-memory.headers]
X-Source-Agent = "codex_cli"

OAuth resource:

https://mcp.evemem.com/mcp

Codex prompt seeding belongs in the active project AGENTS.md. Eve manages its own marked block inside that file rather than creating a parallel sidecar file.

Other MCP clients

For other remote MCP clients, the minimum working setup is:

1. MCP URL:

https://mcp.evemem.com/mcp

2. One source-agent header:

X-Source-Agent: your_client_name

3. Choose one auth style:

• API key:

X-API-Key: eve_<tenant>_...

• OAuth bearer:

Authorization: Bearer <token>

4. For OAuth-capable clients, use this resource identifier:

https://mcp.evemem.com/mcp

5. Required scopes:

memory.read
memory.write

If the client supports a companion instruction file, point it at the active instruction file for that tool rather than inventing a second parallel file.

Which auth path to use

• Claude Code: API key
• Gemini CLI: API key
• Codex CLI: Eve OAuth

If you want Eve to manage the config, prompts, hooks, and verification for you, use eve connect instead of editing files manually.

Safety Model

• no silent shell profile mutation
• no undocumented hooks
• no overwrite of user-authored instruction files
• backup and manifest tracking before mutation
• explicit rollback and uninstall support
• uninstall removes Eve-managed credentials and tool entries, and warns when a user-modified Eve-owned file requires manual review

Development

Run tests:

uv run pytest --cov=eve_client --cov-report=term-missing -q tests

Build Python artifacts:

uv build .

The current release is eve-memory-client 0.3.9. See CHANGELOG.md for release details.

Check build artifacts:

uvx twine check dist/*

Build standalone release artifacts:

bash scripts/build-eve-client-release.sh

Release tags for the PyPI distribution use eve-memory-client@<version>, for example eve-memory-client@0.3.9.

License

Apache-2.0. See LICENSE.