Local-first 6-layer AI memory system for coding agents.
Zero config. Zero cloud. Runs inside Claude Code, Cursor, and Codex.

Quick Start · Architecture · Tools · Setup · Docs · 简体中文 · 繁體中文 · 日本語

---

What is EverMind?

EverMind gives AI coding agents persistent memory across sessions. It embeds directly into Claude Code, Cursor, and Codex via MCP — no cloud, no separate server, no API keys required, no configuration beyond pointing it at your repo.

Memory is organized into 6 layers modeled after how humans store knowledge: working notes that expire, episodic events, semantic facts, procedural knowledge, permanent archive decisions, and a graph of entity relationships. The right layer is chosen automatically based on content and importance.

The Problem

AI agents forget everything between sessions:

• Why a module was designed a certain way
• Which command actually builds or tests the project
• Known bugs and the fixes that worked
• Deployment procedures and pitfalls
• Personal preferences and coding conventions

EverMind solves this by giving agents a reliable place to store and retrieve that knowledge.

Architecture

          Claude Code / Cursor / Codex
                     |
                  MCP (stdio)
                     |
           +-----------------------+
           |   EverMind v2 Core    |
           |                       |
           |  remember / recall    |
           |  forget  / briefing   |
           |  codebase + archive   |
           +-----------+-----------+
                       |
           +-----------v-----------+
           |   SQLite              |
           |   (one file/project)  |
           |                       |
           |  Layer 1: working     |  24h auto-expire
           |  Layer 2: episodic    |  events & discoveries
           |  Layer 3: semantic    |  project facts
           |  Layer 4: procedural  |  how-to knowledge
           |  Layer 5: archive     |  permanent decisions
           |  Layer 6: graph       |  entity relationships (auto-extracted from content)
           |                       |
           |  FTS5 keyword search  |
           |  sqlite-vec KNN       |
           |  event log            |
           +-----------------------+

Storage: ~/.evermind/<project-slug>.db — one SQLite file per project, name auto-detected from git remote.

How EverMind Works

EverMind has two components that work together:

MCP Server — the tools Claude Code calls directly:

Tool group	What it does
Memory tools	briefing, remember, recall, forget, graph_explore, status, health, etc.
Codebase tools	index_repository, get_architecture, search_code, search_graph, trace_path, etc.
Archive tools	search_notes, read_note, write_note, propose_basic_memory_update, commit_basic_memory_update, etc.

Skills — instruction files that tell Claude when and how to use the tools:

• skills/evermind/SKILL.md — core workflow: session start protocol, when to remember
• skills/evermind-archive/SKILL.md — permanent knowledge patterns
• skills/evermind-code-graph/SKILL.md — codebase exploration
• skills/project-memory/SKILL.md — first-time project initialization

Reference a skill from your CLAUDE.md or AGENTS.md:

$evermind

Or with full path if the skill isn't on your skills search path:

$D:/path/to/EverMind/skills/evermind/SKILL.md

Both components are needed. The MCP server gives Claude the ability to remember things. The skills tell Claude when to use that ability.

Quick Start

1. Clone

git clone https://github.com/YPYT1/EverMind.git
cd EverMind

2. Run the setup script

Windows:

powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1

macOS / Linux:

bash scripts/setup-macos.sh

The script checks Python 3.11+, installs uv if missing, syncs dependencies, and auto-configures Claude Desktop and Cursor.

Codebase and archive engines

EverMind exposes 42 tools through the same evermind MCP server. scripts/windows/install-all.ps1 and scripts/macos/install-all.sh install codebase-memory-mcp v0.9.0 and basic-memory v0.22.1 as internal engines; clients still register only EverMind.

For new projects, run index_repository, then get_architecture/search_code, then save verified findings:

remember("Tech stack: ...", importance=1, tags=["codebase-verified"], meta={"source":"codebase"})
remember("Entry point: ...", importance=1, tags=["codebase-verified"], meta={"source":"codebase"})
remember("Key structure: ...", importance=1, tags=["codebase-verified"], meta={"source":"codebase"})

Verified negative facts can outrank older unverified memories and produce forget_suggestions when conflicts are detected.

---

3. Manual config (optional)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "evermind": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/EverMind/mcp", "evermind-mcp"]
    }
  }
}

Replace /path/to/EverMind with the actual clone path. That is the only required change.

4. Enable vector search (optional but recommended)

cd mcp
uv pip install sqlite-vec sentence-transformers

Without these, EverMind uses FTS5 keyword search. With them, recall() runs hybrid BM25 + vector KNN — significantly better for semantic queries like "what did we decide about the auth module".

MCP Tools

Tool	Purpose
remember(content, importance, tags)	Save to memory. importance: 0 = working (24h), 1 = long-term, 2 = permanent
update_memory(id, content, tags, meta)	Correct an existing memory without deleting it; rebuilds search, embeddings, graph links, and briefing cache
recall(query, limit, mode)	Hybrid BM25 + semantic search. Auto-detects project from git
forget(id)	Delete a memory by ID
briefing()	Load session context: recent + important memories for this project
list(layer, tags, limit)	List memories filtered by layer and/or tags
graph_explore(entity)	Explore entity relationships in the knowledge graph

Memory type is auto-detected from content: bug fixes → episodic, architecture decisions → semantic, deploy steps → procedural. Set importance=2 for things you never want deleted.

Setup

Windows

powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1

What the script does:

• Checks Python 3.11+, uv, git
• Offers to install uv if not found
• Runs uv sync in the mcp directory
• Auto-updates Claude Desktop and Cursor MCP configs
• Creates ~/.evermind memory directory

macOS

bash scripts/setup-macos.sh

Same steps as Windows, using macOS config paths (~/Library/Application Support/Claude/).

Manual install

# Install dependencies
uv sync --directory mcp

# Optional: vector search (recommended)
cd mcp && uv pip install sqlite-vec sentence-transformers

Memory Lifecycle

Layer	Retention	Use for
working	24 hours	Temporary notes, WIP context
episodic	Long-term	Events, bug fixes, discoveries
semantic	Long-term	Facts about the project
procedural	Long-term	Deploy steps, workflows, how-to
archive	Permanent	Architecture decisions, permanent rules
graph	Permanent	Entity relationships (auto-extracted from content)

• importance=0 — working layer (default, expires in 24h)
• importance=1 — long-term layer (auto-classified by content type)
• importance=2 — archive layer (never deleted)

Agent Instructions

Add to CLAUDE.md or AGENTS.md:

## EverMind Memory

Call briefing() at session start to restore project context.
Call remember(content) for anything worth keeping across sessions.
Call recall(query) before starting work on a feature or bug.

importance=0: temporary working note (default)
importance=1: long-term memory
importance=2: permanent archive (architecture decisions, critical bugs)

Docs

• Architecture
• MCP Tools Reference
• Configuration
• Quickstart Windows
• Quickstart macOS
• Troubleshooting
• v2 Redesign Notes

---

Community & Support

_{Join the EverMind community}

Community

Support EverMind development

Built for engineers who want their AI tools to actually remember things.