MCP-Memory: Een op OKF gebaseerde geheugenserver voor AI-agenten

Geheugenrecords worden geformatteerd volgens de Open Knowledge Format (OKF v0.2) standaard en geïndexeerd met een lokale SQLite-instantie (met ondersteuning voor FTS5 full-text search). Dit zorgt voor snelle key-value lookups, filtering op tags en inhoudelijke zoekopdrachten.

Belangrijkste kenmerken

• Persistente status over sessies heen: Stelt AI-agenten in staat om stateful geheugenfragmenten te lezen, op te slaan, te zoeken en te verwijderen die behouden blijven over verschillende chatbeurten en sessies.
• Naleving van de OKF-standaard: Elk geheugenitem wordt opgeslagen als een OKF v0.2 Markdown-document met YAML frontmatter (type, key, namespace, tags, generated, sources, verified, status, staleafter), strikt volgens SPEC.md en OKFRULES.md.
• Twee-laags architectuur:
• Menselijk doorzoekbare OKF-directory: Sychroniseert automatisch elk geheugen naar schijf als een raw .md bestand in de memory/ bundle directory, inclusief hiërarchische index.md bestanden voor progressieve onthulling (root index.md versie okf_version: "0.2") en een log.md voor het bijhouden van de updatehistorie.
• Hoogwaardige SQLite-indexering: Maakt gebruik van SQLite FTS5 (Full-Text Search) en automatische triggers voor key-lookups in minder dan 20ms en onmiddellijke trefwoordzoekopdrachten.
• Namespace Isolatie: Ondersteunt contextuele scheiding (bijv. user/preferences, project/architecture, default).
• Opstelling zonder boilerplate: Een snelle setup-wizard (python3 setup.py) configureert automatisch de geïnstalleerde MCP-tools (Antigravity, Claude, Cursor, Windsurf, Codex).

MCP Tools

De server stelt vier primaire MCP-tools beschikbaar voor interagerende agenten:

1. memory_store

Slaat een geheugenrecord op of werkt dit bij in OKF v0.2 formaat.

Parameters:

• key (string, verplicht): Unieke identifier of pad voor het geheugen (bijv. user/preferences/coding_style of project/architecture).
• content (string of object, verplicht): De kerninformatie die moet worden opgeslagen.
• project_root (string, verplicht): Absoluut pad naar de actieve projectroot-directory (bijv. /Users/user/Projects/my-app).
• tags (array van strings, optioneel): Classificatietags voor filtering.
• namespace (string, optioneel, standaard: "default"): Scope/namespace.
• concept_type (string, optioneel, standaard: "Agent Memory"): OKF concept type (bijv. Metric, Playbook, Attested Computation).
• title (string, optioneel): Weergavenaam.
• description (string, optioneel): Samenvatting in één regel.
• resource (string, optioneel): Canonieke URI van het onderliggende asset.
• status (string, optioneel, standaard: "stable"): Lifecycle-status (draft | stable | deprecated).
• stale_after (string, optioneel): ISO-datum (YYYY-MM-DD).
• sources (array van objecten, optioneel): Herkomstbronnen [{resource, id, title, author, usagecount, lastmodified}].
• verified (array van objecten of object, optioneel): Verificatiegebeurtenissen [{by, at}].
• generated_by (string, optioneel): Identifier van de actor volgens de actor-conventie (<producer>/<version>, human:<id>, process:<id>).

2. memory_retrieve

Haalt een specifiek geheugen op aan de hand van de key en namespace.

Parameters:

• key (string, verplicht): De geheugensleutel die moet worden opgezocht.
• project_root (string, verplicht): Absoluut pad naar de actieve projectroot-directory.
• namespace (string, optioneel, standaard: "default"): Scope/namespace.

3. memory_search

Zoekt naar geheugenrecords die overeenkomen met trefwoorden, tags of namespace-filters.

Parameters:

• project_root (string, verplicht): Absoluut pad naar de actieve projectroot-directory.
• query (string, optioneel): Zoekopdracht op basis van trefwoorden in keys, frontmatter en inhoud.
• tags (array van strings, optioneel): Filteren op specifieke tags.
• namespace (string, optioneel): De zoekopdracht beperken tot een namespace.
• limit (integer, optioneel, standaard: 10): Maximaal aantal resultaten.

4. memorygetlast

AGENT DIRECTIVE (Sessie start): Haalt het laatst geregistreerde sessie-checkpoint op (system/last_memory), zodat de AI-agent direct weet waar het werk is gebleven bij het openen van een project of het starten van een sessie.

Parameters:

• project_root (string, verplicht): Absoluut pad naar de actieve projectroot-directory.
• namespace (string, optioneel, standaard: "default"): Scope/namespace.

5. memoryupdatelast

AGENT DIRECTIVE (Mijlpalen & Voortgang): Werkt het canonieke sessie-checkpoint (system/last_memory) bij telkens wanneer een mijlpaal is bereikt, belangrijke wijzigingen zijn doorgevoerd of het werk wordt gepauzeerd.

Parameters:

• content (string of object, verplicht): Een korte notitie of gestructureerd dictionary dat de voortgang samenvat en verwijst naar belangrijke geheugenbestanden.
• project_root (string, verplicht): Absoluut pad naar de actieve projectroot-directory.
• namespace (string, optioneel, standaard: "default"): Scope/namespace.
• summary (string, optioneel): Beschrijving van de behaalde mijlpaal in één zin.

OKF (Open Knowledge Format) Structuur

Elk opgeslagen geheugen voldoet strikt aan de OKF v0.2 specificatie (SPEC.md & OKF_RULES.md):

---
type: Agent Memory
title: Coding Style
key: user/preferences/coding_style
namespace: default
tags:
- preferences
- style
status: stable
generated:
  by: mcp-memory/0.2.0
  at: '2026-08-12T19:23:35Z'
created_at: '2026-08-12T19:23:35Z'
updated_at: '2026-08-12T19:23:35Z'
---
User prefers functional programming style with explicit type annotations.

Snelstart

1. Clone de repository

git clone https://github.com/fellowgeek/mcp-memory
cd mcp-memory

2. Interactieve Setup Wizard

Voer setup.py uit om mcp-memory automatisch te detecteren en te registreren bij je AI-tools:

python3 setup.py

Let op: Zodra setup.py de configuratie heeft voltooid, zal je AI-client mcp-memory automatisch op de achtergrond starten wanneer dat nodig is. Je hoeft geen serverproces handmatig in je terminal open te houden.

3. Handmatig uitvoeren via CLI (Optioneel / Debugging)

Als je de opstartprocedure handmatig wilt verifiëren, de stdio-output wilt inspecteren of de virtuele omgeving (.venv) wilt initialiseren, kun je run.sh direct uitvoeren:

./run.sh

Handmatige Client Configuraties

Als je de MCP-client liever handmatig configureert, voeg dan de "memory" server-entry toe die verwijst naar run.sh.

JSON Configuratie (Antigravity, Claude Desktop, Cursor, Windsurf)

Voeg dit toe aan de mcpconfig.json of claudedesktop_config.json van je client:

{
  "mcpServers": {
    "memory": {
      "command": "/ABSOLUUT/PAD/NAAR/run.sh"
    }
  }
}

TOML Configuratie (Codex Desktop)

Voeg dit toe aan ~/.codex/config.toml:

[mcp_servers.memory]
command = "/ABSOLUUT/PAD/NAAR/run.sh"

CLI Configuratie

Claude Code CLI:

claude mcp add --scope user memory -- /ABSOLUUT/PAD/NAAR/run.sh

Codex CLI:

codex mcp add memory -- /ABSOLUUT/PAD/NAAR/run.sh

Testen

Voer de geautomatiseerde testsuite uit om OKF-serialisatie, SQLite-databasebewerkingen en FastMCP-tooluitvoering te verifiëren:

python3 test_memory.py

Opslag & Omgevingsvariabelen

Standaard maakt mcp-memory project-geïsoleerde geheugenopslagen aan in de rootdirectory van elk project:

• OKF Markdown-bestanden (Menselijk leesbaar): De memory/ map in de projectroot.
• SQLite Database (Verborgen index): .mcp_memory/memories.db in de projectroot.

Je kunt dit gedrag aanpassen met behulp van omgevingsvariabelen:

• MCPMEMORYPROJECT_ROOT: Project root directory (standaard: huidige werkmap cwd).
• MCPMEMORYDBPATH: Pad naar het SQLite-databasebestand (standaard: .mcpmemory/memories.db relatief aan de projectroot).
• MCPMEMORYDIR: Directory voor Open Knowledge Format (OKF) .md bestanden (standaard: memory relatief aan de projectroot).

Tip: Als je liever één globale geheugenopslag gebruikt die over alle projecten wordt gedeeld, stel dan MCPMEMORYDBPATH=~/.mcpmemory/memories.db en MCPMEMORYDIR=~/.mcp_memory/memory in binnen de MCP-configuratie van je client.