mcp-light-memory

Was ist das?

MCP Light Memory ist ein leichtgewichtiges, lokal-first, persistentes Speichersystem für Coding-Agenten und MCP-Clients (Warp, OpenCode, JetBrains AI Assistant / PyCharm, Claude Code, Cursor). Es fungiert als Checkpoint- + Abrufschicht – es speichert den minimalen dauerhaften Zustand, der nötig ist, um komplexe Arbeit über Sitzungen hinweg fortzusetzen, ohne die vollständige Konversation im Kontextfenster des Modells zu behalten.

Wenn Ihr Agent eine Aufgabe startet, ruft er context auf und erhält relevante frühere Entscheidungen, Stolperfallen, Einschränkungen und Hypothesen zurück – sortiert, dedupliziert und vertrauensbegrenzt. Wenn er fertig ist, speichert er den Arbeitszustand als Checkpoint. In der nächsten Sitzung, selbst nach einem Neustart, ist der Speicher da.

Related MCP server: M3 Memory

Warum verwenden?

So funktioniert es (Mechanismen)

• Markdown ist die Quelle der Wahrheit. Jede Erinnerung ist eine .md-Datei mit YAML-Frontmatter (id, type, status, tags, sources, links, valid_from, valid_to, supersedes). Menschenlesbar, diffbar, dauerhaft.

• SQLite ist ein neu aufbaubarer Cache. BM25/FTS5-Index + optionale Embedding-Vektoren + Nutzungsverfolgung. Löschen Sie ihn und alles wird aus Markdown neu aufgebaut.

• Abruf: reines Python-BM25 + optionale dichte Embeddings → RRF-Fusion → MMR-Diversifizierung → Policy-Boosts (Typ/Status/zeitlich) → Token-Budget-Schnitt. Adaptiver Modus: zuerst sparse, dicht nur bei schwachen Ergebnissen.

• Lebenszyklus: remember → update → supersede (verlinkt in beide Richtungen, löscht nie Verlauf) → forget (archiviert, löscht nie) → timeline (zeitliche Ansicht). search --at YYYY-MM-DD für historische Abfragen.

• Vertrauensgrenze: abgerufener Inhalt ist in === BEGIN/END INTERNAL_RAG MEMORY === mit einem SECURITY NOTICE-Header eingebettet. Strukturiertes JSON/MCP trägt trust: untrusted + optional security_flags: ["instruction_like_content"].

• Evidenz-Frische: jedes Ergebnis enthält evidence_state (present/missing/unverifiable) für lokale pfadartige Evidenz – zur Abrufzeit abgeleitet, nie persistiert.

• Multi-Projekt-Router: ein MCP-stdio-Server vor vielen Projekten über eine JSON-Registry. write:false blockiert mutierende Tools, bevor ein Kindprozess gestartet wird. Subprozess-Isolation pro Aufruf (kein gemeinsamer Zustand).

Einrichtung

Voraussetzungen

• Python 3.8+ (verwendet den py-Launcher, python oder python3 – der Installer erkennt automatisch den echten Interpreter und lehnt den WindowsApps-Stub ab)

• Git (das Zielprojekt muss ein Git-Repository sein)

• Optional: pip install sentence-transformers numpy für besseres semantisches Abrufen

Die aktuelle Version wird durch die VERSION-Datei definiert – prüfen Sie diese (oder führen Sie mlm.py --version aus), anstatt eine erwartete Nummer fest zu kodieren.

Schnellstart

Klonen Sie dieses Repository einmal und installieren Sie es dann in ein beliebiges Projekt:

# Windows (PowerShell)
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python ~/mcp-light-memory/install.py . --client warp

# Linux/macOS
git clone https://github.com/PeterPirog/mcp-light-memory.git ~/mcp-light-memory
python3 ~/mcp-light-memory/install.py . --client warp

Der Installer:

• kopiert Skill-Dateien + erstellt INTERNAL_RAG/ + AGENTS.md

• führt init + checkpoint + validate aus (damit guard sofort OK ist)

• registriert den MCP-Server automatisch in der Client-Konfiguration, wenn dies sicher möglich ist (oder meldet MANUAL_REQUIRED / gibt JetBrains-Anweisungen aus)

• schreibt den absoluten Pfad zum verifizierten Python-Interpreter (übersteht Windows-PATH-Probleme)

python .agents\skills\internal-rag\mlm.py --version   # reports the installed version
python .agents\skills\internal-rag\mlm.py status       # expect: INTERNAL_RAG ready
python .agents\skills\internal-rag\mlm.py guard        # expect: GUARD OK

Installationsmatrix

Ein Installer, vier Clients, zwei Konfigurationsbereiche. Vollständige Anleitung: docs/INSTALLATION.md.

• --global ändert den Bereich der CLIENT-KONFIGURATION (~/.warp/.mcp.json vs. {repo}/.warp/.mcp.json, ~/.config/opencode/opencode.json vs. Projekt-opencode.json). Der Server zeigt weiterhin auf das Zielprojekt, in das Sie installiert haben.

• Benötigen Sie einen globalen MCP-Endpunkt für viele Repositories? Verwenden Sie den Multi-Projekt-Router – docs/MCP-MULTI-PROJECT.md.

• JetBrains/PyCharm wird unterstützt, nicht vollautomatisch: Der Installer bereitet das JSON + das Arbeitsverzeichnis vor; Sie fügen den Server unter Settings → Tools → AI Assistant → MCP hinzu und wählen Server level = Project oder Global.

• Manuelle Einrichtung (ohne Installer) pro Client: docs/INSTALLATION.md + Client-Seiten (Warp · OpenCode).

Zero-Shot: Copy-Paste-Prompts für Warp und OpenCode

Sie können einen dieser Prompts direkt in den Client-Agenten einfügen. Ersetzen Sie C:\Projects\App durch den tatsächlichen Ziel-Repository-Pfad.

Warp – Installation für ein Projekt:

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in Warp, using project scope. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, update it with git pull --ff-only. Apply the canonical installation contract from the repository and run install.py with TARGET_PROJECT=C:\Projects\App and --client warp without --global. Do not force-overwrite an existing configuration. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification. If Warp requires an additional project activation/toggle/approval, state the exact client-side step and do not claim the server is active before it is completed.

Warp – globale Client-Konfiguration für ein Projekt:

Install and configure MCP Light Memory (mcp-light-memory) in Warp globally for project C:\Projects\App. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Apply the canonical installation contract and run install.py with TARGET_PROJECT=C:\Projects\App, --client warp, and --global. Remember: --global means the global Warp client configuration, while the server must still be bound to C:\Projects\App; do not use the multi-project router. After installation, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global Warp configuration contains mcp-light-memory and the C:\Projects\App path. Report success only after MCP REGISTRATION: REGISTERED and successful verification.

OpenCode – Installation für ein Projekt (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) as an MCP server for project C:\Projects\App in OpenCode. By "OpenCode" I mean stable/V1, so use --client opencode, not opencode2. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App and --client opencode without --global. Do not force-overwrite an existing configuration. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED (for example because opencode.jsonc exists), do not report success: safely edit the JSONC while preserving comments and unrelated settings if you have appropriate file-editing tools; otherwise report the exact manual action required. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the OpenCode configuration contains mcp-light-memory and C:\Projects\App.

OpenCode – globale Client-Konfiguration für ein Projekt (stable/V1):

Install and configure MCP Light Memory (mcp-light-memory) globally in OpenCode for project C:\Projects\App. By "OpenCode" I mean stable/V1, so use --client opencode. Use the repository https://github.com/PeterPirog/mcp-light-memory. If the tool is not cloned yet, clone it to a stable location outside the project; if it already exists, run git pull --ff-only. Run install.py with TARGET_PROJECT=C:\Projects\App, --client opencode, and --global. --global means the global OpenCode client configuration, while the server must still be bound only to C:\Projects\App; do not use the multi-project router. If the installer returns MCP REGISTRATION: MANUAL_REQUIRED, do not report success and follow the safe JSONC instructions. After real registration, verify from cwd=C:\Projects\App: mlm.py --version, mlm.py status, and mlm.py guard, and confirm that the global OpenCode configuration contains mcp-light-memory and the C:\Projects\App path.

Für OpenCode 2 / V2 verwenden Sie dieselben Prompts, geben aber explizit OpenCode 2 / V2 an und verlangen --client opencode2. Weitere Varianten: docs/ZERO-SHOT-SETUP-PROMPTS.md.

Konfigurationsdetails

Warp

Warp liest MCP-Serverkonfigurationen aus ~/.warp/.mcp.json (global, automatischer Start) oder {repo}/.warp/.mcp.json (Projekt, erfordert einen manuellen Schalter gemäß Warp-Dokumentation). Form: mcpServers.<name> mit command, args, working_directory (immer setzen – der Speicher wird daraus aufgelöst). Siehe examples/warp.example.json und docs/WARP-SETUP.md.

OpenCode stable (V1)

OpenCode liest opencode.json/.jsonc im Projektstamm oder ~/.config/opencode/opencode.json global. V1-Server sind flach unter mcp.<name> (kein servers-Unterschlüssel) mit enabled: true und command als Array – siehe examples/opencode-legacy.example.json und docs/OPENCODE.md.

OpenCode 2 (V2, Beta)

Dieselben Konfigurationsdateien, andere Form: mcp.servers.<name>, command als Array und kein enabled-Feld (V2 deaktiviert über disabled: true) – siehe examples/opencode-v2.example.jsonc und docs/OPENCODE.md.

JetBrains AI Assistant / PyCharm

PyCharm liest KEINE MCP-Konfigurationsdatei automatisch. Der Installer gibt einsatzbereites JSON + Arbeitsverzeichnis aus; Sie fügen den Server unter Settings → Tools → AI Assistant → MCP (STDIO) hinzu und wählen Server level = Project oder Global. Siehe examples/jetbrains.example.json.

Multi-Projekt-Router

Eine MCP-Verbindung vor vielen Projekten – Registry-Allowlist, write:false-harte Grenze, Subprozess-Isolation pro Aufruf.

Registry-Datei (projects.json)

{
  "projects": {
    "backend": { "root": "/abs/path/backend", "write": true },
    "shared-lib": { "root": "/abs/path/shared-lib", "write": false }
  }
}

Warp-Konfiguration für den Router

{
  "mcpServers": {
    "mcp-light-memory-router": {
      "command": "python3",
      "args": ["/abs/path/mcp-light-memory/.agents/skills/internal-rag/irag_mcp_router.py", "--registry", "/abs/path/projects.json"],
      "working_directory": "/abs/path/mcp-light-memory"
    }
  }
}

Siehe docs/MCP-MULTI-PROJECT.md für Details.

Arbeitsablauf

context --task "current task"
  ↓
recovery, if required (RECOVERY REQUIRED)
  ↓
checkpoint before first change
  ↓
implementation
  ↓
checkpoint after each milestone
  ↓
guard before finishing

Kernbefehle (CLI-Alias: mlm.py oder Legacy irag.py):

mlm.py context --task "..."
mlm.py checkpoint --reason "..."
mlm.py search --query "..." --limit 8
mlm.py remember --type decision --title "..." --body "..."
mlm.py show <ref>
mlm.py update <ref> --status superseded
mlm.py status
mlm.py guard
mlm.py validate
mlm.py doctor

Pfadzuordnung (Rebranding: internal-rag → MCP Light Memory)

Der On-Disk-Ordner INTERNAL_RAG/ und das Skill-Verzeichnis .agents/skills/internal-rag/ werden absichtlich unter ihren Legacy-Namen für Null-Migrations-Rückwärtskompatibilität beibehalten. Siehe docs/MIGRATION-TO-MCP-LIGHT-MEMORY.md.

Dauerhafter Speicher (CRUD)

remember --type decision --title "..." --body "..." --tags "a,b" --evidence "src/x.py:42" --links "decisions/other.md"
show <path-or-id>
show <ref> --section Knowledge
update <ref> --add-tags "new" --append "New evidence: ..."
supersede <ref> --by <new> --reason "..."
forget <ref>              # archives, does not delete
link --from <ref> --to <ref>
timeline --limit 20
status
history

Typen: decision, knowledge, constraint, gotcha, failure, hypothesis, session.

Aufgabenstapel (Unterbrechungen)

mlm.py push --task "interrupted work" --reason "user-priority"
mlm.py tasks
mlm.py resume
mlm.py forget-task <id>   # drop a specific task
mlm.py forget-task         # clear the whole stack

Konfiguration (.irag.yml, optional)

retrieval:
  limit: 10
  mmr_lambda: 0.4
  min_score: 0.3
  embeddings: auto        # auto | on | off
  profile: english-fast   # english-fast (default) | multilingual (PL/EN projects)
  embeddings_model: null  # explicit model overrides the profile
tokens:
  context_budget: 5000
checkpoints:
  auto_archive_sessions: true
  max_task_stack: 24

mlm.py config zeigt die effektive Konfiguration. mlm.py config --init schreibt eine Vorlage.

Optionale Embeddings (besseres Abrufen)

pip install -r requirements-optional.txt

Wenn das Paket verfügbar ist und .irag.yml embeddings: auto (Standard) enthält, verwendet das Abrufen Embeddings mit Fallback auf BM25. Zur Laufzeit mit --embeddings on|off|auto überschreiben.

Zwei Abrufprofile (siehe docs/EMBEDDINGS.md):

• english-fast (Standard, all-MiniLM-L6-v2)

• multilingual (intfloat/multilingual-e5-small) – für Polnisch-Englisch-Projekte

Offline / Air-Gapped

python pack.py --with-embeddings --profile english-fast
# -> internal-rag-offline-1.8.1.zip   (name from pack.py; 1.8.1 = VERSION file)
# On the air-gapped machine:
unzip internal-rag-offline-*.zip -d internal-rag-offline
pip install --no-index --find-links wheels/ -r requirements-optional.txt
python install.py "/path/to/project" --client <warp|opencode|opencode2|jetbrains>

Siehe docs/OFFLINE.md für Details.

Datenschutz & Git

Der Standard-Installationsmodus ist nur lokal. Der Installer verwendet .git/info/exclude, nicht die .gitignore des Projekts, damit lokale Speicher- und Integrationsdateien nicht versehentlich committet werden.

Vor der Veröffentlichung eines Projekts:

python .\privacy_check.py "D:\path\to\project"

Erwartet: RESULT: PASS

Vollständige Entfernung aus einem Projekt

python .\uninstall.py "D:\path\to\project"

Das Deinstallationsprogramm erstellt ein Backup außerhalb des Repositorys und entfernt dann INTERNAL_RAG und seine Integrationen. Verwenden Sie --keep-memory, um die Memory-Daten zu erhalten.

Dokumentation

• Installation · Tägliche Nutzung · CLI-Referenz

• Architektur · Memory-Lebenszyklus · Wiederherstellung

• MCP · Multi-Projekt-MCP

• Architekturentscheidungen (ADR) · Konfiguration

• Embeddings · Offline · Git-Hooks

• Datenschutz & Git · Deinstallation · Fehlerbehebung

• Zero-Shot-Einrichtungsprompts · Migration · Branding

Struktur in einem Zielprojekt

project/
├── AGENTS.md
├── .irag.yml                    # optional config
├── INTERNAL_RAG/
│   ├── WORKING_STATE.md
│   ├── INDEX.md
│   ├── .checkpoint.json
│   ├── decisions/  knowledge/  gotchas/  failures/  hypotheses/  sessions/  archive/
│   └── exports/
├── .agents/skills/internal-rag/
│   ├── SKILL.md
│   ├── mlm.py                   # primary CLI (forwards to irag.py)
│   ├── irag.py                  # core (legacy alias, still the canonical module)
│   ├── irag_embeddings.py       # optional plugin
│   └── irag_hooks.py            # optional git hooks
└── .opencode/                   # OpenCode integration (optional)

Wahrheitsquelle

1. aktuelle Benutzeranweisungen, 2. aktueller Code/Tests/Konfiguration, 3. Spezifikationen/ADRs, 4. verifiziertes Memory, 5. Sitzungsnotizen, 6. Hypothesen.

Memory kann veraltet sein. Code hat Vorrang.

Lizenz

MIT.

Änderungshistorie

1.8.0 — Manuelle Einrichtung für JetBrains

• --client jetbrains schreibt keine Dummy-Konfigurationsdatei mehr (PyCharm ignoriert MCP-Konfigurationsdateien). Stattdessen werden JSON zum direkten Einfügen und IDE-Menüanweisungen ausgegeben.

• --unregister --client jetbrains gibt einen Hinweis aus, die Entfernung in der IDE-Benutzeroberfläche vorzunehmen.

1.7.2 — JetBrains cwd + clientspezifische Meldungen

• JetBrains: schreibt working_directory als Hinweis + gibt WARNING mit dem genauen Pfad aus, der in Settings → Tools → AI Assistant → MCP festzulegen ist.

• Clientspezifische Neustartmeldungen (PyCharm neu starten / Warp neu starten / OpenCode neu starten).

• Memory store: <path> wird in der Installationsausgabe ausgegeben.

1.7.1 — Windows-Python-Stub-Fix

• detect_python() lehnt den 0-Byte-Stub von WindowsApps ab; bevorzugt py -0p; überprüft jeden Kandidaten mit --version.

• Verifizierung nach der Registrierung: führt --version unmittelbar nach dem Schreiben der Konfiguration aus und meldet PASS/FAIL.

• --unregister löscht leere Konfigurationsdateien + übergeordnete Verzeichnisse (behebt das tote .warp/.mcp.json-Skelett → GUARD STALE).

1.7.0 — Rebranding zu MCP Light Memory

• Komplettes Rebranding von internal-rag zu MCP Light Memory (mcp-light-memory). Neuer CLI-Alias mlm (mlm.py). Logo-/Icon-Assets. Migrationsdokument. GitHub-Rebranding-Checkliste.

• Abwärtskompatibel: irag.py, INTERNAL_RAG/, alte MCP-Servernamen bleiben als veraltete Aliase erhalten.

• 18 Rebranding-Konsistenztests.

1.6.1 — Härtung nach v1.6

• Mutations-/Lebenszyklus-Benchmark (11 Szenarien). Vertrauensgrenze (ADR-015): trust: untrusted + security_flags. Aktualität der Belege (ADR-016): evidence_state. Skalen-Benchmark (100/1k/10k). Router-Sicherheitsregressionen (+12 Tests). Dokumentations-Konsistenztest. 249 Tests bestehen.

1.6.0 — Retrieval-Qualität + MCP 2026-07-28

• Memory-Qualitäts-Benchmark (37 Fälle). MCP 2026-07-28 Dual-Era (server/discover, _meta, structuredContent, outputSchema). Registry: striktes write. Quellen im Chunk-Präfix. Adaptives Retrieval. Link-bewusster Kontext. consolidate --prepare. Router-Latenz-Benchmark. ADR-010…016.

1.5.0 — Abstention-Gate + Multi-Projekt-Router

• Relevanz-/Abstention-Gate (--meta). FTS5-Kandidaten-Vorfilter. Multi-Projekt-MCP-Router. MCP-Protokoll-Härtung (reines stdout, SDK-verifiziert). 168 Tests.

1.4.0 — Chunking + Deduplizierung + temporaler Lebenszyklus

• Abschnittsbewusstes Chunking (Schema v3). SimHash-Deduplizierung. Mehrsprachiges PL/EN-Profil. Temporaler Lebenszyklus (valid_from/valid_to/supersedes/--at). consolidate --dry-run.

1.3.0 — Persistenter Embedding-Cache

• Float32-BLOBs auf Chunk-Ebene in SQLite. Mehrere Modelle koexistieren. index --vacuum/--embed-missing.

1.0.2 — Token-Budget + Datenschutz

• Durchsetzung des Token-Budgets. Erkennung veralteter Memory-Daten. Duplikaterkennung. Datenschutz-Scan beim Schreiben. Auto-Checkpoint-Timer. Offline-/Air-Gapped-Paket.

1.0.0 — Erstveröffentlichung

• BM25 + MMR-Retrieval. Vollständige Memory-CRUD. Task-Stack. MCP-Server (JSON-RPC stdio). Git-Hooks. Diagnostik. Export/Import. Token-Budget.