NeuroDock Cognitive Graph

io.github.tlennon-iePublished by GitHub account tlennon-iev0.0.6Updated Oct 24, 2026

A local typed-edge graph of people, projects, and decisions that externalises memory.

VerifiedSTDIODesktop onlyDatabasesKnowledge & Memory

Overview

AI-generated overview

A local SQLite graph of people, projects, decisions, and concepts that lets an assistant record typed facts and recall entities, decisions, and weekly activity.

What you can do
Exposes four tools backed by a local SQLite file. recall_entity looks up a person, project, decision, or concept and returns its facts, first-degree neighbours, and a resolution diagnostic. record_fact persists a typed-edge fact and auto-creates entities, restricted to an eight-predicate vocabulary. recall_decisions returns a project's decisions by date, and weekly_rollup produces a server-templated summary of the trailing seven days without calling an LLM.
When to use it
Useful when you want an assistant to keep persistent memory of people, projects, and decisions across sessions, especially for long-running or context-switched work where each session would otherwise start from zero. It is a local, single-file store rather than a shared or team knowledge base.
Requirements
Runs as a local stdio process installed from PyPI (for example with uv or pip). Python and the package runtime are required. The graph is stored at ~/.neurodock/cognitive-graph.sqlite by default, overridable with the NEURODOCK_GRAPH_DB_PATH environment variable. No accounts, API keys, or network access are declared.
Before you install
The server writes to a local SQLite file, so recorded facts and entities persist and can be read by anything with access to that path. It is local-first with no network access or telemetry, and source strings are stored verbatim but never fetched. Vector recall and embeddings are not in this version.

Installation

In SourceWeft

  1. Open NeuroDock Cognitive Graph in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

neurodock-mcp-cognitive-graph

Persistent entity memory for the NeuroDock substrate, exposed as an MCP server. Externalises the user's working memory of people, projects, decisions, and concepts so a hyperfocused or context-switched session does not start from zero.

This is v0.0.3 — the current release. Vector recall, fastembed embeddings, and sqlite-vec are deferred to a future version; see CHANGELOG.md.

Install

sh
uv add neurodock-mcp-cognitive-graph# orpip install neurodock-mcp-cognitive-graph

Use as an MCP server

Add to your ~/.claude.json (Claude Code) or claude_desktop_config.json (Claude Desktop):

json
{  "mcpServers": {    "neurodock-cognitive-graph": {      "command": "uv",      "args": ["run", "neurodock-mcp-cognitive-graph"]    }  }}

Quickstart

bash
# From the workspace root.uv sync --all-packages
# Start the server on stdio (Claude Desktop / Claude Code MCP config).uv run neurodock-mcp-cognitive-graph

The server stores its graph at ~/.neurodock/cognitive-graph.sqlite by default. Override with the NEURODOCK_GRAPH_DB_PATH environment variable.

Tools (v0.0.3)

ToolPurpose
recall_entity(name_or_alias)Look up a person/project/decision/concept. Returns the entity, its facts (capped at 500), first-degree neighbours (capped at 20), and a resolution diagnostic.
record_fact(subject, predicate, object, source?, confidence?)Persist a typed-edge fact. Auto-creates entities by (type, name). Enforces the v0.1.0 eight-predicate vocabulary.
recall_decisions(project, since?)Return decisions for a project, ordered by date desc, capped at 200.
weekly_rollup(project?)Server-templated activity summary for the trailing seven UTC days. No LLM call (vendor boundary).

The full input/output contract is in schemas/. The Pydantic v2 models in src/neurodock_mcp_cognitive_graph/types.py mirror those schemas.

Predicate vocabulary

The eight predicates in v0.1.0 are: mentioned_in, decided_in, reports_to, depends_on, resolved_by, blocked_by, tagged, belongs_to. Unknown predicates raise PREDICATE_NOT_IN_VOCABULARY. Extension predicates land via the v0.2 type_extensions mechanism — see ADR 0002 — cognitive-graph tool design.

Privacy

  • Local-first. No network access. No telemetry.
  • source strings are stored verbatim and never fetched by the server.
  • User content (entity names, decision titles, fact text) is never logged. Error logs include only the structured error code.

Storage

SQLite. One file. Migrations live as numbered .sql files in src/neurodock_mcp_cognitive_graph/migrations/ and are applied on first connect. The schema is described in migrations/0001_init.sql.

Architecture

src/neurodock_mcp_cognitive_graph/├── server.py            FastMCP wiring + CLI entrypoint├── types.py             Pydantic v2 models (mirror of the JSON Schemas)├── config.py            Resolves the SQLite path├── clock.py             SystemClock / FixedClock├── errors.py            ToolError envelope├── resolution.py        Entity name/alias cascade (exact, alias only in v0.0.3)├── rollup.py            Heuristic decision/blocker/next-action assembly├── storage/│   ├── base.py          Storage Protocol + row dataclasses│   ├── memory.py        InMemoryStorage (used by tests)│   └── sqlite.py        SQLiteStorage (production backing)├── tools/│   ├── recall_entity.py│   ├── record_fact.py│   ├── recall_decisions.py│   └── weekly_rollup.py└── migrations/    └── 0001_init.sql

ADR pointers

Tests

bash
uv run pytest packages/mcp-cognitive-graph/tests/ -v

25 tests covering: per-tool unit tests, a FastMCP protocol-conformance suite that exercises every tool and validates the response against the JSON Schema using jsonschema, and an end-to-end test that runs against a real file-backed SQLite store.

Source: packages/mcp-cognitive-graph/README.md at commit 2d9cac6

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.0.6LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts