feat(memorygraph): add persistent memory graph package and MCP tools

[greynewell]

Summary

Squash-merge of the fixed version of #136 onto current main (the original branch history was too messy to rebase cleanly — 33 commits with renames/deletes/capitalisation changes).

• New package internal/memorygraph: typed, weighted knowledge graph persisted at .supermodel/memory-graph.json
• Node types: fact, concept, entity, event, procedure, context
• Weighted directed edges with relation types (related_to, causes, part_of, etc.)
• BFS traversal, scored full-text search, similarity auto-linking, stale-link pruning
• peek.go: node inspection layer (by ID or label) with formatted terminal output
• Six new MCP tools in server.go: upsert_memory_node, create_relation, search_memory_graph, retrieve_with_traversal, prune_stale_links, add_interlinked_context
• 15 unit tests for peek.go
• All lint issues from the original PR resolved (import casing, broken function structure, gocritic, revive, staticcheck SA5011)

Closes #136

Test plan

• make lint — 0 issues
• go test ./internal/memorygraph/... — all 15 tests pass
• go build ./... — compiles cleanly

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a persistent memory graph system to store, organize, and retrieve interconnected information nodes
  • Create typed nodes and establish weighted relationships between them
  • Search functionality with depth-limited expansion to discover connected information
  • Traversal capability from any starting node with relevance-based ranking
  • Automatic link pruning to remove stale or low-confidence connections
  • Auto-linking feature to identify and connect semantically similar nodes
  • Graph viewing and inspection tools to explore nodes and relationships

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

Walkthrough

Introduces a persistent in-memory graph system for the Go MCP server. Adds core graph operations (upsert nodes, create typed relations, search, traversal, pruning) with JSON file persistence, read-only inspection tools, and MCP tool wrappers to expose graph functionality.

Changes

Cohort / File(s)	Summary
Core Memory Graph Engine internal/memorygraph/memory_graph.go	Implements typed, weighted directed graph with 6 node types and 7 relation types. Provides node upsert, relation creation, depth-limited BFS traversal with relevance decay, scored search with token overlap and one-hop neighbor expansion, stale edge pruning with orphan cleanup, and batch interlinked-context addition with auto-similarity linking via Jaccard ≥ 0.72. Persists as atomic JSON under .supermodel/memory-graph.json with read/write mutex concurrency safety.
Graph Inspection & Peek API internal/memorygraph/peek.go, internal/memorygraph/peek_test.go	Adds read-only node snapshots (NodePeek, EdgePeek) with inbound/outbound edge summaries. Peek resolves nodes by ID or case-insensitive label; PeekList returns all nodes sorted by descending access count. Includes human-readable terminal formatting and comprehensive unit tests covering lookup, edge resolution, empty graphs, and access-count ordering.
MCP Tool Wrappers & Server Integration internal/memorygraph/tools.go, internal/mcp/server.go	Wraps graph operations as MCP tools (ToolUpsertMemoryNode, ToolCreateRelation, ToolSearchMemoryGraph, ToolPruneStaleLinks, ToolAddInterlinkedContext, ToolRetrieveWithTraversal). Adds server-side dispatch handlers that parse arguments, invoke graph functions, format results, and return summary stats. Includes helpers for argument parsing and interlinked-item validation.

Sequence Diagram

sequenceDiagram
    actor Client
    participant MCP Server
    participant Tool Wrapper
    participant Memory Graph
    participant Storage

    Client->>MCP Server: Request (e.g., SearchGraph)
    activate MCP Server
    MCP Server->>Tool Wrapper: Dispatch with parsed args
    activate Tool Wrapper
    
    Tool Wrapper->>Memory Graph: SearchGraph(query, maxDepth, topK)
    activate Memory Graph
    
    Memory Graph->>Storage: Load graph from JSON
    activate Storage
    Storage-->>Memory Graph: Graph data
    deactivate Storage
    
    Memory Graph->>Memory Graph: Score & rank nodes<br/>(substring + token overlap)
    Memory Graph->>Memory Graph: Expand 1-hop neighbors<br/>(adjacency + weight filter)
    Memory Graph->>Memory Graph: Async bump access counts
    Memory Graph-->>Tool Wrapper: SearchResult{Direct, Neighbors}
    deactivate Memory Graph
    
    Tool Wrapper->>Tool Wrapper: Format results<br/>(truncate content,<br/>include stats)
    Tool Wrapper-->>MCP Server: Human-readable string
    deactivate Tool Wrapper
    
    MCP Server-->>Client: Response with results
    deactivate MCP Server

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

The PR introduces substantial new functionality across five files with dense, multi-algorithm logic (graph traversal, relevance scoring, similarity computation, JSON persistence, concurrency). While relatively self-contained, the changes demand understanding of graph data structures, BFS traversal, token-set similarity, and MCP integration patterns.

Suggested reviewers

• jonathanpopham

Poem

📊 A graph takes shape in JSON's embrace,
Nodes intertwined in persistent space,
Search flows deep through weighted relations,
Each link a bridge of associations—
Memory blooms, no context left behind! 🧠✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 72.73% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat(memorygraph): add persistent memory graph package and MCP tools' accurately summarizes the main change—introducing a new internal package with core graph functionality and MCP tool integration.
Description check	✅ Passed	The PR description covers all essential template sections: explains what (new memorygraph package with features), why (ports TypeScript tools to Go), and includes a test plan with checkboxes for make lint, make test, and manual testing.
Linked Issues check	✅ Passed	The code changes fully meet the objectives from #136: implements memory_graph.go with typed nodes/edges and persistence, tools.go with six MCP tool wrappers, peek.go for node inspection, and integrates into server.go dispatch.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to the memorygraph package objectives: core graph engine, MCP tool wrappers, inspection layer, server integration, and unit tests for peek.go. No unrelated modifications detected.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/memorygraph

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}