Catalog›MCP servers›AI, search & memory›io.github.CloudCorpRecords/graphmindIGio.github.CloudCorpRecords/graphmindPersistent knowledge graph: entities, relations, and observations for agents. Open site Open in the app JSON README (API)Persistent knowledge graph: entities, relations, and observations for agents.READMELoading documentation…# graphmind graphmind is a small, durable memory for agents: a knowledge graph you can build up a fact at a time and query back later. You record **entities** — people, places, projects, anything with a name — each with a type and a growing list of plain-text **observations**, and you connect them with typed **relations** ("Alice — lives_in → Lisbon"). The whole graph lives in one JSON file on disk, so the memory survives restarts and stays readable, diffable, and editable by hand. There is no database to run and no service to sign up for. The graph file is the product. ## Install ```bash npx @reneturcios/graphmind read ``` Or run the container image: ```bash docker run -i ghcr.io/cloudcorprecords/graphmind ``` The container defaults to the MCP server (see below). Pass CLI arguments to use it as a CLI instead. If you run the container, mount a volume over the working directory if you want the graph file to persist between runs. ## Where the graph lives The store file path comes from the `GRAPHMIND_FILE` environment variable and defaults to `./graphmind.json` in the current working directory. The file is loaded when the server (or a CLI command) starts, and it is rewritten after every change, so what is on disk is always the full current graph: ```json { "entities": [ { "name": "Alice", "entityType": "person", "observations": ["Lives in Lisbon"] } ], "relations": [ { "from": "Alice", "to": "Lisbon", "relationType": "lives_in" } ] } ``` ## CLI The CLI is a read/inspect face over the same store file the MCP server writes: ```bash # Print the whole graph as JSON graphmind read # Print the subgraph matching a search term graphmind search lisbon # Point at a specific store file GRAPHMIND_FILE=~/notes/graph.json graphmind read graphmind --version ``` Exit codes: `0` on success, `1` when the store cannot be read or written, `2` for usage errors. ## MCP server One bin serves both faces. The `mcp` subcommand starts a stdio MCP server: ```bash npx -y @reneturcios/graphmind mcp ``` MCP client configuration: ```json { "mcpServers": { "graphmind": { "command": "npx", "args": ["-y", "@reneturcios/graphmind", "mcp"], "env": { "GRAPHMIND_FILE": "/path/to/graphmind.json" } } } } ``` ### Tools | Tool | Input | What it does | | --- | --- | --- | | `create_entities` | `entities`: array of `{name, entityType, observations}` | Adds entities whose names are not already taken. Existing names are skipped and the stored entity is left untouched. Returns only the entities actually created. | | `create_relations` | `relations`: array of `{from, to, relationType}` | Adds relations whose exact triple is not already present. Returns only the relations actually created. | | `add_observations` | `observations`: array of `{entityName, contents}` | Appends observation strings to existing entities, skipping strings the entity already has. Returns what was added, per entity. | | `delete_entities` | `entityNames`: array of strings | Removes the named entities and every relation that touches any of them. | | `delete_observations` | `deletions`: array of `{entityName, observations}` | Removes the listed observation strings from the named entities. | | `delete_relations` | `relations`: array of `{from, to, relationType}` | Removes relations matching the given exact triples. | | `read_graph` | _(none)_ | Returns the entire graph: all entities and all relations. | | `search_nodes` | `query`: string | Case-insensitive substring search over entity names, types, and observations. Returns the matching entities plus the relations whose endpoints both matched. | | `open_nodes` | `names`: array of strings | Returns the named entities plus the relations between them. Unknown names are skipped. | ### Behaviour worth knowing - **Names are identity.** An entity is its name; creating a second entity with the same name does nothing. Rename by deleting and recreating. - **Relations need real endpoints.** `create_relations` requires both the `from` and `to` entities to already exist, and fails the whole call if one is missing — no stub entities are invented, so a typo surfaces immediately instead of quietly corrupting the graph. - **Observations are a set, in order.** Adding a string an entity already carries is a no-op; new strings append in the order given. - **Deletes cascade only from entities.** Deleting an entity removes its relations; deleting observations or relations never touches anything else. ## Development ```bash npm install npm run build # tsc -> dist/ npm test # node test runner over test/*.test.ts, no network npm run dev # run the CLI from source via tsx ``` ## License MIT — see `LICENSE`. DetailsTypeMCP serversTopicAI, search & memoryPublishercloudcorprecordsSourceofficialCategoryToolsWhere it runsOn my computerVersion0.1.0Last update2026-10-27T19:23:26ZProject statusActiveLanguageTypeScriptLicenseMITAdded2026-10-27 19:38:00Updated2026-10-27 19:38:00Source idio.github.CloudCorpRecords/graphmindMoreMore mcp servers on AI, search & memoryAll from cloudcorprecordsA–Z index
