Simple Memory

Simple Memory is a local, persistent memory layer for AI agents using the Model Context Protocol (MCP).

It gives agents a place to store and recall information across separate chats, tasks, and applications. Memories can contain any JSON data, so the server does not impose a specific workflow or domain.

What is it for?

Simple Memory can help an agent remember:

• Decisions, facts, risks, and ongoing work across multiple conversations
• Business operations, customers, agreements, and organizational knowledge
• Research findings together with their sources and confidence
• Plans, preferences, notes, and long-running personal projects
• Relationships and dependencies between stored information

Memories stay local and persistent. Agents can search, revise, connect, archive, and flag them for review over time. Multiple agents can coordinate safely with logical keys and revision checks, while optional access isolation can limit who may use each space.

Models

Simple Memory uses two local models:

• Qwen3-Embedding-0.6B converts memories and queries into vectors for multilingual semantic retrieval.
• Qwen3-Reranker-0.6B reviews the best candidates and improves their final ordering.

They were selected because they provide strong multilingual retrieval in a relatively small size that remains practical to run locally. Inference automatically prefers a supported GPU and falls back to CPU.

Where is memory stored?

Memories are stored locally in a SQLite database named memory.db.

The location can be changed with:

• SIMPLE_MEMORY_DATA_DIR for a different data directory
• SIMPLE_MEMORY_DB_PATH for a specific database file

Model files are stored separately in the standard Hugging Face cache.

Installation

Requirements:

• Node.js 22 or newer (latest LTS recommended)
• npm 10 or newer
• Internet access during the first model download

Clone the repository and run the setup command:

git clone https://github.com/gmacev/Simple-Memory-Extension-MCP-Server.git
cd Simple-Memory-Extension-MCP-Server
npm run setup

Or ask your agent to set up Simple Memory from this repository.

The first setup downloads the models if they are not already cached.

Updating

Completely stop the MCP client that is using Simple Memory, then update the repository and installation. The server must not be running because loaded native dependencies may need to be replaced:

git pull
npm run update

Restart the MCP client afterward.

Connect your agent

Configure your MCP client to launch the server through stdio. The client starts the server automatically; you do not need to run npm start separately.

Codex

Run:

codex mcp add simple-memory -- node /absolute/path/to/Simple-Memory-Extension-MCP-Server/dist/index.js

Claude Code

Run:

claude mcp add --scope user simple-memory -- node /absolute/path/to/Simple-Memory-Extension-MCP-Server/dist/index.js

Antigravity (Google)

Add this to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "simple-memory": {
      "command": "node",
      "args": ["/absolute/path/to/Simple-Memory-Extension-MCP-Server/dist/index.js"]
    }
  }
}

Available tools

Agents can also read complete memories and revision histories through MCP resources.

Environment variables

All configuration is optional; the defaults are suitable for a normal local installation.

General

Transport

Open HTTP is allowed on loopback only. OAuth public URLs and issuers must use HTTPS except during loopback development. The former SIMPLE_MEMORY_HTTP_TOKEN shared-secret setting is not supported.

Access control for shared use

Most local installations do not need this: a stdio server is open to the trusted agent that starts it.

Use fixed when separate local agent configurations share one database but should be limited to particular spaces. Give each configuration a trusted identity and its allowed spaces:

SIMPLE_MEMORY_ACCESS_MODE=fixed
SIMPLE_MEMORY_FIXED_PRINCIPAL=agent-a
SIMPLE_MEMORY_FIXED_ACCESS={"spaces":{"agent-a-private":"write","project-shared":"read"}}

Use oauth when a shared HTTP server serves separate users or agents. Your identity provider authenticates callers; Simple Memory enforces the access grants carried by their tokens.

Retrieval and models

Setup and Python

Standard Hugging Face variables such as HF_HOME can also be used to relocate the shared model cache.

License

MIT