Enhanced Memory

Enhanced Memory gives agents local, durable memory. It composes LangGraph's native SQLite BaseStore with provenance, strict time-to-live (TTL) reads, deterministic export, and a standard-input/output Model Context Protocol (MCP) server.

It doesn't implement document ingestion, generic retrieval-augmented generation (RAG), crawling, agent orchestration, a hosted application programming interface (API), or another vector database. LangGraph owns storage semantics. FastMCP owns protocol behavior. SQLite owns persistence.

Install

Add the Python library to a project:

uv add "enhanced-mem-vector-rag @ git+https://github.com/BjornMelin/[email protected]"

Install the emvr-mcp command in an isolated environment:

uv tool install "enhanced-mem-vector-rag @ git+https://github.com/BjornMelin/[email protected]"

PyPI trusted publishing is tracked in issue #11. The Git tag remains the canonical install source until that publisher is verified.

For source development:

git clone https://github.com/BjornMelin/enhanced-mem-vector-rag.git
cd enhanced-mem-vector-rag
uv sync --frozen
uv run pytest

Python API

Use MemoryService as the single owner of a local database connection:

from pathlib import Path

from emvr import MemoryRecord, MemoryService

with MemoryService(Path("memory.sqlite3")) as memory:
    record = MemoryRecord.create(
        kind="preference",
        content={"theme": "dark", "font_size": 15},
        source="settings-import",
        evidence=("user-confirmed",),
    )
    memory.upsert(
        ("users", "bjorn", "preferences"),
        "editor",
        record,
    )

    saved = memory.get(("users", "bjorn", "preferences"), "editor")
    assert saved is not None
    print(saved.content)

memory.native is a lifecycle-guarded LangGraph BaseStore, so you can pass it directly to graph.compile(store=...). Namespaces use non-empty tuples with non-empty labels that contain neither periods nor NUL bytes. The langgraph root is reserved. Namespace listing accepts * as a one-segment prefix or suffix wildcard.

The native surface supports filters, batch operations, TTL, and optional sqlite-vec indexing. Exact filters preserve JSON types, so booleans, numbers, arrays, and objects don't alias one another.

Semantic search is disabled by default. Construct the service with a LangGraph SQLite index configuration and an embedding function to enable cosine ranking. Other distance modes fail closed because the pinned SQLite adapter doesn't rank them consistently. The MCP server stays provider-free and supports exact lookup plus namespace and filter searches.

Semantic ranking supports the first 1,000 results per query. Narrow the namespace or filters instead of requesting a deeper semantic offset.

MCP server

The server uses standard input and output only. This keeps the default deployment local and avoids a remote authentication boundary.

{
  "mcpServers": {
    "enhanced-memory": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/BjornMelin/[email protected]",
        "emvr-mcp"
      ],
      "env": {
        "EMVR_DB_PATH": "/absolute/path/to/memory.sqlite3"
      }
    }
  }
}

The server exposes nine tools:

• memory_put, memory_get, memory_search, and memory_delete
• memory_purge_namespace and memory_list_namespaces
• memory_export, memory_sweep_expired, and memory_health

memory_put is an upsert. Every record stores its source, observation time, optional evidence, and a SHA-256 content digest. memory_export returns stable JavaScript Object Notation Lines (JSON Lines) ordered by namespace and key.

Persistence contract

Enhanced Memory preserves these storage guarantees:

• SQLite uses write-ahead logging (WAL) with synchronous=NORMAL, foreign keys enabled, and a five-second busy timeout.
• Expired records are swept before reads, searches, namespace listings, and exports, so callers don't receive stale records.
• Managed content must be a JSON object with string keys and finite numbers. Integers must fit LangGraph's native 64-bit storage range, from -2^63 through 2^64 - 1.
• TTL uses LangGraph's native minute-based sliding expiration semantics. Values must be finite, positive, and no more than 5,270,400 minutes (3,660 days).
• Vector indexing is opt-in. LangGraph's SQLite package supplies sqlite-vec, but Enhanced Memory selects no embedding provider or model.
• The on-disk schema is owned and migrated by langgraph-checkpoint-sqlite.

See architecture, support, and security for the operating boundary.

Development

Run every local quality gate before opening a pull request:

uv sync --frozen
uv run ruff format --check .
uv run ruff check .
uv run pyright
uv run pytest
uv build

License

MIT. See the license.