Skip to content
Back to search

marvins-local-memory

Give your AI companion or coding agent a real long-term memory that grows with you. Remembers past chats, bridges the gap between sessions, and delivers snappy local recall — 100% private, with no Docker or API keys.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aprylnators--marvins-local-memory/badge.svg)](/listings/aprylnators--marvins-local-memory)

HTML

<a href="/listings/aprylnators--marvins-local-memory"><img src="/api/listings/aprylnators--marvins-local-memory/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Run One-Command Setup

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

python scripts/setup.py

This installs the Python packages (`lancedb`, `fastembed`, `pyarrow`, `aiohttp`), creates your `memory/` folder, starts the background memory service 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 live state, dossiers, graph links, and recalled memories 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"
      }
    }
  }
}

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 120 lines
  1. # Marvin's Local Memory Plugin
  2. Give your AI companion or coding agent a **real long-term memory that grows with you**. It remembers past chats, bridges the gap between sessions, and delivers snappy local recall across sessions — **100% private on your own machine**, with **no Docker containers and no API keys**.
  3. Works natively in **Google Antigravity** and connects universally to **Claude Code, Cursor, Codex, Windsurf, and OpenClaw** on Windows, macOS, and Linux.
  4. ---
  5. ## What It Does (In Plain English)
  6. Most AI chats start over with a blank slate every time you open a new window. **Marvin's Local Memory Plugin** fixes that in one lightweight folder:
  7. - **Bridges the gap between sessions:** Stop re-explaining who you are, how you work, or where you left off every time you start a new conversation.
  8. - **Remembers your past chats & notes:** Save conversations, preferences, project decisions, lore, and markdown notes locally so your agent pulls back the right context when it matters.
  9. - **Snappy, instant recall:** Keeps a small local service warmed up in the background so memories appear quickly without slowing down your replies.
  10. - **Grows with your agent:** Keeps track of active projects and life chapters over time (so your AI knows what's happening *today* without forgetting finished milestones) and distils new notes into durable memories.
  11. - **100% private & free to run:** Everything stays in one clean `memory/` folder on your own computer — no cloud sync, no Docker setup, and zero per-message API charges.
  12. > **Moving a companion from ChatGPT, Claude, Gemini, or Character.AI?**
  13. > Follow our step-by-step **[Companion Migration Guide (`MIGRATION_GUIDE.md`)](MIGRATION_GUIDE.md)** to bring your saved memories, profile, and past chat logs straight into your new local setup.
  14. ---
  15. ## 5-Minute Quickstart
  16. ### 1. Run One-Command Setup
  17. From inside the `plugins/marvins-local-memory` directory:
  18. ```bash
  19. python scripts/setup.py
  20. ```
  21. This installs the Python packages (`lancedb`, `fastembed`, `pyarrow`, `aiohttp`), creates your `memory/` folder, starts the background memory service on `http://127.0.0.1:8765`, and prints the exact copy-paste MCP config snippet for your machine.
  22. ### 2. Connect to Your Harness
  23. #### Option A: Google Antigravity (Full Native Integration)
  24. 1. Copy or clone `plugins/marvins-local-memory/` into `~/.gemini/config/plugins/marvins-local-memory/` (or load it from your workspace `plugins/` folder).
  25. 2. Enable **Marvin's Local Memory Plugin** in Antigravity Customizations.
  26. 3. Antigravity automatically loads:
  27. - `hooks.json` (`PreInvocation` hook injecting live state, dossiers, graph links, and recalled memories on every turn)
  28. - `mcp_config.json` (MCP tools `deep_recall`, `search_memory`, `get_state`, `set_state`, `memory_health`)
  29. - `rules/AGENTS.md` + `skills/marvins-local-memory/SKILL.md`
  30. #### Option B: Claude Code, Cursor, Codex, Windsurf, or OpenClaw (Universal MCP)
  31. 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`):
  32. ```json
  33. {
  34. "mcpServers": {
  35. "marvins-local-memory": {
  36. "command": "python",
  37. "args": ["/ABS/PATH/TO/marvins-local-memory/scripts/mcp_server.py"],
  38. "env": {
  39. "COMPANION_MEMORY_DIR": "/ABS/PATH/TO/YOUR_PROJECT/memory"
  40. }
  41. }
  42. }
  43. }
  44. ```
  45. ---
  46. ## Folder Structure Created in Your Project (`memory/`)
  47. ```text
  48. memory/
  49. ├── lancedb/ # Searchable archive of past chats, notes & memories
  50. ├── graph/ # Active projects, habits, preferences & chapter history
  51. ├── dossiers/ # Plain-text "always remember" sheets (active_focus.md, user_profile.md)
  52. ├── dreams/ # Rolling 14-day dream consolidation journals
  53. ├── inbox/ # Drop .md notes or session logs here to consolidate new memories
  54. └── state/ # Incremental progress tracker for dream runs
  55. ```
  56. *(Recommended: keep periodic backups of `memory/` **outside** your workspace directory.)*
  57. ---
  58. ## Under the Hood (For Developers & Tinkerers)
  59. - **Zero-Docker Hybrid Search:** Embeddings run locally via `FastEmbed` (`BAAI/bge-small-en-v1.5`, 384d) paired with embedded `LanceDB` hybrid vector + BM25 search and recency weighting.
  60. - **Bi-Temporal Property Graph:** Tracks entities, relations, and phase transitions in `property_graph.json` (using atomic temp-file replacement) mirrored to LanceDB, automatically marking superseded phases `active=False`.
  61. - **Self-Healing Warm Daemon (`127.0.0.1:8765`):** Binds localhost-only with `Host` allowlisting, `Origin` / `Sec-Fetch-Site` CSRF rejection, strict `Content-Type: application/json` enforcement on `POST`, input allowlist validation, bounded `limit`/`hops`, and automatic `checkout_latest()` + handle reopen so background compactions never trigger HTTP 500 errors.
  62. - **No Silent Failures:** Surfaces an explicit `[MEMORY LAYER WARNING]` if recall degrades instead of returning empty context silently.
  63. - **Zero-API-Key Dream Consolidation:** Chunks episodes from `memory/inbox/*.md` (and optionally Antigravity transcripts when opted in) and pipes prompts over `stdin` (`shell=False`) to your local `agy` CLI, `claude -p`, or `ollama`.
  64. ### Environment Variables
  65. | Variable | Default | Purpose |
  66. | :--- | :--- | :--- |
  67. | `COMPANION_MEMORY_DIR` | `./memory` | Explicit directory for all memory storage folders |
  68. | `COMPANION_MEMORY_PORT` | `8765` | Local port for the warm HTTP daemon (`127.0.0.1`) |
  69. | `COMPANION_DREAM_CMD` | `agy --disable-slash-commands -p` | CLI command used for Dream Consolidation (reads prompt from `stdin`) |
  70. | `COMPANION_DREAM_SCAN_GLOBAL_TRANSCRIPTS` | `0` (off) | Set to `1` to allow `--dream` to also read `~/.gemini/antigravity/brain` session transcripts |
  71. | `COMPANION_MEMORY_QUERY` | *(empty)* | Optional override query when testing `pre_invocation.py` directly |
  72. ### CLI Commands
  73. ```bash
  74. # Check daemon + database health
  75. python scripts/query_memory.py --diagnose
  76. # Unified deep recall (2-hop graph + LanceDB)
  77. python scripts/query_memory.py "API refactor decisions"
  78. # Track or transition a project phase live
  79. 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"
  80. # Index existing markdown or plain-text notes/exports into LanceDB
  81. python scripts/query_memory.py --index ./docs --category knowledge
  82. # Compact LanceDB fragments cleanly (safe while daemon is running!)
  83. python scripts/query_memory.py --compact
  84. # Run Dream Consolidation on project-local memory/inbox/*.md (zero API keys)
  85. python scripts/query_memory.py --dream
  86. # Opt-in flags for Antigravity transcripts or full history re-processing
  87. python scripts/query_memory.py --dream --include-global-transcripts --all-history
  88. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.