Token Optimization with GCF and Long-Term Memory with MemPalace

Every token a language model reads — system prompt, tool schemas, prior turns, and tool responses — is billed and counted against the context window before the model produces a single word of output. For a network automation agent that queries dozens of devices and carries a large skill inventory, two costs dominate: the wire cost of MCP tool responses returning on every call, and the standing cost of loading skills and tool schemas into each turn. NetClaw attacks the first with Graph Compact Format (GCF), a wire encoding tuned for graph-shaped network data, and complements short-lived context with MemPalace, a persistent semantic-plus-temporal memory store. This section covers both, and the deliberate division of labor between MemPalace and GAIT.

The Token-Budget Context Explosion

NetClaw's monolithic architecture loads roughly 194 skills every turn, alongside 37–52 MCP servers whose schemas amount to hundreds to thousands of tool definitions; the README's platform inventory cites 113 MCP integrations and 191 skills. Because context utilization is prompt_tokens / model_max_context, this manifest consumes a large fraction of the window before any user request is added — a "context explosion" in which every turn pays for a mostly-unused tool-schema payload. This is the same dynamic industry research identifies as the dominant scaling bottleneck for multi-tool agents. NetClaw addresses it on two fronts: the iN2N federation (covered elsewhere) reduces the standing schema cost by distributing skills across focused member claws under a lean Border Claw, while GCF reduces the per-response cost of the data flowing back from those tools.

GCF: Graph Compact Format

All MCP server responses pass through GCF, yielding 55–83% token savings on network data. GCF auto-detects graph-shaped data — devices plus links or sessions — and switches to a graph profile that replaces repeated identifiers with local IDs and expresses relationships as compact edge arrows rather than verbose nested JSON objects.

Two further mechanisms compound the savings across a conversation. Session-level deduplication tracks symbols already sent on prior calls and omits them on repeat, reaching 91% savings by call 3. Delta encoding sends only what changed on a re-query, reaching 99% savings when little has moved between polls.

flowchart TD
    A["Raw MCP JSON response"] --> B{"Graph-shaped data?"}
    B -->|"Yes"| C["Graph profile: local IDs + edge arrows"]
    B -->|"No"| G["Generic compaction"]
    C --> D["Session dedup: drop previously-sent symbols"]
    G --> D
    D --> E["Delta encoding: changes only"]
    E --> F["Compact wire output (55-83% smaller)"]
    B -.->|"Encoding error"| H["JSON fallback"]
    C -.->|"Encoding error"| H

Conceptually, a raw response listing devices and their BGP sessions collapses from repeated fully-qualified objects into a symbol table plus arrows:

# Before (JSON, per session, repeated verbatim each call)
{"device":"router-core-01","neighbor":"router-edge-02","state":"Established","asn":65001}

# After (GCF graph profile: local IDs + edge, symbols deduped across calls)
1=router-core-01 2=router-edge-02
1 -[bgp:Established asn65001]-> 2

GCF is controlled by the NETCLAW_GCF_MODE environment variable and falls back to standard JSON on any encoding error. It remains experimental: some servers (for example Datadog and AWS) return non-graph data that falls back to JSON, and the mode can be disabled entirely if problems arise.

# Full encoding: graph profile where possible, generic elsewhere (default)
export NETCLAW_GCF_MODE=full

# Graph profile only — best for device/link/session topologies
export NETCLAW_GCF_MODE=graph

# Generic compaction without graph-shape detection
export NETCLAW_GCF_MODE=generic

# Disable GCF; emit standard JSON (use if a server misbehaves)
export NETCLAW_GCF_MODE=off

Token accounting is not left to estimation guesswork: every interaction reports input/output tokens, USD cost, and GCF savings with per-session and per-tool breakdowns, powered by Anthropic's count_tokens() API with a local estimation fallback. The utilities live in src/netclaw_tokens/.

MemPalace: ChromaDB Semantic Store and Temporal Knowledge Graph

Where GCF optimizes the transient context of a single conversation, MemPalace provides durable memory across sessions. It combines two complementary substrates. A ChromaDB semantic store holds embeddings — numeric vectors of meaning — in collections with metadata, enabling similarity search that recalls relevant past experience by meaning rather than keyword, and persists on disk so memory survives restarts. Alongside it, a temporal knowledge graph records network facts — upgrades, peer changes, maintenance windows — as time-aware tuples bound to validity windows, so the agent can answer "what was true at time T," trace how a topology evolved, and back each answer with an explicit, provenance-tagged path. MemPalace adds cross-domain navigation between "wings" and per-agent diaries on top of these stores.

This hybrid of vector recall plus temporal graph is the emerging best practice for agent memory: the vector index gives broad semantic recall over unstructured experience, while the temporal graph gives precise, explainable reasoning over dynamic, relational, time-sensitive facts that a pure embedding store cannot reliably enforce. One limitation matters operationally: MemPalace updates its semantic index only at session end, so a mid-session crash loses facts learned during that session — though the actions taken are still captured by GAIT.

GAIT vs MemPalace: What vs Why

NetClaw runs two memory systems with distinct jobs, and the README draws the line sharply: "GAIT records what happened. MemPalace remembers why." GAIT is the append-only git audit trail of actions taken — the immutable record of what was executed. MemPalace holds the reasoning and context behind those actions — the maintenance-window rationale, the upgrade history, the peer-change context — the searchable, temporally-scoped why. The two are complementary rather than redundant: GAIT answers accountability and replay questions from an execution log, while MemPalace answers understanding questions from structured semantic facts. The session-end caveat is precisely where the split earns its keep — even if MemPalace loses a session's learned "why," GAIT preserves the "what."

flowchart TD
    A["Agent action taken"] --> B["GAIT: append-only git audit trail"]
    A --> C["MemPalace: reasoning and context"]
    B --> D["What happened (execution record)"]
    D --> E["Survives mid-session crash"]
    C --> F["ChromaDB semantic store"]
    C --> G["Temporal knowledge graph"]
    F --> H["Why (indexed at session end)"]
    G --> H

References