# EMM — Extended Memory Management

[![Release](https://img.shields.io/github/v/release/tkraljevic/EMM)](https://github.com/tkraljevic/EMM/releases)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%E2%89%A522.5-339933)](https://nodejs.org)

**Persistent memory for AI agents — local, lightweight, model-independent, and MCP-native.**

EMM is a standalone memory layer that gives AI agents persistent long-term
memory without tying your data to a specific model, provider, or
application.

Your memory belongs to you, not to the model using it.

Any MCP-compatible AI client can access the same memory store, allowing
models and applications to be replaced without losing accumulated
knowledge.

## The idea

Large language models have context windows, not durable memory. Keeping an
ever-growing history inside the context is inefficient, expensive, and
eventually impractical.

EMM takes a different approach:

> Store everything. Keep the active context small. Retrieve only what matters.

The complete memory store lives locally in SQLite. Agents receive only a
compact memory map and retrieve relevant information on demand through
MCP. This keeps context overhead small even as the memory database grows.

## Core principles

- **Model-independent** — memory survives changes of model, provider, or AI application.
- **MCP-native** — designed to work with any MCP-capable agent.
- **Local-first** — your memory remains under your control.
- **Persistent** — knowledge survives sessions and conversations.
- **Context-efficient** — only relevant memory enters the model context.
- **Lightweight** — designed as a small standalone service with minimal dependencies.
- **Portable** — one database can move between machines and clients.
- **Scoped** — memories can belong to individual projects or remain globally available.
- **Lifecycle-aware** — memories can evolve, supersede older information, decay in relevance, and be archived.
- **Deterministic core** — EMM manages storage and retrieval while reasoning remains the responsibility of the agent.

## Memory architecture

EMM organizes memory conceptually into three layers:

**Hot → Warm → Cold**

- **Hot** memory contains the small amount of information an agent should
  always have available, such as the memory protocol, directives, project
  map, and current checkpoint.
- **Warm** memory contains searchable summaries, triggers, metadata, and
  references.
- **Cold** memory contains the full stored information and is retrieved
  only when needed.

The result is a memory system whose storage can continue growing without
requiring the model's active context to grow with it.

> An AI model should be replaceable. Your memory shouldn't be.
> One memory. Any model.

## Features

- 🔌 **Any MCP client** — Claude Code, Claude Desktop, OpenCode, LM Studio, Antigravity
- 🧠 **One shared database**, portable between machines, plain SQLite you can inspect or back up yourself
- 🧹 **Self-managing** — decay and opt-in archival keep old, unused entries from cluttering search, with thresholds you control (see below)
- 🗂️ **Project scoping** — keep facts from bleeding between unrelated projects, or share them everywhere
- 🌐 **Web dashboard, login-protected** — browse, search, and edit memory from a browser (`--transport http`); the AI-facing MCP endpoint stays open for client compatibility, only the human dashboard requires signing in
- ⚙️ **Configurable from the dashboard** — decay half-life, archive threshold, and the login itself are editable in Settings, not fixed constants
- 📦 **Standalone binaries** — run it with no Node.js installed at all

## Install

```bash
git clone https://github.com/tkraljevic/EMM.git
cd EMM
npm install && npm run build
node scripts/install.mjs   # auto-detects your AI clients and registers EMM
```

Or, for a guided one-shot setup: double-click `setup.bat` (Windows) or run
`./EMM-Macs/setup.command` (macOS). Prefer a prebuilt binary or manual
per-client config? See [docs/BINARIES.md](docs/BINARIES.md) and
[docs/CLIENTS.md](docs/CLIENTS.md).

Restart your AI client, then say **"call memory_index"** — you should see
the `== EMM MEMORY PROTOCOL v1 ==` block.

## Usage

Add a short rule to your system prompt / `CLAUDE.md` so agents use it
without being asked:

> At session start call `memory_index` (pass `scope: <project/repo name>`
> for project-specific work). Before saying you don't know about prior
> work, decisions, or preferences, call `memory_search`. On long sessions,
> call `memory_checkpoint` every ~15-20 turns. At session end, store one
> `digests` entry summarizing what happened.

## Learn more

| Doc | Covers |
|---|---|
| [docs/CLIENTS.md](docs/CLIENTS.md) | Manual MCP config for each client |
| [docs/GUIDE.md](docs/GUIDE.md) | Project scoping, memory decay & archival, moving memory between computers, HTTP transport & dashboard login/settings |
| [docs/BINARIES.md](docs/BINARIES.md) | Standalone binaries — building and cross-building them |
| [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) | Running tests, dev commands |
| [Input_EMM/agent.md](Input_EMM/agent.md) | Design decisions, rejected alternatives, roadmap |

## License

MIT