Graphonomous Quickstart

This guide gets you from zero to a working Graphonomous MCP runtime in minutes.

What you’ll set up

Run Graphonomous locally
Connect it to your MCP-compatible client
Verify retrieval and learning loops
Build docs locally before publishing to Read the Docs

Prerequisites

Linux/macOS (or WSL on Windows)
Elixir ~> 1.17
Erlang/OTP 27.x
Node.js >= 18 (recommended for npm/npx workflow)
Python >= 3.10 (for docs build)

1) Run Graphonomous

Option A — Fast start with `npx`

npx -y graphonomous --db ~/.graphonomous/knowledge.db --embedder-backend fallback

Option B — Build from source

cd ProjectAmp2/graphonomous
mix deps.get
mix compile --warnings-as-errors
mix test
MIX_ENV=prod mix release --overwrite
_build/prod/rel/graphonomous/bin/graphonomous eval "Graphonomous.CLI.main(System.argv())" -- --db ~/.graphonomous/knowledge.db --embedder-backend fallback

2) Configure your MCP client

Use the Graphonomous command in your MCP server settings.

Example shape:

{
  "context_servers": {
    "graphonomous": {
      "command": "graphonomous",
      "args": ["--db", "~/.graphonomous/knowledge.db", "--embedder-backend", "fallback"],
      "env": {
        "GRAPHONOMOUS_EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
      }
    }
  }
}

If you do not install globally, use npx as the command and pass the package in args.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "graphonomous": {
      "command": "npx",
      "args": ["-y", "graphonomous", "--db", "./.graphonomous/knowledge.db", "--embedder-backend", "fallback"]
    }
  }
}

3) Verify the memory loop

In your client, run a simple cycle:

Store

Save one semantic fact via store_node

Retrieve

Query it with retrieve_context

Learn

Report outcome with learn_from_outcome using returned causal IDs

Inspect

Use query_graph to confirm node and confidence state

If those four steps work, your Graphonomous runtime is healthy.

4) Build docs locally (Read the Docs parity)

From the repository root:

cd ProjectAmp2/graphonomous
python -m pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html

Open docs/_build/html/index.html in your browser to preview docs exactly as generated by Sphinx.

5) Publish docs

With Read the Docs connected to this repo and .readthedocs.yaml enabled, docs will publish automatically on push.

Planned canonical docs URL:

https://docs.graphonomous.com

Troubleshooting

Runtime starts but client cannot connect

Confirm command path is correct
Restart the client after config changes
Keep MCP process on stdio (no background daemon assumptions)

Retrieval returns empty results

Store at least one node first
Query with a specific natural-language prompt
Verify DB path is writable and consistent between runs

Embedding/model friction on laptops

Keep --embedder-backend fallback enabled during initial setup

Docs build fails

Reinstall docs dependencies
Ensure docs/conf.py exists and root_doc points to index

Next reads

architecture — internals and runtime components
mcp-tools — complete tool/resource reference
runtime-walkthrough — retrieve → act → store → learn loop in practice
operations — maintenance, consolidation, and release workflow