This guide shows you how to run Graphonomous as an MCP server in Zed with a working local setup.
Elixir ~> 1.17
Erlang/OTP 27.x
Zed with Agent/AI features enabled
From the project root:
cd ProjectAmp2/graphonomous
You can run Graphonomous in two modes:
Use Mix with no compile step:
mix run --no-compile -e 'Graphonomous.CLI.main(["--db","~/.graphonomous/knowledge.db","--embedder-backend","fallback"])'
This is the easiest way to test local changes quickly.
Build the graphonomous executable:
MIX_ENV=prod mix escript.build
This creates:
./graphonomous
Before wiring Zed, verify the command starts.
If using fast dev mode:
mix run --no-compile -e 'Graphonomous.CLI.main(["--help"])'
If using built executable mode:
./graphonomous --help
Then run server mode (stdio MCP transport).
Fast dev mode:
mix run --no-compile -e 'Graphonomous.CLI.main(["--db","~/.graphonomous/knowledge.db","--embedder-backend","fallback"])'
Built executable mode:
./graphonomous --db ~/.graphonomous/knowledge.db --embedder-backend fallback
Notes:
--embedder-backend fallback is the safest default for constrained laptops.
Press Ctrl+C to stop.
Run this before deploying or updating your Zed config:
python scripts/mcp_smoke_test.py --cwd .
What it validates:
initialize handshake succeeds
notifications/initialized is accepted
tools/list responds
resources/list responds
response latencies stay within thresholds
Useful variants:
# verbose stderr while testing python scripts/mcp_smoke_test.py --cwd . --tee-stderr
# stricter latency gates (example) python scripts/mcp_smoke_test.py --cwd . --max-initialize-ms 2500 --max-discovery-ms 2500
context_servers)Open your Zed settings JSON and add one of the following.
{ "context_servers": { "graphonomous": { "command": "/absolute/path/to/ProjectAmp2/graphonomous/graphonomous", "args": [ "--db", "~/.graphonomous/knowledge.db", "--embedder-backend", "fallback" ], "env": { "GRAPHONOMOUS_EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2", "LOG_LEVEL": "info" } } } }
If graphonomous is on your PATH, you can use:
"command": "graphonomous"
instead of an absolute path.
{ "context_servers": { "graphonomous": { "command": "sh", "args": [ "-lc", "cd /absolute/path/to/ProjectAmp2/graphonomous && mix run --no-compile -e 'Graphonomous.CLI.main([\"--db\",\"~/.graphonomous/knowledge.db\",\"--embedder-backend\",\"fallback\"])'" ], "env": { "LOG_LEVEL": "info" } } } }
Use Option B while actively changing code; switch to Option A for daily/stable usage.
To make Graphonomous usage consistent in every chat, load the skills pack into your agent prompt context at chat start.
Skills live in the ampersand-plugins repo. Reference docs are mirrored in docs/skills/.
Minimum required context:
docs/skills/SKILLS.md
docs/skills/bootstrap.md
Recommended full context:
docs/skills/retrieve.md
docs/skills/learn.md
docs/skills/deliberate.md
docs/skills/consolidate.md
docs/skills/goals.md
docs/skills/attention.md
docs/skills/workflows.md
If your Zed workflow supports per-assistant system/developer instructions, include the SKILLS.md and bootstrap.md there so they are applied automatically each chat.
Open the Agent panel.
Go to MCP/context server settings.
Confirm graphonomous is active (running indicator).
At the start of each new chat, load the prompt context from:
docs/skills/SKILLS.md
docs/skills/bootstrap.md
For best results, also load additional skill files from docs/skills/ (e.g., retrieve.md, learn.md, workflows.md).
Start the prompt and ask it to use Graphonomous tools explicitly, e.g.:
“Use graphonomous to retrieve(action: “context”, ...) before answering.”
“Use graphonomous to act(action: “store_node”, ...) for semantic memory.”
“Use graphonomous to learn(action: “from_outcome”, ...) for outcome feedback.”
Store a few nodes with act(action: "store_node", ...).
Query them via retrieve(action: "context", ...).
Feed outcomes via learn(action: "from_outcome", ...).
Inspect runtime with query_graph and resource snapshots.
This gives you a full closed-loop memory flow without external integrations.
If you want Zed to use command: "graphonomous" without absolute paths:
sudo install -m 0755 ./graphonomous /usr/local/bin/graphonomous
Then confirm:
graphonomous --help
Use absolute command path first.
Verify executable permissions:
chmod +x /absolute/path/to/graphonomous
Test the exact command manually in terminal.
Ensure parent dir exists:
mkdir -p ~/.graphonomous
Keep --embedder-backend fallback.
Keep default model unless you intentionally change it.
Mention graphonomous by name in your prompt.
Ask explicitly to call a specific tool (store_node, retrieve_context, etc.).
{ "context_servers": { "graphonomous": { "command": "/absolute/path/to/ProjectAmp2/graphonomous/graphonomous", "args": ["--db", "~/.graphonomous/knowledge.db", "--embedder-backend", "fallback"], "env": {} } } }
When you pull new changes:
cd ProjectAmp2/graphonomous git pull MIX_ENV=prod mix escript.build
If you installed globally, reinstall the binary:
sudo install -m 0755 ./graphonomous /usr/local/bin/graphonomous