Skip to main content
Glama

Marvin's Local Memory Plugin

A zero-Docker, zero-API-key, cross-platform local memory stack for AI coding assistants and digital companions. Works natively as an Antigravity Plugin and universally as a stdio MCP Server across Claude Code, Cursor, Codex, Windsurf, and OpenClaw on Windows, macOS, and Linux.


Why We Built This

Most local agent memory tools either require heavy Docker containers (Neo4j / Qdrant), burn API credits on every message, scatter databases across random project folders, or silently return blank results when background compactions run.

Marvin's Local Memory Plugin puts everything inside one clean memory/ folder and keeps a lightweight FastEmbed + LanceDB + Bi-Temporal Property Graph daemon warm in RAM:

  • Zero Docker & Zero API Keys: Embeddings run locally via FastEmbed (BAAI/bge-small-en-v1.5, 384d) and storage runs embedded on disk via LanceDB. Background Dream Consolidation pipes episodes via stdin to your local agy subscription CLI (or any custom CLI like claude -p or ollama).

  • Self-Healing Warm Daemon: Automatically calls checkout_latest() and reopens stale .lance fragment handles so background compactions never cause HTTP 500 errors.

  • No Silent Failures: Surfaces an explicit [MEMORY LAYER WARNING] if recall degrades instead of feeding blank context silently.

  • Bi-Temporal State Tracking: Tracks project phases cleanly and marks old phases active=False when you transition forward.


Related MCP server: LumenCore

5-Minute Quickstart

1. Run One-Command Setup

From inside the plugins/marvins-local-memory directory:

python scripts/setup.py

This installs Python dependencies (lancedb, fastembed, pyarrow, aiohttp), creates your memory/ workspace layout, starts the warm daemon on http://127.0.0.1:8765, and prints the exact copy-paste MCP config snippet for your machine.

2. Connect to Your Harness

Option A: Google Antigravity (Full Native Integration)

  1. Copy or clone plugins/marvins-local-memory/ into ~/.gemini/config/plugins/marvins-local-memory/ (or load it from your workspace plugins/ folder).

  2. Enable Marvin's Local Memory Plugin in Antigravity Customizations.

  3. Antigravity automatically loads:

    • hooks.json (PreInvocation hook injecting Layers 2A, 2B, 3A, 3B on every turn)

    • mcp_config.json (MCP tools deep_recall, search_memory, get_state, set_state, memory_health)

    • rules/AGENTS.md + skills/marvins-local-memory/SKILL.md

Option B: Claude Code, Cursor, Codex, Windsurf, or OpenClaw (Universal MCP)

Add the marvins-local-memory stdio server to your client's MCP configuration (replacing /ABS/PATH/TO with your actual path, or copy the exact JSON printed by python scripts/setup.py):

{
  "mcpServers": {
    "marvins-local-memory": {
      "command": "python",
      "args": ["/ABS/PATH/TO/marvins-local-memory/scripts/mcp_server.py"],
      "env": {
        "COMPANION_MEMORY_DIR": "/ABS/PATH/TO/YOUR_PROJECT/memory"
      }
    }
  }
}

Folder Structure Created in Your Project (memory/)

memory/
├── lancedb/      # Embedded vector + BM25 hybrid database
├── graph/        # property_graph.json (entities + bi-temporal edges)
├── dossiers/     # Human-editable working memory sheets (active_focus.md, user_profile.md)
├── dreams/       # Rolling 14-day dream consolidation journals
├── inbox/        # Drop .md notes/session logs here for universal dream ingestion
└── state/        # High-water mark state for incremental consolidation

(Recommended: keep periodic backups outside your workspace directory.)


Environment Variables

Variable

Default

Purpose

COMPANION_MEMORY_DIR

./memory

Explicit directory for all memory storage folders

COMPANION_MEMORY_PORT

8765

Local port for the warm HTTP daemon (127.0.0.1)

COMPANION_DREAM_CMD

agy --disable-slash-commands -p

CLI command used for background Dream Consolidation (reads prompt from stdin)

COMPANION_MEMORY_QUERY

(empty)

Optional override query when testing pre_invocation.py directly


CLI Commands

# Check daemon + database health
python scripts/query_memory.py --diagnose

# Unified deep recall (2-hop graph + LanceDB)
python scripts/query_memory.py "API refactor decisions"

# Track or transition a project phase live
python scripts/query_memory.py --set-state "project:website" --op ADD --name "My Website" --entity-cat project --phase "Design" --summary "Drafting landing page" --next "Build shop checkout"

# Index existing markdown notes into LanceDB
python scripts/query_memory.py --index ./docs --category knowledge

# Compact LanceDB fragments cleanly (safe while daemon is running!)
python scripts/query_memory.py --compact

# Run background Dream Consolidation (zero API keys)
python scripts/query_memory.py --dream

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI coding assistants with persistent project memory to retain architectural decisions, code patterns, and domain knowledge across sessions. It stores data locally in a SQLite database, allowing agents to remember, recall, and manage project-specific context using full-text search.
      3 npm
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides persistent memory for AI tools by building a local knowledge graph from conversations, enabling cross-session recall and context awareness without cloud dependencies.
      9
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides a local long-term memory layer for AI coding tools like Cursor and Claude Code, enabling cross-session, cross-tool sharing of project facts, user preferences, decisions, and workflows.
      11 npm
      2
      MIT