memgraph v1.9.0 — cli-guide-spec discovery

Embedded agent guide

• memgraph guide emits the embedded cli-guide-spec JSON mental model
• memgraph guide --human renders the same guide as Markdown
• memgraph help-json exposes the complete machine-readable command catalog
• HTTP GET /guide serves the same envelope and GET /llms.txt provides an agent breadcrumb
• Discovery works offline/cold-start, including global flags before the command

Validated with go test ./..., go test -race ./..., go vet ./..., go build ./..., cold-start JSON/Markdown smoke, and invalid-argument exit checks.

v1.8.1 — Two-tier MCP tools (53% token reduction)

v1.8.1 — Two-tier MCP tools

Reduces MCP tool definition overhead by 53% while maintaining 100% CLI parity.

Before (v1.8.0): 23 tools, 2487 tokens per API call

Every CLI command was an individual MCP tool. The tool definitions were injected into every LLM call, costing ~2500 tokens.

After (v1.8.1): 9 tools, 1158 tokens per API call

8 core tools (agent uses these mid-task, ~966 tokens):

• memgraph_projects — discover projects
• memgraph_recall — search memories
• memgraph_read — read memory or section
• memgraph_save — store new memory
• memgraph_list — browse memories
• memgraph_edit — update memory
• memgraph_delete — remove memory
• memgraph_recommend — skill recommendations

1 admin meta-tool (~192 tokens):

• memgraph_admin — takes {command, args} and dispatches to 15 rare operations:
  status, config, profile, sessions, init, demo, import, attach, bridge, setup, feedback, query, related, plans, graph_from_dir

Impact

Metric	v1.8.0	v1.8.1	Change
Tools advertised	23	9	-61%
Tokens per API call	2487	1158	-53%
CLI operations covered	23	23	100%

All 23 operations are still accessible — the admin meta-tool just doesn't advertise each one individually in the tool list.

v1.8.0 — 100% CLI↔MCP parity

v1.8.0 — 100% CLI↔MCP parity

Every CLI command (except daemons: serve, watch, mcp) now has a corresponding MCP tool. Agents can do everything via MCP that they could via the CLI — no shelling out needed.

23 Tools (was 5)

Memory CRUD (9)

Tool	CLI equivalent
memgraph_recall	memgraph recall
memgraph_read	memgraph read
memgraph_save	memgraph remember
memgraph_list	memgraph list
memgraph_edit	memgraph edit
memgraph_delete	memgraph delete
memgraph_sessions	memgraph sessions
memgraph_import	memgraph import
memgraph_init	memgraph init

System / Discovery (9)

Tool	CLI equivalent
memgraph_projects	memgraph projects
memgraph_profile	memgraph profile
memgraph_status	memgraph status
memgraph_config	memgraph config
memgraph_attach	memgraph attach
memgraph_demo	memgraph demo
memgraph_bridge	memgraph bridge
memgraph_setup	memgraph setup
memgraph_feedback	memgraph feedback

Skill Graph (5)

Tool	CLI equivalent
memgraph_recommend	memgraph recommend
memgraph_query	memgraph query
memgraph_related	memgraph related
memgraph_plans	memgraph plans
memgraph_graph_from_dir	memgraph graph-from-dir

Excluded (daemons, not tools)

• serve — HTTP server, blocks forever
• watch — filesystem watcher daemon, blocks forever
• mcp — the MCP server itself

Code Organization

Refactored from one 509-LOC file into 4 focused files (all under 500 LOC):

• mcp_tools.go (264 LOC) — tool definitions + dispatch + helpers
• mcp_memory.go (491 LOC) — memory CRUD implementations
• mcp_system.go (349 LOC) — system/discovery implementations
• mcp_graph.go (250 LOC) — skill graph implementations

Stats

• 52 tests pass with -race
• Pure Go stdlib, zero external dependencies

v1.7.0 — stdio MCP server

v1.7.0 — stdio MCP server for automatic agent discovery

The Problem

Every agent integration was a text instruction in CLAUDE.md saying "run memgraph recall before starting a task." This was fragile — models may skip, misread, or forget the instruction. Each agent framework needed its own bridge file.

The Fix

memgraph mcp starts a stdio JSON-RPC 2.0 server implementing the MCP 2025-11-25 protocol. No external dependencies — pure Go stdlib.

5 Tools Exposed

Tool	What it does
memgraph_projects	List all project scopes (discovery — no prior knowledge needed)
memgraph_recall	Search memories (returns compact section index by default)
memgraph_read	Read full memory or specific section by slug
memgraph_save	Store new memory with [slug] sections
memgraph_recommend	Skill recommendations for a task

Register with Claude Code

claude mcp add memgraph -s user -- ~/.local/bin/memgraph mcp

Verified: claude mcp list shows memgraph ✔ Connected. All 5 tools discoverable via tools/list. Full end-to-end workflow tested through the protocol.

Protocol

• Transport: stdio (newline-delimited JSON-RPC 2.0)
• Handshake: initialize → notifications/initialized → tools/list → tools/call
• Protocol version: 2025-11-25
• Capabilities: tools (listChanged: false)
• Errors: JSON-RPC level (-32700, -32601, -32602) for protocol errors; isError: true for tool execution errors

Impact

• Eliminates CLAUDE.md rules: agents discover memgraph via MCP tool list
• Eliminates cold-start friction: framework advertises tools, model calls them
• Eliminates bridge files: no per-agent integration files needed
• Token-efficient by default: memgraph_recall returns section index, not full memories

Files

• mcp_server.go (164 LOC) — JSON-RPC loop, protocol handshake, dispatch
• mcp_tools.go (509 LOC) — tool definitions + handler wrappers
• mcp_test.go (247 LOC) — 7 integration tests

Stats

• 49 tests pass with -race
• Pure Go stdlib, zero external dependencies

Closes #5

v1.6.0 — Project registry + remote-based scoping

v1.6.0 — Project registry + remote-based scoping

The Problem

Memories were scoped by the repo's filesystem path. If you deleted, moved, or re-cloned a repo to a different path, the memories became orphaned — still on disk but inaccessible by default. --project memgraph only worked if you were inside the memgraph repo.

The Fix — Three Layers

1. Git remote as scope key
When a repo has a remote, the remote URL (normalized) is used as the scope key instead of the local path. Clone the same repo to any path → same scope. Move the repo → same scope.

2. Project registry (~/.memgraph/projects.json)
Maps human-readable names to memory dirs. --project memgraph resolves via the registry and works from any directory. Auto-imports existing scopes on first run.

3. memgraph attach command

• memgraph attach <name> — register current repo under a stable name
• memgraph attach <name> --from-scope <scope> — rebind an orphaned scope
• memgraph attach --remove <name> — unregister

Scope Resolution Order

1. --memory-dir <path> (explicit override)
2. --project <name> via registry (global, works from any dir)
3. Git remote-based scope (if repo has a remote)
4. Git path-based scope (backward compat for existing memories)
5. Default .memgraph dir (no git repo)

Backward Compatibility

Old path-based scopes are still accessible. When resolving scope for a repo with a remote, memgraph checks if a remote-based scope exists first, then falls back to the path-based scope. New memories go to the remote-based scope.

Cold-Start Verified

An agent with zero memgraph knowledge, starting from /tmp (no git repo), successfully:

1. memgraph projects → discovered 19 projects with names
2. memgraph recall "commands usage" --project memgraph --format index → got section index
3. memgraph read <id>/<slug> --project memgraph → read specific sections

No --memory-dir, no cd, no prior knowledge required.

Stats

• 42 tests pass with -race
• Pure Go stdlib, zero external dependencies
• New file: registry.go (project registry + auto-import)

v1.5.0 — Sectioned memories + project discovery

v1.5.0 — Sectioned memories + project discovery

New Features

Sectioned memories + two-phase recall (#4)
Parse [slug] markers in memory content into addressable sections with line ranges. Agents can recall a compact section index, then read only the section they need — ~80% token reduction for multi-section memories.

• memgraph recall "query" --format index — returns section previews ([slug] Lstart-end "preview...")
• memgraph recall "query" --format paths — returns file paths + absolute line ranges (for native read tool via offset/limit)
• memgraph recall "query" --format full — default, backward compatible
• memgraph read <id>/<slug> — read a single section by slug
• memgraph read <id>/<slug> --json — JSON output for a section
• memgraph read <id> — full memory with section index header

memgraph projects command
Lists all project scopes across all repos with memory counts and paths. Solves the cold-start discovery problem — agents with no prior knowledge can find what projects exist and their --memory-dir paths.

Bug Fixes

• Subcommand --help interception: memgraph recall --help and memgraph read --help now print help instead of searching for "--help" as a query string or memory ID.

Stats

• 42 tests (34 + 8 new section tests), all pass with -race
• Pure Go stdlib, zero external dependencies
• Binaries: linux/amd64, linux/arm64, darwin/amd64, darwin/arm64

Full changelog: https://github.com/javimosch/memgraph/blob/master/docs/changelog-2026-07.html

v1.4.0 — Stable public API freeze

v1.4.0 — Stable public API freeze

The CLI flags, JSON output shapes, and ranking weights are now frozen as of v1.4.0.

Bug Fixes

memgraph remember stdin input (was not_implemented):
memgraph remember with no --text and no positional args now reads from stdin until EOF (Ctrl-D). Previously returned exit code 110 with "not_implemented" — a broken code path in a core command that would have violated the stability promise. Empty stdin still returns invalid_argument (85).

Milestone

• 34 automated tests (go test -race) cover graph build, query scoring, ranking order (golden corpus), serve API JSON-error contract, end-to-end ingest, and memory write
• CI green on master via GitHub Actions (build + vet + test with -race)
• Ranking pipeline consolidated into a single rankNodes function, eliminating triplicated logic across query, recommend, and /api/search
• Golden-corpus ranking test pins top-N ordering for 7 fixed queries — catches ranking regressions while allowing legit weight tuning

What "stable" means

• CLI flags: no breaking changes without a major version bump
• JSON output shapes: field names and structure are frozen
• Ranking weights: the scoring constants are frozen; tuning requires a new minor version

Full changelog: https://github.com/javimosch/memgraph-cli/blob/master/docs/changelog-2026-07.html

v1.3.4 — Serve API unknown /api/* paths return JSON 404

v1.3.4 — Serve API unknown /api/* paths return JSON 404

Bug Fixes

Unknown /api/* paths return JSON 404:
Unknown /api/* paths (e.g. /api/unknown) now return a JSON 404 error instead of Go's default plain-text 404 page not found. This completes the v1.3.2 "all serve API errors return JSON" contract — previously only known endpoints returned JSON errors, while unknown API paths leaked the default http.NotFound handler. Non-API paths (UI routes) still return plain-text 404.

Smoke Tests

Verified query/recommend/related/recall/list limit edge cases, edit/delete/import validation, bridge/setup, and all serve API error paths. All regression queries still return correct results.

Full changelog: https://github.com/javimosch/memgraph-cli/blob/main/docs/changelog-2026-07.html

v1.3.3 — Serve API limit consistency + git stop word

v1.3.3 — Serve API limit consistency + git stop word

Bug Fixes

Serve API limit=0 returns all results:
/api/search?limit=0 now returns all results (was returning 0). The V2 handler was missing the limit > 0 check before truncating results, so results[:0] produced an empty array. Now consistent with CLI behavior where limit=0 means no limit.

Serve API limit=-1 returns all results:
Negative limits are now treated the same as 0 (no limit), consistent with CLI behavior.

"git" added to stop words:
"GitHub" camelCase-splits to "git"+"hub", and "git" was too common (many skills mention git in their name/description), causing queries like "Deploy Go CLI to GitHub" to match git-best-practices instead of more relevant skills. "git best practices" and "git backup encrypted" queries still return correct results (matched by "best", "practices", "backup" keywords).

Smoke Tests Passed

• 19 regression queries — all pass
• 8 serve API limit edge cases (0, -1, abc, 1000, 1, no limit) — all consistent
• 5 corrupted/missing graph file tests — all handled gracefully
• 6 import edge cases (invalid JSON, empty, nonexistent, array, missing content) — all return JSON errors
• 6 session tests (create, list, edit, delete, profile) — all pass
• 6 French/special char tests — accent stripping works for cognates
• 3 concurrent CLI tests (10 concurrent, 200ms) — fast
• Dogfooding: 3/3 correct skill matches (Cloudflare DNS, Go CLI CI/CD, monitoring)

Download

Single static binary — no dependencies, no runtime, no Docker.

v1.3.2 — Serve API JSON errors

v1.3.2 — Serve API JSON errors

Bug Fixes

All serve API error responses now return JSON:

• Unknown node: 404 + {"error":{"type":"not_found",...}}
• Missing/empty q param: 400 + {"error":{"type":"invalid_argument",...}}
• Wrong HTTP method: 405 + {"error":{"type":"method_not_allowed",...}}
• Empty graph: 503 + {"error":{"type":"graph_empty",...}}
• Internal errors: 500 + {"error":{"type":"internal_error",...}}

Added writeJSONError helper for consistent JSON error responses across all API handlers.

Smoke Tests Passed

• 19 regression queries — all pass
• 10 serve API edge cases (404, 400, 405, 503, CORS, long queries) — all return JSON
• 6 recall/search tests (weights, tag-only, empty, limit) — all pass
• 6 demo/import/export tests — all pass
• 6 scoring tests (numbers, versions, ports, mixed case, all caps) — all pass
• Dogfooding: 3/3 correct skill matches (CRM tracking, social media publishing, changelog HTML)

Download

Single static binary — no dependencies, no runtime, no Docker.