This page is the operational runbook for running, validating, and maintaining Graphonomous in development and production-like environments.
Graphonomous runs as an Elixir/OTP application with supervised runtime services and an MCP server interface over stdio. Core operational concerns are:
Process health (runtime services are up)
Data durability (SQLite-backed state)
Retrieval quality (memory remains relevant)
Learning integrity (outcomes update confidence correctly)
Memory hygiene (consolidation decay/pruning cycles)
Transport stability (MCP client/server connectivity)
Use this checklist for routine operation:
Start Graphonomous with an explicit DB path.
Verify runtime health snapshot.
Verify goals snapshot (if goal-driven workflows are active).
Confirm retrieval works on a known query.
Confirm writes (store_node) and updates (learn_from_outcome) succeed.
Run/inspect consolidation state.
Review logs for transport disconnects or repeated timeouts.
Run Graphonomous with a dedicated local DB:
Ensure your DB directory exists.
Start using fallback embedder when troubleshooting or on constrained devices.
Recommended startup characteristics:
Explicit --db path
Stable log level (info or debug)
Request timeout tuned for your client/editor
After startup, validate in this order:
Tool discovery returns expected Graphonomous tools.
Resource reads succeed:
graphonomous://runtime/health
graphonomous://goals/snapshot
A test retrieval query returns status: ok.
A test node write succeeds.
Use graphonomous://runtime/health to verify:
Process-level service status (up/down)
High-level object counts (nodes/goals)
Timestamp of snapshot generation
If any core service is down, restart runtime and verify DB accessibility.
Use graphonomous://goals/snapshot to verify:
Total number of goals
Status distribution (proposed, active, blocked, completed, etc.)
Serialized goal records for debugging orchestration state
Graphonomous uses SQLite as durable storage and ETS as hot in-memory cache.
Operational implications:
SQLite file is the recovery source of truth.
ETS is rebuilt/warmed from DB state.
Always keep DB path explicit and stable per environment.
Recommended backup practice:
Schedule periodic copies/snapshots of the SQLite DB file.
Perform backups during low-write periods when possible.
Keep at least:
daily rolling backups (7 days),
weekly backups (4 weeks),
monthly backups (3–6 months).
If runtime state appears inconsistent:
Stop Graphonomous.
Backup current DB file before changes.
Restart runtime and verify health.
Re-run retrieval sanity checks.
If needed, restore from known-good backup and replay required operational steps.
For consequential actions:
Retrieve context first.
Perform action.
Report outcome with real causal_node_ids.
This keeps confidence updates meaningful and avoids drift.
Use outcome status correctly:
success: action achieved intended result
partial_success: mixed outcome
failure: action failed
timeout: no reliable completion signal
Treating timeouts as failures can incorrectly penalize good knowledge.
Operational rule:
Use evidence-calibrated confidence values.
Avoid blanket high confidence in both stored nodes and outcomes.
Favor structured evidence payloads for audits and debugging.
For multi-step work, always use goals.
Typical progression:
proposed -> active -> completed or proposed/active -> blocked -> active (when unblocked)
Before high-impact actions, run goal coverage review to route execution:
act: proceed
learn: gather additional context
escalate: block/escalate to human or multi-agent process
Update progress incrementally (avoid “jump to 100%” without evidence).
Link supporting nodes to goals.
Keep transition metadata descriptive for auditability.
Consolidation maintains memory quality over time.
End of productive sessions
Periodically during long autonomous runs
After heavy write/ingestion bursts
Before critical retrieval/review checkpoints
From consolidation status/runtime info monitor:
cycle count
last run timestamp
decay/prune behavior
signs of overly aggressive pruning
If retrieval quality drops sharply, inspect consolidation settings and confidence distributions.
Symptoms:
client timeouts
server shutdown messages
intermittent success/failure across calls
Response:
Confirm runtime process is alive.
Validate health resource.
Restart MCP runtime cleanly.
Re-run minimal smoke flow (list tools -> read resources -> retrieve -> store).
Inspect logs for transport and timeout patterns.
Increase request timeout if workload is heavy.
Symptoms:
retrieval works but node/goal writes fail
partial success in batches
Response:
Verify DB path and file permissions.
Check available disk space.
Restart runtime.
Retry writes idempotently.
Confirm data via query/list calls after retry.
Symptoms:
poor relevance
stale/conflicting recall
weak support around active goals
Response:
Inspect low-confidence node concentration.
Run consolidation.
Add missing high-quality nodes (semantic, procedural, temporal, outcome, or goal as appropriate).
Use coverage review to identify knowledge gaps.
Avoid forcing action when routing says learn or escalate.
Before releases:
Run format, compile, and tests.
Verify MCP tools/resources remain discoverable.
Validate key operational workflows:
retrieve -> store -> learn -> consolidate
Confirm docs and CLI help text are in sync with behavior.
Ensure version parity across project metadata and distribution artifacts.
After releases:
Smoke test install/run path.
Verify health/resource access from at least one MCP client.
Confirm no regressions in goal operations and consolidation calls.
Never store secrets or credentials in graph content/metadata.
Use least-privilege file permissions for DB directories.
Keep logs free of sensitive user data where possible.
Prefer explicit, auditable metadata over opaque free-text for critical actions.
Treat externally sourced claims as lower confidence until verified.
These are practical baseline targets you can tune per environment:
Runtime availability: core services up > 99%
MCP request success rate: > 99% for standard calls
Median retrieval latency: < 2s on local workloads
Write success rate: > 99% for node/goal operations
Consolidation cadence adherence: > 95% of expected cycles
| Symptom | Likely Cause | First Action |
|---|---|---|
| Tool calls timeout | Transport/runtime instability | Restart runtime, re-check health |
| Goals not updating | Write-path issue or bad payload | Validate payload shape, retry update |
| Retrieval returns empty repeatedly | Sparse graph or wrong query scope | Seed knowledge, broaden query |
| Coverage always escalates | Insufficient support/confidence | Add evidence nodes, review contradictions |
| Sudden memory loss feel | Aggressive decay/prune settings | Inspect consolidation config/status |
Before ending a productive session:
Store key new knowledge discovered.
Report any pending outcomes.
Update goal progress/status.
Trigger consolidation and verify status.
Capture any unresolved risks in a goal note for next session continuity.
index — docs entry point
architecture — system design and internals
quickstart — first-run path
mcp-tools — tool/resource interface reference
skills/SKILLS — operational agent behavior loop
NPM_PUBLISH — release/distribution runbook
ZED — editor integration guidance