Storage Model

Storage Model

AgentCTX uses a hybrid storage architecture: a local content-addressed store for offline operation and SurrealDB for persistent, queryable storage.

Content-Addressed Store (CAS)

Every piece of content is stored by its SHA-256 hash:

.context/objects/
├── a1/
│   └── a1b2c3d4...   ← SHA-256 of content
├── e5/
│   └── e5f6g7h8...
└── i9/
    └── i9j0k1l2...

Objects are stored in 2-character prefix subdirectories (like Git’s object storage) for filesystem performance at scale.

Benefits:

• Deduplication — identical content is stored once, regardless of how many agents reference it
• Integrity — content can’t be modified without changing its hash
• Portability — objects are self-contained and can be synced to remote stores

Content Registration Protocol

Static content (tool schemas, documentation chunks, skill definitions) is registered once and referenced by hash. This is the mechanism behind AgentCTX’s 99.9% savings on static content:

First session:     +s "deploy" "Steps: lint, test, build, deploy" → stored as SHA-256
Subsequent sessions: Reference by hash → 3 tokens instead of 50+

SurrealDB

SurrealDB v3 is the primary persistent database, providing:

Feature	Use
Document store	Memory and knowledge storage
Graph relations	Memory relationships (RELATE edges)
HNSW vectors	Semantic similarity search (memory + knowledge via surrealqlNative)
LIVE SELECT	Real-time subscriptions
Computed fields	Automatic decay scoring
Functions	Server-side fn::compute_decay

Schema

AgentCTX ships with 10 SurrealQL schema files, loaded at startup by the surrealdb-init service:

Schema	Purpose
memory.surql	Memory table, HNSW index, CHANGEFEED 7d, fn::compute_decay, computed decay_score, ASYNC events
knowledge.surql	Knowledge table, HNSW index, CHANGEFEED 7d, full-text search
graph.surql	Relation tables: related, grounds, promoted_by (TYPE RELATION)
security.surql	Row-level security permissions, DEFINE ACCESS TYPE RECORD
telemetry.surql	DEFINE SEQUENCE telemetry_seq, telemetry table
api.surql	DEFINE API endpoints: /memory/search, /knowledge/search, /health
credentials.surql	Credential vault table, composite unique index, admin-only PERMISSIONS
change-set.surql	Change-set tracking table
process-group.surql	Process group state table
process-archive.surql	Process archive table

Dual-Path Architecture

Modules that interact with SurrealDB use a dual-path design:

surrealqlNative = true  → SurrealQL emitter (direct queries)
surrealqlNative = false → TypeScript wrapper (legacy fallback)

The SurrealQL-native path is the default in production. The TypeScript path remains as a fallback.

Edge Sync

The storage module supports syncing objects to remote stores for distributed deployments:

• Object sync — CAS objects replicated across nodes
• Ref sync — reference pointers synchronized
• Conflict resolution — content-addressed design means no merge conflicts

SurrealML

SurrealDB’s built-in ML capabilities are used for:

• Automatic decay scoring (computed fields)
• HNSW nearest-neighbor search on embedded memories
• Server-side aggregation functions

WASM Contracts

Memory write operations can be enforced by WASM contracts (crates/memory-wasm/), providing:

• Write gate validation before storage
• Schema enforcement at the edge
• Cross-platform consistency (same logic in Node.js and browser)

Next

• Security Model → — the 8-layer defense-in-depth
• Gateway & Routing → — how requests reach storage