GraphMem

GraphMem includes installable user rules and a skill inside this repo:

- rules: docs/global_and_knowledge_graph_management_rules.md
- skill: .cursor/skills/graph-mem-mcp-toolset/SKILL.md

GraphMem exposes the following MCP tools:

- create_entity-- Create new entities with auto-dedup check
- get_entity-- Retrieve entities by ID with observations and relations
- update_entity-- Modify entity name, type, aliases, description
- delete_entity-- Remove entities and all associated data
- search_entities-- Hybrid text + vector semantic search with relevance ranking
- list_entities-- Paginated listing of all entities

- create_observation-- Add observations to existing entities
- update_observation-- Update an active observation or supersede it with a retained replacement
- delete_observation-- Mark observations obsolete while retaining their history

Observations use anactive,obsolete, orsupersededlifecycle. Normal entity reads, graph traversal, relationship discovery, and search expose active observations only. Useget_entity(include_obsolete: true)orinclude_obsolete=trueon observation REST/resource listings to inspect retained history. Explicit duplicate-cleanup maintenance operations still hard-delete redundant active rows.

- create_relation-- Create typed relationships between entities
- delete_relation-- Remove relationships
- find_relations-- Find relationships by entity or type
- traverse_graph-- Bounded multi-hop breadth-first traversal from an entity
- find_shortest_path-- Shortest path (by hop count) between two entities
- get_subgraph_by_ids-- Get connected subgraph of specified entities
- search_subgraph-- Search across entities and observations with pagination

- set_context-- Scope subsequent operations to a project (perX-MCP-Client)
- get_context-- Check the active project context
- clear_context-- Remove project scoping
- bulk_update-- Batch create entities, observations, and relations atomically
- suggest_merges-- Find potential duplicate entities via vector similarity
- merge_entities-- Merge a source entity into a target (transfers observations and relations)
- dream_state_status-- Report background graph compaction state (running/paused/cursor)
- get_maintenance_reports-- Read maintenance/compaction reports, including thecompaction_reviewqueue

- get_version-- Server version
- get_current_time-- Server time in ISO 8601

A backgrounddream-statejob (DreamStateCompactionJob, scheduled via Solid Queuerecurring.yml) periodically compacts the knowledge graph:

- Orphan phase-- attaches high-confidence orphan nodes to matchingProjectroots
- Tree-walk phase-- deduplicates identical observations and auto-merges very similar entities (cosine distance < 0.10)
- Review queue-- lower-confidence merges and orphan matches are written tomaintenance_reports(compaction_review), readable viaget_maintenance_reports

The job iscooperatively pausable: mutating MCP tools request a pause when compaction is running, so live tool traffic takes priority. Usedream_state_statusto inspect cursor position and stats, andget_maintenance_reportsto review and action the queued suggestions. Paused runs resume on the next scheduled trigger.

- memory_entities-- Query entities with filtering, sorting, and relation inclusion
- memory_observations-- Access observations with advanced filtering
- memory_relations-- Query relationships with bidirectional entity inclusion
- memory_graph-- Graph traversals starting from any entity

Full REST API at/api/v1for direct integration. Swagger docs available at/api-docs.

Interactive Cytoscape.js-based graph visualization at the server root (/), with contextual menus, drag-and-drop operations, and data management features.

Prerequisites:Ollama must be running on the host with at least one embedding model pulled:

# Install Ollama (https://ollama.com) then pull the default embedding model ollama pull nomic-embed-text

Theappcontainer usesnetwork_mode: host, so it shares the host's network stack.localhost:11434reaches Ollama with no bridge/firewall configuration needed. The app binds directly to host port 3030.

# Clone and enter the project git clone https://github.com/steveoro/graph_mem.git cd graph_mem # Copy example config and set your master key cp .env.example .env # Edit .env: set RAILS_MASTER_KEY (from config/master.key) and DB_PASSWORD # Start the stack (MariaDB 11.8 + Rails in production mode) docker compose up -d # Seed canonical entity types docker compose exec app bin/rails db:seed # Verify Ollama connectivity docker compose exec app bin/rails embeddings:check # Backfill embeddings docker compose exec app bin/rails embeddings:backfill # Update the container after a repository pull docker compose down && docker compose up -d --build

The app is available athttp://localhost:3030. Swagger API docs athttp://localhost:3030/api-docs.

The app port (3030) is hardcoded on Dockerfile and docker-compose.yml because the service relies on host networking to access the embedding service byollama. This allows a simpler container setup on different machines without resorting to iptables or firewall mangling.

This containerized app is asingle-user serverwith no authentication layer -- it is designed to run locally on a machine and/or be accessible only through a trusted LAN.Do not expose this service to the public internet.

To allow a local Ubuntu server runninggraph_memin a container withollamarunning as a service for embedding processing, remember to allow incoming trafic if you're usingufw(assuming your local LAN is set on 192.168.0.0/24):

sudo ufw allow from 192.168.0.0/24 to any port 3030 proto tcp comment "GraphMem from LAN" sudo ufw allow from 192.168.0.0/24 to any port 11434 proto tcp comment "Ollama from LAN"

This way, the graph_mem UI will be accessible onhttp://<graph_mem_server_ip>:3030/while the MCP server will be athttp://<graph_mem_server_ip>:3030/mcp/sse.

For local development, run the app natively with MariaDB on localhost.

- Ruby 3.4.1+ (via RVM or rbenv)
- MariaDB 11.8+ (for vector search)
- Ollama with an embedding model

cp config/database.example.yml config/database.yml # Edit config/database.yml with your MariaDB credentials bin/rails db:prepare bin/rails db:seed

Option A -- Streamable HTTP transport (recommended for modern clients):

{ "mcpServers": { "graph_mem": { "url": "http://localhost:3030/mcp", "headers": { "X-MCP-Client": "Agent-1" } } } }

Option B -- Legacy SSE transport (Docker / older clients):

{ "mcpServers": { "graph_mem": { "url": "http://localhost:3030/mcp/sse" } } }

Option C -- stdio transport (native development / real-time changes applied):

Before backfilling or regenerating embeddings, verify that the app can reach your Ollama instance:

# Docker docker compose exec app bin/rails embeddings:check # Native bin/rails embeddings:check

This sends a single test embedding throughEmbeddingServiceusing the resolved configuration (AppSettings → ENV → defaults). It reports the resolved config, response latency, and vector dimensions — the exact same code path used bybackfillandregenerate.

For a lower-level check,curlis available inside the production container (host networking meanslocalhostreaches Ollama directly):

# Verify Ollama is reachable and list available models docker compose exec app curl -sf http://localhost:11434/api/tags # Test a raw embedding request docker compose exec app curl -sf http://localhost:11434/api/embed \ -d '{"model":"nomic-embed-text","input":"hello"}'

To change the model (e.g. fromnomic-embed-textto a different one):
- Pull the new model on the Ollama host:ollama pull <model-name>
- Update the model (and dimensions if different) inSystem Settings → Embeddingsor viaEMBEDDING_MODEL/EMBEDDING_DIMSin.env
- Verify connectivity:bin/rails embeddings:checkor the operatorTest connectionbutton
- Recompute all vectors:bin/rails embeddings:regenerateor the operatorRegenerate allaction