io.github.YonasValentin/mcp-memory-graph

Append text to the pinned core-memory block (newline-separated when non-empty). If the result would exceed char_limit the write is refused (error: core_memory_full) so you compact via core_memory_replace instead of silently overflowing.

Read the pinned "core memory" block for a (scope, namespace) — a small, bounded, always-in-context note the agent maintains about who it is and what matters now. Returns content, char_limit, and used (character count).

Replace the first occurrence of old_text with new_text in the pinned core-memory block. Returns error: not_found if old_text is absent, or core_memory_full if the result would exceed char_limit. Use this to update or compact the block.

Multi-agent / team attribution rollup. Returns how many currently-valid top-level memories each agent (agent_id, set at store time) wrote — { by_agent, by_author, total } — distinct from author (the human/source). Memories stored without an agent_id are bucketed under "unattributed". Optional scope/namespace filters scope the rollup.

Export the memory graph as a JSON Canvas 1.0 .canvas — opens as a spatial board in real Obsidian. Each currently-valid top-level memory becomes a text node on a deterministic grid; memory_links become labeled, arrow-tipped edges. Optionally filter by scope/namespace and cap with limit. When vault_path is given the canvas is written there (confined under the vault) and its path returned; otherwise only the canvas object.

GraphRAG global sensemaking (agent-driven, no LLM in the server). Detects communities (densely-connected entity clusters) over the entity graph on demand via weighted label propagation, and returns each community's top entities + linked memories. This is the corpus-level view that chunk-level search can't give — synthesize named themes from the communities to answer "what are the main themes?".

Apply agent-generated summaries to condense old memories. Preserves original content for later restoration. Use after consolidation reports flag condensation candidates.

Run the "dream cycle": find and merge near-duplicate memories, prune expired/low-quality entries, and update quality scores based on access patterns. Use dry_run=true to preview changes.

Delete memories by ID or by filter criteria (scope, department, before_date, expired_only). Provide at least one of id or filter.

Adaptive per-user expertise profile. action=observe records demonstrated knowledge of a topic (level rises on a saturating curve, never collapses other topics); action=get returns the profile. The agent supplies the classified topic — the server just tracks evidence over time.

Export memories as JSON for backup or migration. Supports filtering by scope, namespace, and department. Max 1000 records per export.

Export high-signal rows (auto-extracted learnings + agent reflections) as instruction→output training pairs (pairs/chatml/alpaca) for a project LoRA/distillation flywheel. Read-only, quality-filtered by importance/confidence. Training stays out of the repo — this only emits the JSONL.

Write memories OUT to an Obsidian vault as .md files with YAML frontmatter — the reverse of vault_sync. Each currently-valid top-level memory becomes a plain markdown file a human can open and edit; namespaced memories land under <vault>/<namespace>/. Lossless: written files parse back via the vault parser. Optionally filter by scope/namespace.

Store LLM-extracted entities and relationships for a memory. The calling agent should analyze memory content and provide structured entity/relationship data. This enables knowledge graph queries.

Extract decisions, patterns, error fixes, and conventions from a session transcript using heuristic analysis. Deduplicates against existing memories and optionally auto-stores.

GDPR-grade forget (additive — does NOT replace memory_delete). hard:false (default) soft-deletes/tombstones: stamps valid_to so the memory is excluded from default retrieval but stays queryable via as_of and is recoverable. hard:true erases for real: returns a portability "export" copy FIRST (data-subject access), THEN permanently deletes (irreversible, cascades). Returns { forgotten, mode, recoverable, export? }.

Retrieve a specific memory by its ID. Optionally include child chunks for ingested documents.

Query the knowledge graph: find entities, their relationships, and linked memories. Use entity name to start traversal, or browse all entities by type. Supports multi-hop traversal (depth 1-3).

Store health report: live/retired/stale counts, aging buckets, unresolved conflicts, and webhook delivery health, rolled up to a single ok|attention status with reasons. Read-only; optionally scoped.

Point-in-time history surface for one memory: its current bi-temporal timeline (created_at/updated_at/valid_from/valid_to/tx_expired/superseded_at/version) plus the full memory_versions edit history. Returns { memory_id, exists, timeline, versions } or { memory_id, exists:false }.

Import memories from JSON. Each item is embedded and stored. Use overwrite=true to update existing memories by ID.

Ingest a full document: automatically chunks it based on content type (text, markdown, code, legal), embeds each chunk, and stores with provenance. Use this for large documents.

Active advisor digest: what in the store needs ATTENTION now — unresolved conflicts, memories flagged stale by change-propagation, most-contradicted facts, and decisions recorded with no supporting evidence. Complements memory_questions (what to capture next). Read-only; optionally scoped.

Capture a structured lesson or incident in one call: fills the matching section template (incident → Symptom/Root Cause/Fix/Prevention; lesson → What/Why it matters/How to apply) from your field values and stores it through the normal write path (deduped — a repeat capture is a NOOP). Unknown document_types use a generic scaffold.

Find BROKEN [[wikilinks]] — the inverse of memory_unlinked_mentions. Reports (1) unresolved: a [[Title]] in a memory's content that matches no LIVE memory title in the same scope/namespace; (2) dangling_edges: stored wikilink edges whose target memory was deleted or superseded. Resolution is by TITLE (memories have no slug) so write [[Exact Title]]. Pass an id to check one memory, or scope/namespace to sweep a partition. Read-only.

Browse memories with filtering and pagination. Supports sorting by creation date, update date, or title.

Get a lightweight index of all memories — titles, types, tags, and scores without content. Use this to discover what knowledge exists before running expensive searches.

Answer a question with a TIGHT, relevant subgraph instead of flooding context. Seeds from hybrid search, walks the memory graph (hub-avoiding) up to max_hops, and returns a token-budgeted "context" string plus structured nodes — with an actionable hint when truncated.

Structured query over memory PROPERTIES (the agent's "Bases/Dataview"): filter currently-valid, top-level memories by scope/namespace/department/document_type/language/tags (AND)/min_importance/created_at range, sort by created_at|updated_at|importance_score|title, paginate, and project specific fields. Exact, deterministic retrieval that complements fuzzy memory_search — use it for "all decision memories in namespace=acme with importance>0.7, newest first".

Active "questions to ask" digest. Surfaces open questions / gaps the graph is uniquely positioned to find so you know what to verify or learn next: AMBIGUOUS inferred links to confirm (verify), frequently-mentioned but barely-documented entities (gap), and disconnected memories that may be stale or mis-scoped (orphan). Returns { questions: [{ question, type, evidence }], count } over currently-valid top-level memories. Optional scope/namespace filters and limit (default 20).

Generative-Agents-style reflection (agent-driven, no LLM in the server). mode:"gather" (default) returns the most reflection-worthy memories (high importance × recent) as material plus an instruction to synthesize 1–3 higher-level insights. mode:"store" persists a synthesized insight (provenance="reflection") and "derived_from"-links it to its source memories.

Find memories semantically related to a given memory ID. Uses vector similarity to discover connections.

Bring a memory back: un-tombstones a soft-forgotten memory (memory_forget {hard:false}) by clearing valid_to/tx_expired so it re-enters default recall, AND/OR restores a condensed memory to its original full content. Both are applied when both apply. Returns reinstated/uncondensed flags.

Change-propagation surface. action=list: memories flagged needs_revalidation (a source they were derived from changed). action=preview: the blast radius of a change to `id` (which dependents WOULD be flagged) without mutating anything. action=confirm: clear `id`'s stale flag after re-verifying it.

Search memories using hybrid vector+keyword search. Finds semantically similar content and exact keyword matches, with optional filters for scope, department, tags, date range, and temporal decay.

Frictionless per-session capture ("daily note for agents"). Keyed by source "session:<session_id>": the first call creates one session memory (document_type "session"); every later call for the same session_id appends to that same memory (newline-joined, re-embedded and versioned). Different session_ids stay isolated. Returns { memory_id, created, appended }.

Save or resume a resumable session-state ("where was I"): structured summary/next_steps/open_questions/files_touched/branch keyed by session_key. save upserts (versioned, so you can diff sessions via memory_version_diff); resume returns the latest. Bypasses the dedup write-gate so an incremental save always persists.

Get usage statistics: total memories, chunks, documents, breakdowns by scope/department/type, storage size, and expired count.

Store a new memory with content, metadata, and automatic vector embedding. Use this to save information, decisions, patterns, or knowledge for later semantic retrieval.

Fetch an Obsidian-style note scaffold for a document_type so stored memories stay structurally consistent. Returns a markdown template with ## Section headers (e.g., decision → Context/Decision/Consequences; incident → Symptom/Root Cause/Fix/Prevention; also learning, bug-fix, meeting, session). Unknown types get a generic Summary/Details/Notes scaffold (known:false). Read-only: fill the scaffold, then store it via memory_store.

Show the MemGPT-style tier distribution (hot / recall / archival) of currently-valid, top-level memories and list the hot working set. Tiers are derived from access recency + frequency — hot = frequently or recently accessed, archival = old and rarely touched, recall = everything in between. Read-only; optional scope/namespace filter.

Surface "unlinked mentions" for a memory — other memories that are semantically related (vector-near + shared entities) but that you have NOT explicitly linked yet. This is Obsidian's killer feature, automated: instead of matching note titles as literal text, it uses embeddings + the entity graph to propose latent connections the agent never made. Auto "similar_to" suggestions are surfaced; existing wikilink/co-occurrence/typed links are excluded. Use it to discover and then confirm real connections (e.g. via memory_extract_entities or a stored link).

Update an existing memory. If content changes, the vector embedding is automatically regenerated. Previous versions are preserved in history.

Verify the signed provenance envelope of memories: recomputes each content_hash and ed25519-checks the signature against THIS machine's trusted signing key (not the row's self-embedded key). Verify one by id, or a batch by scope/namespace. Returns per-memory status (verified / unsigned / tampered / untrusted) + a summary {verified, unsigned, tampered, untrusted}. "untrusted" = validly signed but by a non-trust-root key (e.g. a teammate on a synced vault) — distinct from "tampered". Read-only. Signing is enabled by MCP_SIGN_MEMORIES.

Show a line-by-line diff between two revisions of a memory (Obsidian-Sync-grade trust). `to` defaults to the current version. Use it to audit exactly what an edit changed — added/removed lines plus a summary count.

Roll a memory back to a prior version's content. The restore is itself a versioned, re-embedded edit (the pre-restore state is snapshotted, the vault file re-mirrored) — never a destructive overwrite. Returns the restored memory.

View the version history of a memory, showing all past edits with timestamps and who made each change.

Manage the active-infrastructure event bus (gated on MCP_WEBHOOKS). register an outbound webhook target (URL is SSRF-validated — public http(s) only), list targets (secrets never returned), delete a target, or dispatch the durable delivery queue now. Mutations to memories (created/updated/superseded/deleted/forgotten) enqueue HMAC-signed deliveries that this tool drains with retry + circuit-breaker + dead-letter.

Search memories via hybrid vector+keyword search, scoped to a namespace. Defaults the namespace to the vault folder name; pass an explicit `namespace` to search memories that live under a different namespace (e.g. after memory_export_vault).

Check the sync status of an Obsidian vault: total files, synced/pending/changed counts, last sync time, and memory count.