OriginTrail DKG V10 Node — your multi-agent memory 🦞

Give your AI agents the ultimate memory that survives the session.

The Decentralized Knowledge Graph V10 is the shared, verifiable memory layer for multi-agent AI systems. Every finding your agents produce can flow from a private draft to a team-visible share to a permanent, cryptographically anchored record — queryable by any agent, owned by the publisher. No black boxes. No vendor lock-in. No context that evaporates when the session ends.

Disclaimer: DKG V10 is in release-candidate on the testnet. Expect rapid iteration and breaking changes. Please avoid using in production environments and note that features, APIs, and stability may change as the project evolves.

---

What is DKG V10

This is the monorepo for the Decentralized Knowledge Graph V10 node — the node software, CLI, dashboard UI, protocol packages, adapters, and tooling needed to run a DKG node and participate in the network.

Any AI agent — whether built with OpenClaw, ElizaOS, Hermes, or any custom framework — can run a DKG node and start exchanging knowledge with other agents across the network, without any central authority, API gateway, or vendor platform in between.

Why a Decentralized Knowledge Graph

Most agent memory today is flat: conversation logs, vector embeddings, Markdown files. A knowledge graph stores facts as structured relationships (subject → predicate → object), so agents can reason over connections, not just retrieve similar text. When Agent A publishes "Company X acquired Company Y on March 5", any other agent can query for all acquisitions by Company X, all events on March 5, or all entities related to Company Y — without knowing what to search for in advance. The graph structure turns isolated findings into composable, queryable collective intelligence. Packaging that graph into DKG Knowledge Assets gives it clear ownership, history, and integrity.

Why Knowledge Assets enable trust

A Knowledge Asset (KA) is a unit of published knowledge: a set of RDF statements bundled with a Merkle proof and anchored to the blockchain. Once published, the content is immutable — anyone can verify that the data hasn't been tampered with by recomputing the proof against the on-chain root. Agents don't need to trust each other; they verify. Every claim has cryptographic provenance: who published it, when, and exactly what was said.

Why context graphs enable collaboration

A Context Graph is a scoped knowledge domain (the UI calls them "projects") with configurable access and governance. Agents can keep a context graph private, open it to specific peers, or back it with on-chain M-of-N signatures so a group must agree before anything is finalized. Every context graph can be further partitioned into named sub-graphs for finer-grained organization of knowledge within the same domain.

In experiments with coding agents leveraging the DKG for shared knowledge, we observed both reduced completion time and lower costs compared to agents operating without a collective memory layer.

---

The three memory layers

DKG V10 gives every agent a three-layer verifiable memory system. Knowledge is written in the cheapest, most private layer first and promoted outward as it matures.

Layer	Scope	Cost	Trust	Persistence
Working Memory (WM)	Private to your agent	Free	Self-attested	Local, survives restarts
Shared Working Memory (SWM)	Visible to context-graph peers	Free	Self-attested, gossip-replicated	TTL-bounded
Verified Memory (VM)	Permanent, on-chain	TRAC	Self-attested → endorsed → consensus-verified	Permanent

The canonical flow for a new assertion is WM → SWM → VM:

create assertion ──► write triples ──► promote ──► publish ──► (optional) M-of-N verify
     (WM)              (WM)            (WM→SWM)   (SWM→VM)              (VM)

All on-chain publishing goes through SWM first — the chain transaction is a finality signal that seals data peers already hold via gossip. Assertions themselves carry a durable lifecycle record (created → promoted → published → finalized, or discarded) in the context graph's _meta graph, so their history is auditable independently of the data.

SWM gossip is signed when the node has a local agent private key. Context graphs that declare DKG_ALLOWED_AGENT or DKG_PARTICIPANT_AGENT require a signed GossipEnvelope from one of those agent addresses; unsigned legacy SWM payloads are accepted only for context graphs without agent gates. Signatures authenticate the writer, but do not encrypt GossipSub payload bytes.

---

Quick Start

Prerequisites: Node.js 22+, npm 10+. macOS, Linux, and Windows (PowerShell 5.1+ or WSL2) all supported.

Hermes adapter

Two commands:

npm install -g @origintrail-official/dkg
dkg hermes setup

dkg hermes setup bootstraps the DKG node config (no separate dkg init needed), starts the daemon, optionally funds wallets, and wires the Hermes profile with replace-by-default provider election (use --preserve-provider to opt out, --no-start / --no-fund for advanced flows). See the adapter guide for details.

OpenClaw adapter

Two commands:

npm install -g @origintrail-official/dkg     # installs CLI + bundled adapter
dkg openclaw setup                           # configures + starts the daemon, registers the plugin

dkg openclaw setup is non-interactive and idempotent. It writes ~/.dkg/config.json, merges the adapter into ~/.openclaw/openclaw.json (under plugins.entries.adapter-openclaw.config — daemonUrl, memory.enabled, channel.enabled), syncs the canonical DKG node skill into the OpenClaw workspace at skills/dkg-node/SKILL.md, and verifies the install. The right-panel "Connect OpenClaw" button in the node UI runs the same in-process flow.

Restart the OpenClaw gateway if it does not auto-reload:

openclaw gateway restart

First-run verification. A healthy setup satisfies all four:

• dkg_status works from the OpenClaw agent
• The DKG node UI loads at http://127.0.0.1:9200/ui
• The right-side chat surface connects to OpenClaw and a sent message round-trips
• The conversation survives a UI reload (proves DKG-backed chat persistence)

Flags. --no-fund (skip faucet), --no-start (configure only), --no-verify (skip verification), --dry-run (preview without writing). Faucet funding is best-effort: a failed call logs a ready-to-paste curl block and setup continues. See the Testnet Funding section below for the full request/response shape.

The full adapter reference — daemon URL config, channel-port overrides, disconnect/reconnect semantics — lives in packages/adapter-openclaw/README.md.

Troubleshooting (OpenClaw)

• Adapter not visible to gateway → check ~/.openclaw/openclaw.json has plugins.entries.adapter-openclaw populated; re-run dkg openclaw setup.
• Faucet failure → setup logs a curl block for manual funding; the node still works for non-on-chain flows (P2P, queries, WM/SWM writes).
• Disconnect / Reconnect cycle wiped my custom config → re-run dkg openclaw setup --port <N> after Reconnect. Default-port users see no visible difference across the cycle.
• Channel port 9201 already in use → set channel.port manually under plugins.entries.adapter-openclaw.config in ~/.openclaw/openclaw.json.

Model Context Protocol (MCP)

Two commands wire DKG V10 into MCP-aware clients (Cursor, Claude Code, Claude Desktop, Windsurf, VSCode + GitHub Copilot Chat, Cline):

npm install -g @origintrail-official/dkg
dkg mcp setup

dkg mcp setup bootstraps the DKG node config (no separate dkg init needed), starts the daemon, optionally funds wallets, and registers MCP entries in each detected client (you confirm per client unless --yes is passed). See the MCP integration guide for client-by-client paths, mode overrides (--installed / --monorepo), the manual JSON shape, the contributor monorepo dev workflow, and troubleshooting (including the WSL2 caveat for Windows-side MCP clients).

Standalone node

Skip the framework wiring — run the daemon directly and use the CLI or HTTP API:

npm install -g @origintrail-official/dkg
dkg init      # creates ~/.dkg/config.yaml (auto-funds wallets on testnet if faucet reachable)
dkg start     # starts the node daemon on http://127.0.0.1:9200

Once running, open the dashboard at http://127.0.0.1:9200/ui, or query directly:

TOKEN=$(dkg auth show)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9200/api/agents

---

Community integrations

Beyond the first-party framework adapters above, DKG V10 supports community-contributed integrations — CLIs, MCP servers, agent plugins, and services that run against your local node through its public HTTP API, dkg CLI, or MCP interface. They live in contributor-owned repositories and are discovered through the OriginTrail/dkg-integrations registry.

dkg integration list                              # list verified + featured tiers (default)
dkg integration list --tier community             # include community-tier (contributor-submitted) entries
dkg integration info <slug>                       # inspect a single entry
dkg integration install <slug>                    # install — automates `cli` and `mcp` install kinds
dkg integration install <slug> --allow-community  # required to install a community-tier entry

By design, list shows only verified and featured tiers and install refuses community-tier entries unless you opt in — community submissions haven't been peer-reviewed by the OriginTrail core team, so discovering and installing them is an explicit choice. The CLI automates the cli and mcp install kinds today; service, agent-plugin, and manual kinds aren't auto-installed yet — install exits with the entry's repo URL so you can follow its README. For cli installs, the CLI verifies the npm tarball's publish-time sigstore provenance against the registry-declared repo before running npm install --global (--no-verify-provenance to skip).

Building one: fork the minimal reference template at OriginTrail/dkg-hello-world — ~150 lines, zero dependencies, demonstrates the full Working Memory write → read round trip. Submission rules (schema, security checks, trust tiers) are in the registry's CONTRIBUTING.md.

---

CLI commands

dkg init                                 # interactive setup — node name, role, relay
dkg start [-f]                           # start the node daemon (-f for foreground)
dkg stop                                 # graceful shutdown
dkg status                               # node health, peer count, identity
dkg logs                                 # tail the daemon log
dkg peers                                # connected peers and transport info
dkg peer info <peer-id>                  # inspect a peer's identity and addresses

# Direct messaging
dkg send <name> <msg>                    # encrypted direct message to a peer
dkg chat <name>                          # interactive chat with a peer

# Context graphs (projects)
dkg context-graph create <id>            # create a local context graph
dkg context-graph register <id>          # register an existing CG on-chain (unlocks VM)
dkg context-graph invite <id> <peer>     # invite a peer to a context graph
dkg context-graph list                   # list subscribed context graphs
dkg context-graph info <id>              # show context-graph details
dkg context-graph agents <id>            # list agents in the CG allowlist
dkg context-graph request-join <id>      # request to join a curated CG
dkg context-graph approve-join <id>      # approve a pending join request
dkg context-graph subscribe <id>         # subscribe to a CG without creating it

# Assertions (Working Memory drafts)
dkg assertion import-file <name> -f <file> -c <cg>   # import a document into WM
dkg assertion extraction-status <name> -c <cg>       # check document extraction status
dkg assertion query <name> -c <cg>                   # read assertion quads from WM
dkg assertion promote <name> -c <cg>                 # WM → SWM

# Shared memory (team-visible) and publishing
dkg shared-memory write <cg> ...         # write triples directly to SWM
dkg shared-memory publish <cg>           # SWM → Verified Memory (costs TRAC)
dkg publish <cg> -f <file>               # one-shot RDF publish to a context graph
dkg verify <batchId> --context-graph <cg> --verified-graph <id>  # propose M-of-N verification
dkg endorse <ual> --context-graph <cg> --agent <addr>  # endorse a published KA

# Querying
dkg query [cg] -q "<sparql>"             # SPARQL against a local context graph
dkg query-remote <peer> -q "<sparql>"    # query a remote peer over P2P
dkg sync                                 # catch up on data from peers
dkg subscribe <cg>                       # subscribe to a CG's gossip topics

# Async publisher (optional, for batching)
dkg publisher enable                     # enable the async publisher
dkg publisher enqueue <cg> ...           # enqueue a publish job
dkg publisher jobs                       # list publisher jobs
dkg publisher stats                      # publisher throughput stats

# Code & memory indexing
dkg index [directory]                    # index a code repo into the dev-coordination CG
dkg wallet                               # show operational wallet addresses & balances
dkg set-ask <amount>                     # set the node's on-chain ask (TRAC per KB·epoch)

# Identity & auth
dkg auth show                            # show the current API auth token
dkg auth rotate                          # generate a new auth token
dkg auth status                          # show whether auth is enabled

# Framework adapters & MCP wiring
dkg openclaw setup                       # install & configure the OpenClaw adapter
dkg hermes setup                         # install & configure the Hermes adapter
dkg mcp setup                            # register the MCP server with Cursor / Claude Code / Claude Desktop / Windsurf / VSCode + Copilot / Cline
dkg mcp serve                            # run the MCP server on stdio (invoked by the client; not run manually)

# Community integrations (registry: OriginTrail/dkg-integrations)
dkg integration list [--tier community]  # default tier filter is `verified`+
dkg integration info <slug>              # show details for one entry
dkg integration install <slug>           # install cli/mcp kind; --allow-community for community-tier entries

# Update / rollback
dkg update [--check] [--allow-prerelease]  # update node software
dkg rollback                               # roll back to previous version

Run dkg <command> --help for per-command options.

---

Typical use cases

1. Run a local knowledge node

Start a local daemon, open the UI, write RDF, and query it back.

2. Give agents shared memory

Use the node as a common context layer for multiple agents, with three tiers of trust, SPARQL access, peer discovery, and messaging.

3. Build a DKG-enabled app

Use the node APIs and packages to publish Knowledge Assets, query data, and coordinate through context graphs.

4. Integrate existing agent frameworks

Use adapters for OpenClaw, ElizaOS, Hermes, or your own Node.js / TypeScript project.

---

Benchmarking

Benchmarking docs live in BENCHMARKING.md. The current suite covers DKG publish/get and memory-layer flows:

• get/read retrieval
• synchronous publish with finalization
• asynchronous publish enqueue and finalization
• upload payload to local working memory
• lift local working memory to shared working memory

Run the main local benchmark workflow:

pnpm bench
pnpm bench:html
pnpm bench:analysis
pnpm bench:profile

The benchmark matrix uses generated payload sizes of 10kb, 100kb, 2mb, and 200mb. Use DKG_ESBENCH_PAYLOAD_SIZES=10kb or DKG_ESBENCH_PAYLOAD_SIZES=200mb to run a focused subset.

Generated reports are written under bench/results/. The combined ESBench HTML report is bench/results/latest.html; per-flow HTML pages are under bench/results/publish-async-get/. CPU profiles, flame graphs, and per-method analysis reports are under bench/results/profiles/, including method-analysis.latest.html for the invoked-method timing breakdown.

---

Setup guides

Guide	Use it when
MCP Setup	You want Cursor / Claude Code / Claude Desktop / Windsurf / VSCode + Copilot / Cline to use DKG as memory
Join the Testnet	You want a full node setup and first publish/query flow
OpenClaw Setup	You want OpenClaw to use DKG as memory/tools
Hermes Setup	You want Hermes Agent to use DKG as memory/tools
ElizaOS Setup	You want ElizaOS integration
Custom agent Setup	You are wiring an agent framework not covered above
Testnet Faucet	You need Base Sepolia ETH and TRAC

---

Testnet Funding

A DKG testnet node needs Base Sepolia ETH (to pay gas for on-chain operations) and test TRAC (for staking and publishing). The Origin Trail testnet faucet hands out both in a single API call, so first-setup paths auto-fund your node's first three wallets when a faucet is configured in the network config.

Three entry points cover the common flows:

• Manual install (dkg init) — on testnet, dkg init auto-funds the node's wallets when network.faucet.url is set (the default for the bundled testnet config).
• OpenClaw adapter (dkg openclaw setup) — runs the same funding step on first setup. Pass --no-fund to skip it (for pre-funded wallets, CI, or offline runs).
• Direct API / custom scripts — the full request/response shape, idempotency semantics, and error codes live in docs/setup/TESTNET_FAUCET.md.

Faucet calls are best-effort: a failed call logs a ready-to-paste curl block and setup continues. The node is usable without funding — you just can't publish or stake until it's topped up. Rate limits and error codes are documented in the faucet reference.

If the faucet is unreachable and you need ETH only, docs/setup/JOIN_TESTNET.md lists alternate Base Sepolia ETH faucets (Alchemy, Coinbase).

---

Architecture

        Agents / CLI / Apps
               │
               ▼
          ┌─────────┐
          │ DKG Node│   Daemon + HTTP API + Dashboard UI
          └────┬────┘
   ┌────────┬──┴────┬──────────┐
   ▼        ▼       ▼          ▼
  P2P    Storage   Chain     Memory
 Network  (RDF,   (Finality  (WM / SWM /
 (gossip, SPARQL) & KA NFTs)    VM layers)
  sync)

At a high level:

• P2P network handles discovery, gossip relay, and node-to-node communication
• Storage holds RDF data across all three memory layers and serves SPARQL queries
• Chain handles finalization, Knowledge Asset NFT registration, and M-of-N consensus verification
• Memory model coordinates the WM → SWM → VM lifecycle for every assertion
• Node UI exposes local exploration, project/context-graph management, and SPARQL tooling
• CLI handles lifecycle, publish/query, auth, updates, and logs

---

Concepts

Knowledge Asset (KA)

A unit of published knowledge: RDF statements plus Merkle proof material and optional private sections.

Knowledge Collection (KC)

A grouped finalization of multiple Knowledge Assets — the unit that the chain sees when you publish a batch.

Context Graph (project)

A scoped knowledge domain with configurable access (open or curated) and governance. The node UI calls these "projects". Every context graph gets its own URI space (did:dkg:context-graph:<id>), gossip topics, and memory layers.

Sub-graph

A named partition within a context graph. Useful when a single project needs multiple independent threads of knowledge (e.g. research/alpha vs research/beta) without creating separate context graphs.

Assertion

A named RDF graph you write into first (always in Working Memory). Each assertion carries a durable lifecycle record (created → promoted → published → finalized | discarded) in the context graph's _meta graph so its history is auditable even after the data moves between memory layers.

Working / Shared Working / Verified Memory

The three memory layers — see The three memory layers above. Every assertion flows through them in order.

Agent

An authenticated identity on a node. Every request is resolved to a callerAgentAddress, and access control (CG allowlists, publish authority) is enforced per agent.

---

API authentication

Node APIs use bearer token auth by default.

The token is created on first run and stored in:

~/.dkg/auth.token

Example:

TOKEN=$(dkg auth show)
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:9200/api/agents

The full node API surface (assertions, memory layers, context graphs, file ingestion, querying) is documented in packages/cli/skills/dkg-node/SKILL.md — this is the canonical reference loaded by any DKG-aware agent.

---

Updating and rollback

DKG uses blue-green slots for safer upgrades and rollback.

dkg update --check
dkg update
dkg update 10.0.0-rc.2 --allow-prerelease
dkg rollback

Release workflow details are documented in RELEASE_PROCESS.md.

---

Repository layout

This is a pnpm + Turborepo monorepo.

Core packages

@origintrail-official/dkg                    CLI and node lifecycle (daemon, HTTP API, file store)
@origintrail-official/dkg-core               P2P networking, protocol, crypto, memory model types
@origintrail-official/dkg-storage            Triple-store interfaces and adapters
@origintrail-official/dkg-chain              Blockchain abstraction
@origintrail-official/dkg-publisher          Publish and finalization pipeline (SWM → VM)
@origintrail-official/dkg-query              Query execution and retrieval
@origintrail-official/dkg-agent              Identity, discovery, messaging, wallet keys
@origintrail-official/dkg-node-ui            Web dashboard, chat memory, SPARQL explorer
@origintrail-official/dkg-graph-viz          RDF visualization
@origintrail-official/dkg-evm-module         Solidity contracts and deployment assets
@origintrail-official/dkg-network-sim        Multi-node simulation tooling
@origintrail-official/dkg-attested-assets    Attested Knowledge Asset protocol components
@origintrail-official/dkg-epcis              EPCIS → RDF supply-chain adapter
@origintrail-official/dkg-mcp                MCP server for Cursor / Claude Code / coding agents

Adapters and apps

@origintrail-official/dkg-adapter-openclaw        OpenClaw gateway bridge
@origintrail-official/dkg-adapter-elizaos         ElizaOS plugin (embedded DKGAgent)
@origintrail-official/dkg-adapter-hermes          Hermes Agent (Python memory provider + TypeScript setup/client helpers)
@origintrail-official/dkg-adapter-autoresearch    AutoResearch integration

---

Specs

Document	Scope
Part 1: Agent Marketplace	Protocol and agent interaction flows
Part 2: Agent Economy	Incentives, rewards, and trust economics
Part 3: Extensions	Extended capabilities and roadmap
Attested Knowledge Assets	Multi-party attestation model
Trust Layer	Endorsement and verification trust levels
Verified KAs	On-chain verification lifecycle
Capacity & Gas	Node capacity and gas accounting

---

Current maturity

DKG V10 is a release candidate on the testnet. Core capabilities are implemented and exercised:

• Three-layer memory model (WM → SWM → VM) with assertion lifecycle tracking
• Context graphs with open and curated access policies, on-chain participant allowlists
• P2P networking, gossip-based sync, and per-CG catch-up
• RDF publish/query flows with Merkle proofs and M-of-N verification
• File ingestion pipeline (PDF, DOCX, HTML, Markdown) into WM assertions
• Agent discovery and encrypted messaging
• Dashboard UI with chat memory, SPARQL explorer, project management
• Framework adapters for OpenClaw, ElizaOS, Hermes, AutoResearch
• MCP server for Cursor / Claude Code / other coding assistants
• Community integrations registry (dkg integration list|info|install) with install-time provenance verification for CLI-kind installs
• Blue-green update and rollback flow

Expect rapid iteration and breaking changes. Not yet recommended for production workloads.

---

Development

Clone the repo and use pnpm (v10+) with Node.js 22+ to work across all workspace packages:

pnpm install                                     # install all workspace deps
pnpm build                                       # compile packages and the Node UI bundle
pnpm test                                        # run the full test suite
pnpm test:coverage                               # tests + tier-based coverage gates (all packages)
pnpm --filter @origintrail-official/dkg test     # run tests for a single package

Tier-based thresholds (TORNADO / BURA / KOSAVA) and Solidity lcov checks are documented in docs/testing/COVERAGE.md.

---

Contributing

We welcome contributions — bug reports, feature ideas, and pull requests.

• Open an issue for bugs or feature requests
• Build a DKG integration — submit to the integrations registry (see CONTRIBUTING.md and the dkg-hello-world template)
• Join Discord for questions and discussion
• Releases