Your corpus stays with its keeper.

Run a data node beside your agent: immutable records, content-addressed blobs, SQLite full-text search, provenance, and an append-only change feed. The base node reads local indexes only and advertises peer_sync: false; the optional explicit-pull wrapper advertises only its bounded agent-data-sync/v1 profile.

AgentTool may help an agent find or call a node. It does not have to own the raw bytes.

Two related layers, two separate jobs

sources ──collect──> your @agenttool/data node
                         ├── SQLite metadata + FTS
                         ├── content-addressed local blobs
                         └── dedicated node bearer

optional @agenttool/adds ──> encrypted Blocks + signed control records
@agenttool/sdk at.data ──HTTP──> that node's URL
api.agenttool.dev       ──X────> no implicit raw-data path

Run the local reference node

The reference node requires Bun because it uses bun:sqlite and Bun.serve. The CLI creates a default private collection and local .agent-data/ directory. Use a dedicated random node token. The SDK configures that token separately and never implicitly forwards AT_API_KEY; a caller can still explicitly supply the same value and should not do so.

bun add https://docs.agenttool.dev/packages/v1/@agenttool/data/0.3.1/agenttool-data-0.3.1.tgz
export AGENT_DATA_NODE_TOKEN='<dedicated-random-node-token>'
bunx --bun --no-install --package @agenttool/data agenttool-data --root=./.agent-data

# agent-data/v1 node ... listening at http://127.0.0.1:7742

Check a node with the executable profile

agenttool-data doctor, introduced in @agenttool/data@0.2.0 and retained through 0.3.1, is a bounded black-box runner for agent-data/v1-slice1-http. Its JSON report follows the public conformance report schema and validates only the observed HTTP profile at that target and time; it is not a security certification, durability proof, or secure-erasure claim.

# Public discovery and synthetic auth-boundary probes
bunx --bun --no-install --package @agenttool/data agenttool-data \
  doctor http://127.0.0.1:7742 --profile public

# Supply a dedicated node bearer through stdin, never argv
printf '%s' "$AGENT_DATA_NODE_TOKEN" | \
  bunx --bun --no-install --package @agenttool/data agenttool-data \
    doctor http://127.0.0.1:7742 --profile read --token-stdin

Discover, collect, and query

# Public capability truth
curl http://127.0.0.1:7742/.well-known/agent-data

# Collect one local text item
curl -X POST http://127.0.0.1:7742/v1/data/collect \
  -H "Authorization: Bearer $AGENT_DATA_NODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "default",
    "collector_id": "text",
    "input": { "text": "Local-first agents keep their corpus close." }
  }'

# Query the node-local FTS index
curl -X POST http://127.0.0.1:7742/v1/data/query \
  -H "Authorization: Bearer $AGENT_DATA_NODE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "collections": ["default"], "text": "corpus", "consistency": "local" }'

Use the optional encrypted-object plane

@agenttool/adds is the experimental reference implementation of the separate adds/v0.1 working draft. It can encrypt, address, sign, store, and share exact objects offline through memory, filesystem, or caller-provided stores. A CID and signature prove bytes and key control; they do not prove a claim is true or that a provider will retain the object.

bun add https://docs.agenttool.dev/packages/v1/@agenttool/adds/0.2.3/agenttool-adds-0.2.3.tgz

import { AgentData, MemoryBlockStore, generateIdentity } from "@agenttool/adds";

const data = new AgentData({
  identity: generateIdentity("did:example:agent"),
  store: new MemoryBlockStore(),
});

const published = await data.put("private agent context", {
  mediaType: "text/plain; charset=utf-8",
});

console.log(published.ref); // ciphertext/control-document CID reference

ADDS 0.2.3 requires @noble/ed25519@^2.3.0, matching the verifier's Point API, and propagates programming/environment faults instead of misreporting them as an invalid signature. Immutable 0.2.2 could resolve Noble 2.2.3 and reject a valid signed object; that was a fail-closed availability defect, not acceptance of an invalid signature. The current JavaScript maps embed their TypeScript sources and the tarball omits declaration maps rather than pointing at an excluded source tree.

Archive committed Git history across named zones

@agenttool/repo-archive composes a self-contained Git bundle with ADDS encryption, signed archive records, and per-zone read-back drills. A zone is counted only after that zone alone decrypts, validates, restores into a fresh no-checkout repository, verifies the bundle, and passes strict git fsck.

npm install --save-exact @agenttool/repo-archive@0.1.0-dev.0 @agenttool/adds@0.2.3
npx agent-repo-archive simulate --repo /absolute/path/to/clean/repository

Pull encrypted pages from an explicit peer

@agenttool/data-sync composes the data node and ADDS packages. It discovers no peers and accepts no caller-supplied peer URL or credential: the operator configures the exact origin, source node and publisher keys, page-only bearer, collection allow-list, and recipient key. Verified records are retained in the destination node for offline query.

bun add \
  https://docs.agenttool.dev/packages/v1/@agenttool/adds/0.2.3/agenttool-adds-0.2.3.tgz \
  https://docs.agenttool.dev/packages/v1/@agenttool/data/0.3.1/agenttool-data-0.3.1.tgz \
  https://docs.agenttool.dev/packages/v1/@agenttool/data-sync/0.1.2/agenttool-data-sync-0.1.2.tgz

import { DataSyncService } from "@agenttool/data-sync";

Data-sync 0.1.2 peers on repaired ADDS ^0.2.3 and data ^0.3.1. It rejects imported objects whose signed manifest lacks the exact sync media type or schema, requires the reference node's strict uppercase, non-leap-second RFC 3339 change-time profile to match the decrypted record or tombstone time, and permits an explicit plaintext page up to the default data-node 10 MiB record ceiling with 32 MiB encoded-response headroom. The ordinary requested page remains 1 MiB; larger pages are still deliberate. Its shipped JavaScript maps embed TypeScript text and omit declaration maps.

Use at.data with separate configuration

The SDK integration has two independent configuration fields. apiKey authorizes the hosted AgentTool project. dataNode.token authorizes the node you selected. The SDK never implicitly substitutes or forwards one as the other.

import { AgentTool } from "@agenttool/sdk";

const at = new AgentTool({
  apiKey: process.env.AT_API_KEY,
  dataNode: {
    baseUrl: "http://127.0.0.1:7742",
    token: process.env.AGENT_DATA_NODE_TOKEN,
  },
});

const hits = await at.data.query({
  collections: ["default"],
  text: "local-first",
  consistency: "local",
});

from agenttool import AgentTool
import os

at = AgentTool(
    api_key=os.environ["AT_API_KEY"],
    data_node_url="http://127.0.0.1:7742",
    data_node_token=os.environ["AGENT_DATA_NODE_TOKEN"],
)

hits = at.data.query(
    collections=["default"],
    text="local-first",
    consistency="local",
)

For data-only use with no AgentTool account, instantiate the exported TypeScript or Python DataClient directly with the node URL and token. It does not require AT_API_KEY.

Reference node HTTP surface

Slice 1 capability truth

Protocol and wire references

• AGENT-DATA-PROTOCOL.md — normative agent-data/v1 collection, record, query, and change contract.
• ADDS-0.1-DRAFT.md — experimental encrypted-object working draft, with a machine-readable schema and pinned vectors.
• AGENT-REPO-ARCHIVE.md — encrypted committed-history archive overview, with the normative 0.1 profile, machine-readable schema, and pinned vectors.
• Memory — hosted, project-bearer-gated memory records; a separate surface from raw local corpora.