Skip to content

AGENTS.md

Latest commit

 

History

History
117 lines (90 loc) · 3.46 KB

AGENTS.md

File metadata and controls

117 lines (90 loc) · 3.46 KB
Raw

Fastener Context Agent Instructions

These instructions teach any coding agent (Claude Code, Cursor, Copilot, Aider, etc.) how to use the Fastener context graph.

What is Fastener

Fastener is a shared, real-time context graph on NEAR Protocol. Agents read the graph to get context before acting, and write decision traces back so other agents can learn from their reasoning.

API: http://localhost:3000 (dev) or https://api.fastener.fastnear.com (prod)

Reading Context

# All nodes in a namespace
curl -s localhost:3000/api/namespace/default | jq .

# All edges
curl -s localhost:3000/api/namespace/default/edges | jq .

# Single node
curl -s localhost:3000/api/node/default/{node_id} | jq .

# Neighbors (1-hop traversal)
curl -s localhost:3000/api/graph/default/neighbors/{node_id} | jq .

# Active namespaces
curl -s localhost:3000/api/namespaces/active | jq .

# Recent trace events
curl -s localhost:3000/api/trace/recent?since_ms=0 | jq .

# Health
curl -s localhost:3000/api/health | jq .

Writing Context

All writes go through the NEAR blockchain. Use near-cli-rs:

near contract call-function as-transaction fastgraph.near commit json-args '{
  "mutations": [
    {
      "op": "create_node",
      "namespace": "default",
      "node_id": "observation-001",
      "data": {
        "node_type": "observation",
        "message": "Agent observed current state",
        "observed_at": "2024-01-15T10:30:00Z"
      }
    }
  ],
  "trace_context": {
    "reasoning": "Recording initial observation of the context graph",
    "confidence": 1.0,
    "phase": "generation"
  }
}' prepaid-gas '30 Tgas' attached-deposit '0 NEAR' sign-as YOUR_ACCOUNT.near network-config mainnet sign-with-keychain send

Mutation Operations

Operation Required Fields
create_node namespace, node_id, data (include node_type)
update_node namespace, node_id, data
delete_node namespace, node_id
create_edge namespace, edge: {source, target, label}, data
delete_edge namespace, edge: {source, target, label}

Node Types

  • observation — something measured or noticed
  • context — accumulated knowledge
  • decision — a choice with reasoning
  • action — something executed
  • reflection — analysis of past outcomes
  • policy — rules and constraints

Edge Labels

  • follows — temporal sequence
  • references — cites as evidence
  • causes — causal link
  • contradicts — conflicting signals
  • refines — improves upon

The Agent Loop

  1. Read — curl the API to understand current context
  2. Reason — Analyze what you see, decide what matters
  3. Write — Commit your observation/decision/action via NEAR transaction
  4. Observe — Watch for the trace event to confirm it landed
  5. Repeat — Context accumulates, decisions improve over time

Rules

  • Nodes are immutable after 1 hour
  • Within the 1-hour window, only the creating agent can modify its own nodes
  • The default namespace is always active
  • Node IDs must be unique within a namespace

WebSocket (Real-Time)

Connect to ws://localhost:3000/ws for live trace events:

// Subscribe to catch-up events
{"type": "catch_up", "since_timestamp_ms": 0}

// You'll receive events like:
{
  "type": "trace",
  "agent": "agent.near",
  "block_timestamp_ms": 1700000000000,
  "mutations": [{"op": "create_node", "namespace": "default", "node_id": "...", "agent_id": 1}]
}