@interego/core
Persistent, verifiable, federated memory for AI agents — owned by you, portable across runtimes, signed by construction.
Drop the MCP relay into any agent that speaks MCP (Claude Code, Cursor, Codex, Windsurf, Cline, Hermes, OpenClaw, …) and the agent gets context that survives sessions and machines, that other agents can read and verify, and that you control end-to-end.
// ~/.claude.json / .cursor/mcp.json / .codex/config.toml equivalent
{
"mcpServers": {
"interego": {
"url": "https://relay.interego.xwisee.com/mcp"
}
}
}
/mcp is the Streamable HTTP transport — a single endpoint that carries request, response, and notifications. It is the only MCP transport this relay serves. There is no HTTP+SSE fallback: MCP deprecated that transport in protocol revision 2025-03-26, and the relay's /sse path is a plain write-activity feed, not an MCP transport (see deploy/mcp-relay/OAUTH-SETUP.md).
The first tool call walks you through a passkey or wallet enrollment in the browser, mints your DID + pod, and issues a bearer token. Subsequent calls reuse the same identity from any device.
Adding the connector to ChatGPT or Claude.ai (web / mobile)
The hosted relay is exposed as a remote MCP server, so GUI clients can mount it without a config file. The same connector entry covers web and mobile — settings sync through your account.
ChatGPT (web or mobile)
- Open Settings → Connectors → Add custom connector. (Available on ChatGPT Pro, Team, and Enterprise; exact menu label and location vary by plan and platform.)
- Name it whatever you like, e.g.
Interego.
- URL:
https://relay.interego.xwisee.com/mcp
- Save. On first use, ChatGPT opens a browser tab for OAuth — enroll a passkey or connect a wallet there, then return to the chat.
- The same connector then works in the ChatGPT web app and the ChatGPT mobile app (iOS / Android), because connector settings sync through your OpenAI account.
Claude.ai (web or mobile)
- Open Settings → Connectors → Add custom connector (on some surfaces this appears as Configure connector in the conversation menu).
- URL:
https://relay.interego.xwisee.com/mcp
- Save. The OAuth flow opens in your browser — enroll a passkey or connect a wallet on first use.
- The same connector then covers Claude.ai on the web and the Claude mobile app, because connector settings sync through your Anthropic account.
Use /mcp — there is no second transport to fall back to. A client that cannot speak Streamable HTTP cannot reach this relay over MCP at all; /sse will not serve it (measured: tools/probe-sse-mcp-handshake-live.ts).
Status: reference implementation. Hosted on the maintainer's Railway project for evaluation. Self-host (examples/personal-bridge/) before you depend on it. The compliance + audit-trail work in this repo is infrastructure for SOC 2 / EU AI Act / NIST RMF evidence — it is not an attested control environment by itself.
L1 protocol: Last Call Working Draft (2026-05-16). Wire format and core vocabulary (iep: / ieh: / pgsl: / ie: / align:) are frozen for v1.0 pending Candidate Recommendation. Editors commit no breaking changes through 2027-05-16 without a deprecation cycle. See spec/STABILITY.md for the practical adopter-facing commitment, and spec/architecture.md for the normative spec. Second implementations (any language) are warmly welcomed — open an issue and we will work with you.
Author: Mark Spivey
License: MIT
The MCP surface above is a thin ergonomic wrapper on three pillars over one cryptographic root: typed context (Context Descriptors with seven facets, a composition algebra, modal status, iep:supersedes chains, the PGSL content-addressed lattice — the L1 protocol is Interego Protocol 1.0), verifiable identity (wallet-rooted DIDs, capability passports that survive infrastructure migration, attribute-based access control), and coordination (multi-axis attestation, federated saga transactions, Nostr-style p2p relays). Wrapped in NaCl envelopes, secp256k1 signatures, ZK commitments, IPFS anchoring. Federated across Solid pods by default.
The underlying surface is a small categorical kernel — eight verbs: mint, dereference, compose, act, restrict, extend, promote, decompose — exposed both as a TypeScript module (packages/core/src/kernel/) and as first-class MCP tools alongside the 27 named compatibility shims (publish_context, register_agent, pgsl_*, invoke_affordance, …). The stdio MCP server exposes these 8 verbs; the hosted relay is a superset, adding a ninth verb (reduce_chain) plus relay-only shims. The named tools' wire format is unchanged so existing connectors keep working; new clients can call the kernel verbs directly. See docs/ARCHITECTURAL-FOUNDATIONS.md §11 for the categorical structure realized by the kernel.
Quick start — pick the path that matches what you're doing
What products inherit
Anything built on Interego inherits five properties without writing them itself:
- Federation across organizations — agent identity is wallet-rooted; cross-pod sharing is per-graph and cryptographically scoped. Single-tenant assumptions don't bind you.
- Belief revision as a primitive —
iep:modalStatus (Asserted / Hypothetical / Counterfactual) plus iep:supersedes chains make claim history and reversal first-class.
- Composition on typed data — union / intersection / restriction / override operators on descriptors, plus PGSL meet/pullback at the atom layer, give structural — not heuristic — answers to "what do these views agree on."
- Identity portability — capability passports survive pod migrations, framework changes, and wallet rotations.
- Audit by construction — every action that goes through
publish_context produces a signed, timestamped, lineage-walkable descriptor. Regulatory frameworks with an L3 mapping (eu-ai-act:, nist-rmf:, soc2:) let compliance teams query that audit trail in their own vocabulary. The mappings are infrastructure for compliance evidence; they are not themselves an attestation that any deployment meets the standard.
The verticals under applications/ are intentionally separate packages, each demonstrating a different shape of product riding the substrate. The most product-shaped of the bunch — applications/organizational-working-memory/ — turns the substrate into a typed people / projects / decisions / follow-ups surface with per-source navigation isolated behind uniform verbs so the consuming agent's context never sees the per-source noise. The 10-minute quickstart brings it up via docker compose.
Recent additions
The protocol surface has grown substantially. Highlights:
-
Pilot verticals (dual-audience) — two verticals in applications/ are designated pilots for the dual-audience design discipline (docs/DUAL-AUDIENCE.md): every vertical has at least two first-class audiences (the protagonist whose data it is, and the institutional operator) and gives each its own affordances over the same descriptors. Learning (learner-performer-companion/ + lrs-adapter/) serves the learner / performer AND the enterprise edtech professional; the interop standards (IEEE LERS, ADL TLA, xAPI, W3C VC, Open Badges 3.0, IMS CLR 2.0) connect both audiences without either dictating the other. Organizational working memory (organizational-working-memory/) serves the knowledge worker / individual contributor AND the org-level operator. ABAC + per-graph share_with + aggregate-privacy queries are the bilateral substrate primitives.
-
Vertical-application examples (NOT first-party — emergent use cases on top of the protocol) — applications/ holds reference implementations of how the protocol can be composed for specific industries / domains. They are separate from Interego itself: the generic personal-bridge and hosted relay don't load them. Each vertical has:
- A first-principles affordance declaration (
applications/<vertical>/affordances.ts) — the spec-level artifact. A generic Interego agent discovers + invokes vertical capabilities via descriptors using only the protocol's own primitives. No vertical-specific client code needed at the agent.
For dated detail see CHANGELOG.md.
Hosted vs self-hosted: which path is right for you
Two complementary deployment paths. Both are open-source; both federate; pick by what you need.
| Path | What it is | Best for |
|---|
| Hosted reference (relay.interego.xwisee.com) | Publicly-hosted Railway deployment (images on ghcr.io). OAuth-gated MCP at /mcp exposing 9 categorical substrate verbs — the local stdio server's 8 (mint, dereference, compose, act, restrict, extend, promote, decompose) plus reduce_chain — alongside the 27 compatibility shims for the named-tool surface (publish_context, discover_context, register_agent, invoke_affordance, etc.) and additional relay-only shims. The kernel verbs are the substrate's irreducible primitives; the shims are particular compositions of those primitives. Every response is JSON-LD with hydra:Operation affordances and conformsToShape pointers; SHACL shapes graph at /.well-known/shacl-shapes. The relay is a superset of the local stdio MCP server, not an identical surface. Per-user pods, claude.ai/ChatGPT custom-connector compatible. Operated by the maintainer as a reference instance. | Evaluation without running your own infrastructure. You still enroll an identity (passkey / wallet — 2 min via the landing page) and wire up an MCP client; what you skip is hosting the relay / pod / identity server yourself. See the first-hour walkthrough. Tier 3 substrate. Vertical applications are NOT bundled into this relay — they deploy independently per the verticals doc. |
Personal bridge (examples/personal-bridge/) | A small Node binary you run on your own infrastructure (laptop / Pi / NAS / Tailscale-exposed home server). Embedded relay, MCP at /mcp exposing core p2p tools (publish_p2p, query_p2p, share_encrypted, query_my_inbox), REST + admin UI. | Self-hosting + local-first. Your data on your network; one URL all your devices; sharing is per-publish () or per-bridge (mirror to public Nostr relays via ). Tier 5 substrate. Vertical bridges run alongside this generic bridge on different ports — see . |
They federate when you need it. A user on the hosted relay can share with a personal-bridge user via cross-pod E2EE share (Tier 4) or via a common public Nostr relay (Tier 5 with WebSocketRelayMirror). Identity stays the same — your wallet's secp256k1 key is your identity on every surface.
Recommendation: start on the hosted instance to evaluate; graduate to the personal bridge when you want self-hosting; federate between them whenever it's useful. The hosted instance is not the recommended path for production — the personal bridge is. The hosted instance exists so the protocol is approachable; the bridge exists so it's owned.
The hosted relay is intentionally not adding P2P endpoints. Re-centralizing what's deliberately decentralized would defeat the point. P2P lives in your bridge.
Features
For runnable demos of the trust substrate (auditor, ERC-8004 T0-T2, x402, affordance bridge, federation health check) see examples/SEMANTIC-ALIGNMENT-README.md.
Storage & content
- End-to-end encrypted pod content. Every named graph is wrapped in an
X25519 + XSalsa20-Poly1305 envelope with one wrapped key per authorized agent. CSS / object storage / IPFS pinning services see only ciphertext. Descriptor metadata (facets, manifest entries) stays plaintext so federation queries still work. See docs/e2ee.md.
- Persistent pod state. Solid pod storage is the content-addressed PGSL lattice over managed PostgreSQL (a custom CSS
DataAccessor, integrations/pgsl-css-accessor). State survives restarts and is no longer bound to a network-file volume. CSS itself still runs at one replica: moving off the incoherent AzureFile volume removed the storage blocker to scaling out, but not the locker one — CSS's RedisLocker.clearLocks() does KEYS <prefix>* + DEL over the whole namespace on every replica boot and shutdown, with namespacePrefix defaulting to "", so a second replica deletes the first's live locks. See the rationale in integrations/pgsl-css-accessor/config/pgsl-server-redis.json, which is what an operator reads at the moment they scale.
- Cleartext mirror for federation reasoning. Cross-descriptor relationships inside encrypted payloads —
iep:revokedIf, prov:wasDerivedFrom, iep:supersedes, dct:conformsTo — are extracted at publish time and threaded onto the cleartext descriptor so federation readers evaluate lineage, supersession, and schema conformance without decryption keys. One consolidated helper (normalizePublishInputs) runs on every publish path.
Hypermedia & capabilities
- Hypermedia-native data products. Every descriptor self-describes its graph payload via a single RDF block that is simultaneously
iep:Affordance, ieh:Affordance, hydra:Operation, and dcat:Distribution. Works with DCAT catalogs, Hydra clients, and the affordance-bridge resolver without Interego-specific code.
- Runtime affordance-to-tool resolution. An agent walks the pod's manifest, enumerates
iep:affordance blocks by iep:action, and invokes any declared capability without the harness pre-registering it. Invocations publish back as descriptors with prov:wasDerivedFrom citing the source affordance — discovered capabilities carry full provenance. See examples/affordance-bridge.mjs.
Identity & trust
- Per-surface agents, auto-detected. Each client (Claude Code, Claude Desktop, Claude Mobile, ChatGPT, Cursor, Codex, Windsurf, …) registers as its own
iep:AuthorizedAgent with its own did:web identity and X25519 keypair. The relay maps the OAuth client_name to a surface slug automatically; unknown clients get their slugified name, never a silent fallback.
- Cross-pod selective sharing.
publish_context(..., share_with: ["did:web:...", "acct:[email protected]"]) resolves handles via DID / WebFinger, pulls target agents' keys, adds them as envelope recipients on that one graph. Per-graph; no pod-level ACL change.
- Decentralized auth — no passwords, no user-claimable identifiers. SIWE (ERC-4361), WebAuthn passkeys, or
did:key Ed25519 signatures. userId is derived from the first credential (u-pk-<hash> / u-eth-<addr> / u-did-<hash>). Identity server is a stateless DID resolver + signature verifier; user auth state lives in <pod>/auth-methods.jsonld. See deploy/identity/AUTH-ARCHITECTURE.md.
- ERC-8004 progressive support. T0 federation-native attestations; T1 ECDSA-signed (secp256k1 via ethers.js); T2 IPFS-pinned + signed EIP-1559 transaction against the Reputation Registry. T0 readers parse T1+T2 by ignoring the additive fields — no forking.
- x402 payment integration. HTTP-402 challenge → EIP-191 signed authorization → retry with
X-Payment → 200 with tx hash. Real signatures + nonce enforcement + replay detection. Production settlement is one swap away (EIP-712 transferWithAuthorization + x402.org facilitator).
Discovery
effective_at interval-contains semantics. discover_context(..., effective_at: "...") returns only descriptors whose validity interval contains the given instant — the "what's valid right now?" query, distinct from endpoint-only filters.- Composable auditing. Structural auditor (vocabulary × modal × independence × derivation) + cross-auditor consensus + per-issuer reputation aggregator. Every audit is itself a descriptor conforming to
audit-result-v1; monitoring lives inside the system being monitored.
Ontology & protocol discipline
- Twenty formal ontologies covering L1 protocol (
iep:, ieh:, pgsl:, ie:, align:), L2 architecture patterns (hyprcat:, hypragent:, abac:, registry:, passport:), L3 implementation/domain (hela:, sat:, cts:, olke:, amta:, code:), L3 regulatory mappings (eu-ai-act:, nist-rmf:, soc2:), L3 complexity-aware vocabulary (wks:). See docs/ns/README.md. All terms enforced by CI lint.
- CI ontology-lint gate.
tools/ontology-lint.mjs scans TS source for <prefix>:<Term> emissions and verifies each against its corresponding docs/ns/<prefix>.ttl. New code cannot land iep:NewType without a matching OWL declaration.
- CI derivation-lint gate.
tools/derivation-lint.mjs enforces that every L2/L3 ontology class has explicit L1 grounding (owl:equivalentClass / rdfs:subClassOf / iep:constructedFrom / declared primitive). The gate fails on the first ungrounded class, so "every L2/L3 class is grounded" is the enforced invariant; run npm run lint:derivation for the current count.
- Layering discipline (L1 protocol / L2 architecture / L3 implementation). See
spec/LAYERS.md. Namespace is the boundary contract — domain terms stay out of core namespaces.
- Conformance test suite (
spec/CONFORMANCE.md) defines L1 / L2 / L3 conformance levels with badge output. Third-party implementations can claim a level by passing the suite against their serialized output.
What It Does
Every Named Graph has context: who created it, when, under what interpretive frame, at what confidence, with what trust credential, through what causal model. Interego makes that context structured, composable, machine-readable, and cryptographically verifiable.
An AI agent (Claude Code, Codex, OpenClaw, etc.) produces a knowledge graph. This library wraps that graph with a Context Descriptor declaring:
| Facet | What it captures | W3C Alignment |
|---|
| Temporal | When is this valid? | OWL-Time, Dublin Core |
| Provenance | Who generated it, from what? | PROV-O |
| Agent | Which AI agent, on behalf of which human? | PROV-O, ActivityStreams |
| AccessControl | Who can read/write? | WAC |
| Semiotic | Asserted or hypothetical? At what confidence? | Peircean triadic semiotics |
| Trust | Self-asserted, attested, or cryptographically verified? | VC 2.0, DID Core |
| Federation | Where is this stored, how does it sync? | DCAT 3, Solid Protocol |
| Causal | What structural causal model governs this? | Pearl's SCM framework |
| Projection | How does this map to other vocabularies? | SKOS, Hydra |
Two agents can then compose their descriptors via set-theoretic operators (union, intersection, restriction, override) forming a bounded lattice — merging knowledge with full provenance chains preserved.
Architecture
The repo is an npm workspaces monorepo. The substrate kernel ships as
@interego/core. Anything that is a particular composition of
substrate primitives — Solid binding, PGSL realization (currently still
in core), affordance engine (currently still in core), ABAC, registry,
passport, compliance, ops, transactions, constitutional layer, p2p,
connectors, extractors, skills, privacy, security.txt — lives in its
own sibling @interego/* package. See docs/ARCHITECTURAL-FOUNDATIONS.md §12 for the substrate-vs-vertical line that motivates the split.
packages/
├── core/ @interego/core — the substrate kernel
│ └── src/
│ ├── model/ Typed ContextDescriptor + 7 facets +
│ │ composition algebra (HELA's typed-
│ │ hyperedge category + the 4 limit/
│ │ colimit operators).
│ ├── kernel/ The 8 categorical verbs (mint /
│ │ dereference / compose / act / restrict /
│ │ extend / promote / decompose).
│ ├── rdf/ Turtle / TriG / JSON-LD serialization,
│ │ RDF 1.2 helpers, parseTrig subject-
│ │ extraction parser, virtualized RDF layer.
│ ├── validation/ Shape conformance / SHACL primitives.
│ ├── sparql/ Standards-compliant SPARQL pattern
│ │ builders.
│ ├── crypto/ Abstract signing/verification + ZK
│ │ primitives. Ethers/nacl-backed wallet
│ │ impls ship here for now.
│ ├── naming/ L2 attestation-based naming.
│ ├── affordance/ iep:Affordance shape + OODA/BDI/Active-
│ │ Inference runtime (slated for split
│ │ into @interego/affordance-engine).
│ ├── solid/ Solid+LDP binding (slated for split
│ │ into @interego/solid).
│ ├── pgsl/ Grothendieck-fibration realization
│ │ (slated for split into @interego/pgsl).
│ └── compat.ts Back-compat re-exports from sibling
│ @interego/* packages.
├── abac/ Attribute-Based Access Control
├── compliance/ EU AI Act / NIST RMF / SOC 2 framework
│ reports + ECDSA-signed lineage walks
├── connectors/ Notion / Slack / Web source connectors
├── constitutional/ Self-amending policies
├── extractors/ PDF / JSON / CSV / HTML extractors
├── ops/ SOC 2 operational evidence builders
├── p2p/ Nostr-style relay-mediated federation
├── passport/ Capability-passport biography
├── privacy/ Pre-publish sensitivity screening
├── registry/ Public agent attestation registry
├── security-txt/ RFC 9116 body builder
├── skills/ agentskills.io ↔ iep:Affordance bridge
└── transactions/ Federated saga-style transactions
├── mcp-server/ Stdio MCP server — substrate tools (publish_context,
│ discover_context, get_descriptor, subscribe_to_pod,
│ register_agent, pgsl_*, federation, identity, …).
│ Top-level handler list lives in mcp-server/server.ts;
│ the deployed Streamable-HTTP relay (deploy/mcp-relay/) exposes
│ a smaller OAuth-gated subset for claude.ai connectors.
│ v0.5.0 ships system-level instructions, doc resources,
│ workflow prompts so connecting agents understand the
│ system without trial-and-error tool calls. Subscriptions
│ capped at CG_MAX_SUBSCRIPTIONS (default 32) per process;
│ unsubscribe_from_pod releases a slot.
├── deploy/ Dockerfiles, Railway service configs, identity server, relay
│ ├── identity/ WebID + DID + Ed25519 + WebFinger + bearer tokens + SIWE
│ ├── mcp-relay/ Streamable-HTTP bridge — v0.3.0 mirrors stdio discoverability
│ │ (instructions / doc resources / prompts) for claude.ai
│ │ and other web-based MCP clients
│ └── css-config/ Community Solid Server configuration
├── examples/ Runnable demos — emergence (vocabulary alignment,
│ mediator pullback, stigmergic colony, localized
│ closed-world), ABAC (cross-pod, sybil-resistance, ZK,
│ emergent policy, supersession), code domain, agent
│ registry, distributed affordances, cross-app interop,
│ pod-as-graph views, federated reasoning, nanotation
│ pipeline, scripts/ for multi-CLI-session orchestration
├── spec/ Specs: architecture, LAYERS, DERIVATION, CONFORMANCE,
│ FEDERATED-TRANSACTIONS, CONSTITUTIONAL-LAYER,
│ CRDT-OFFLINE-MERGE, AGGREGATE-PRIVACY, proofs/ (TLA+)
├── benchmarks/ LongMemEval (89.2% agentic, 92.4% raw) evaluation suite
├── integrations/ Path 2 (OpenClaw memory plugin) + Path 4 (compliance overlay)
│ + Path 5 (Hermes memory provider) — all HATEOAS-shaped
└── tests/ Vitest suites covering the substrate (counts vary as
new modules land; see CLAUDE.md for the canonical
expectations on tests/context-graphs.test.ts).
Design Principles
- Zero runtime dependencies for the core. Validation is programmatic. SHACL shapes exported as Turtle strings.
- Discriminated union pattern. All 9+ facet types use
{ type: 'Temporal' | 'Provenance' |... } for exhaustive switch matching.
- Composition is algebraic. Four operators form a bounded lattice with category-theoretic proofs (presheaf naturality, idempotence, commutativity, associativity, absorption).
- Semiotic foundation. Descriptors are Peircean signs. The Sign functor phi/psi forms an adjunction between the descriptor category and the semiotic category. The Semiotic Field Functor maps to SAT.
- PGSL substrate. Content is canonically addressed via the Poly-Granular Sequence Lattice — deterministic, structurally shared, with categorical pullback construction.
- Real cryptography. No mocks. ethers.js v6 for ECDSA, tweetnacl for NaCl encryption, real IPFS CIDs, real SIWE verification.
- Local-first. Everything works on localhost with zero internet. Cloud deployment is additive.
- W3C vocabulary reuse. 23+ standard namespaces (PROV-O, OWL-Time, DCAT, WAC, VC, DID, Solid, Hydra, DPROD, SKOS, FOAF).
Quick Start
Pick the path that matches who you are:
🎯 I want to actually USE one of the example verticals (chat with my training content, run a probe cycle, bridge xAPI, etc.)
The example verticals under applications/ are separate from Interego — the generic protocol-level deployments don't bundle them. You reach a vertical's capabilities one of two ways:
Path A — first-principles (use ANY generic Interego MCP client; no per-vertical install):
The vertical exposes its capabilities as iep:Affordance descriptors. Run any generic Interego agent (e.g., the stdio MCP server), point it at the vertical's affordance manifest, and it discovers + invokes via discover_context + a standard HTTP POST to hydra:target. No vertical-specific code anywhere on the client side. This is the spec-level path — works for any vertical anyone publishes.
Path B — opinionated reified bridge (when you want named MCP tools — lpc.*, adp.*, lrs.*, ac.* — for ergonomic LLM tool selection):
Each example vertical has a tiny optional bridge in applications/<vertical>/bridge/. Build + run only the ones you want; each is independent, depends on @interego/core, and exposes its named tools at its own port:
# Example: run the learner-performer-companion bridge
cd applications/learner-performer-companion/bridge
npm install && npm run build
export LPC_DEFAULT_POD_URL=https://your-pod.example/me/
export LPC_DEFAULT_USER_DID=did:web:you.example
PORT=6010 BRIDGE_DEPLOYMENT_URL=http://localhost:6010 npm start
Add http://localhost:6010/mcp to your MCP client config. That bridge exposes the LPC vertical's 6 named MCP tools. Run the others (ADP at 6020, LRS at 6030, AC at 6040) the same way.
Either path, you can now do (Path A via affordance walking; Path B via named tool):
- "Ingest this SCORM zip into my pod" →
lpc.ingest_training_content (Path B) or discover_context → find urn:iep:action:lpc:ingest-training-content → POST (Path A)
- "What did the customer-service training say about second-contact escalation?" →
lpc.grounded_answer — verbatim citation, honest no-data, tamper detection
- "Define a capability space and record three parallel probes" →
adp.define_capability + adp.record_probe
- "Pull this xAPI Statement from our LRS into my pod" →
lrs.ingest_statement (auto-negotiates xAPI 2.0 / 1.0.3)
- "Author this tool, attest it, bundle it as a teaching package" →
ac.author_tool → ac.attest_tool → ac.bundle_teaching_package
Each vertical has Tier 8 integration tests against the real live pod (Railway css-gate) + real Lrsql + real SCORM Cloud + public Nostr relay. See applications/README.md for the per-vertical framing.
🤖 I'm an AI coding agent (Claude Code, Cursor, Windsurf, Cline) — protocol-level access
The fastest way to use the protocol layer is via the stdio MCP server, which exposes the substrate's tool surface (publish, discover, ingest, resolve, compose, ontology lookup, runtime eval, identity, federation) to any MCP-capable client. The authoritative tool list lives in mcp-server/server.ts.
Add this to your MCP client config:
// Claude Code: ~/.claude.json | Claude Desktop: claude_desktop_config.json
// Cursor:.cursor/mcp.json | Windsurf: ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"context-graphs": {
"command": "npx",
"args": ["-y", "@interego/mcp"]
}
}
}
Restart your client. You can now say things like "publish this graph to my pod with high trust", "what affordances does this lattice node have?", "resolve this PGSL atom and show its containment chain" — and the LLM will pick the right tool.
→ Full MCP server docs
🧑💻 I'm a developer building a TypeScript app
npm install @interego/core
import {
ContextDescriptor,
createPGSL,
embedInPGSL,
loadOntology, // load any of the four canonical.ttl ontologies
computeConfidence, // runtime eval over PGSL signals
} from '@interego/core';
// 1. Build a context descriptor (the typed-context layer)
const desc = ContextDescriptor.create('urn:iep:my-analysis:1')
.describes('urn:graph:my-data')
.temporal({ validFrom: '2026-04-13T00:00:00Z' })
.asserted(0.92)
.build();
// 2. Use the PGSL substrate
const pgsl = createPGSL({ wasAttributedTo: 'urn:my-app', generatedAtTime: new Date().toISOString() });
embedInPGSL(pgsl, "The user prefers Adobe Premiere Pro for video editing.");
// 3. Load the canonical harness ontology
const harnessTtl = loadOntology('harness'); // 982 lines, 810 triples
→ See the full developer guide
🐍 I'm scripting in Python / Go / Rust / anything else
Hit the deployed HTTP relay (any HTTP client works — no MCP, no SDK):
curl -X POST https://relay.interego.xwisee.com/tool/discover_context \
-H "Content-Type: application/json" \
-d '{"namespace": "cg"}'
Every MCP tool is exposed as a POST /tool/{tool_name} endpoint with a JSON body matching the tool's input schema.
👀 I just want to look around
Open one of the deployed web UIs in your browser — no install required:
👶 I'm new — what's the actual first-hour experience?
First-hour walkthrough — guided tour for non-developers. Enroll an identity, visit your dashboard, wire up an AI client, publish your first memory, recall it later, share with a friend. 30 minutes, no CLI.
Companion docs:
🛠 I want to clone and hack on the system itself
git clone https://github.com/markjspivey-xwisee/interego.git
cd context-graphs
npm install
npm run build
npm test # Vitest across the tests/ directory (3 env-gated tests skip when their creds are unset)
# Build the MCP server too
cd mcp-server
npm install ../interego-core-*.tgz --no-save
npm run build
Deployment is two explicit, manually-dispatched steps — building does not deploy.
# 1. Build one image and push it to GHCR. Takes the IMAGE name (interego-relay),
# which is not always the Railway SERVICE name (relay).
gh workflow run build-ghcr.yml -f image=interego-relay --ref master
# 2. Pin the Railway service to that image and poll /health until it reports the sha.
gh workflow run deploy-railway.yml -f service=relay -f tag=<40-hex-sha> \
-f verify_url=https://relay.interego.xwisee.com/health
This section previously described a deploy-azure.yml that auto-deployed five
container apps on every push to master. That workflow was deleted when the stack
moved off Azure, and the registry it pushed to (contextgraphsacr) no longer exists —
so the README was documenting a pipeline that could not run, linking to a file that is
not in the tree, and telling a reader that merging to master ships. It does not.
Nothing deploys without the second dispatch above.
Every service goes through the same two dispatches — there is no auto-deploy tier and no
manually-built tier. The image names build-ghcr.yml accepts are read out of its own
matrix by its validate-input job, so a name that is not in the matrix fails the dispatch
rather than skipping every leg and reporting success:
interego-relay, interego-identity, interego-css-gate, interego-css-pgslinterego-dashboard, interego-pgsl-browser, interego-main, interego-microsite, interego-bridge, interego-acme-idinterego-foxxi-bridge, interego-foxxi-dashboard, interego-foxxi-microsite, interego-foxxi-scorm-playerinterego-wsp-bridge, interego-discord
The az acr build / az containerapp update recipe that stood here is not a fallback —
contextgraphsacr was deleted with the rest of the Azure footprint, so both commands
fail at the registry. Keeping them printed as the manual path meant the documented
escape hatch for a broken CI deploy was itself broken.
Tagging a release as vX.Y.Z triggers npm publish for both packages (workflow).
Detailed Examples
Build a Context Descriptor
import { ContextDescriptor, validate, toTurtle } from '@interego/core';
import type { IRI } from '@interego/core';
const descriptor = ContextDescriptor.create('urn:iep:my-analysis:1' as IRI)
.describes('urn:graph:project:arch-v1' as IRI)
.temporal({ validFrom: '2026-03-20T00:00:00Z' })
.delegatedBy(
// The principal this agent is AUTHORISED to act for — standing, and written
// as the Agent facet's iep:onBehalfOf.
'https://id.example.com/alice/profile#me' as IRI,
// The author. prov:wasAttributedTo names THIS, because it is what asserted
// the descriptor. Whether any particular act was carried out on the
// principal's behalf is a separate, per-activity statement — see
// prov:qualifiedDelegation / iep:actedOnOwnAccount.
'urn:agent:anthropic:claude-code:vscode' as IRI,
)
.asserted(0.92)
.selfAsserted('did:web:alice.example' as IRI)
.federation({
origin: 'https://pod.example.com/alice/' as IRI,
storageEndpoint: 'https://pod.example.com/alice/' as IRI,
syncProtocol: 'SolidNotifications',
})
.version(1)
.build();
const result = validate(descriptor);
console.log(result.conforms); // true
console.log(toTurtle(descriptor));
Publish to a Solid Pod
import { publish, discover, subscribe } from '@interego/core';
const result = await publish(descriptor, graphTurtle, 'https://pod.example.com/alice/');
// → { descriptorUrl, graphUrl, manifestUrl }
// → IPFS pinned (if configured): ipfs://Qm...
// → Anchor receipt written to pod: /anchors/{id}.json
const entries = await discover('https://pod.example.com/bob/', {
facetType: 'Semiotic', validFrom: '2026-01-01T00:00:00Z',
});
const sub = await subscribe('https://pod.example.com/bob/', (event) => {
console.log(`${event.type} on ${event.resource}`);
});
Compose Descriptors
import { union, intersection, restriction } from '@interego/core';
const merged = union(descriptorA, descriptorB);
const common = intersection(descriptorA, descriptorB);
const trustOnly = restriction(merged, ['Trust', 'Semiotic']);
PGSL — Poly-Granular Sequence Lattice
The content substrate. Deterministic hierarchical data structure representing sequential data as a lattice of overlapping sub-structures with content-addressed canonical URIs.
import { createPGSL, embedInPGSL, pgslResolve, latticeMeet } from '@interego/core';
const pgsl = createPGSL({ wasAttributedTo: 'did:web:alice', generatedAtTime: new Date().toISOString() });
const uriA = embedInPGSL(pgsl, 'autonomous agents share knowledge graphs');
const uriB = embedInPGSL(pgsl, 'knowledge graphs enable semantic interoperability');
const meet = latticeMeet(pgsl, uriA, uriB);
const shared = pgslResolve(pgsl, meet!); // "knowledge graphs" — structural overlap
PGSL provides:
- Content-addressed atoms — same input always produces the same URI
- Structural sharing — two texts sharing sub-sequences share lattice fragments
- Lattice meet — greatest lower bound finds the largest shared sub-sequence
- Categorical pullback — overlapping pair construction as a universal property
- Entity/relation extraction — extract structured facts from natural language
- Ontological inference — synonym groups, IS-A hierarchies, part-of relations
- Usage-based semantics — co-occurrence mining, Yoneda embedding, emergent synonyms
- Structural computation — date arithmetic, counting, aggregation, abstention detection
- In-memory SPARQL engine — materialize lattice as triple store, execute SELECT/ASK/FILTER/OPTIONAL/UNION/aggregates
- Three-layer SHACL validation — core (node constraints), structural (lattice invariants), domain (user-defined shapes)
- LLM tool interface — 5 tools (sparql_query, lookup_entity, count_items, temporal_query, validate_shacl) with multi-turn dispatch loop
- Ingestion profiles — domain-specific data mapping (xAPI, LERS, RDF, custom)
SPARQL Engine
import { sparqlQueryPGSL, materializeTriples, executeSparqlString } from '@interego/core';
// Execute SPARQL against the PGSL lattice
const result = sparqlQueryPGSL(pgsl, `
PREFIX pgsl: <https://markjspivey-xwisee.github.io/interego/ns/pgsl#>
SELECT ?atom ?value WHERE {
?atom a pgsl:Atom ; pgsl:value ?value.
} LIMIT 10
`);
console.log(result.bindings.length); // number of matching atoms
SHACL Validation
import { validateAllPGSL, validateDomainShapes } from '@interego/core';
// Validate lattice with all 3 layers (core + structural + domain)
const result = validateAllPGSL(pgsl);
console.log(result.conforms); // true if no violations
// Custom domain shapes
const result = validateDomainShapes(pgsl, [{
name: 'AtomMustHaveValue',
targetClass: 'https://...pgsl#Atom',
properties: [{ path: 'https://...pgsl#value', minCount: 1 }],
}]);
Coherence Verification
Usage-based semantic agreement between agents. Two agents share a SIGN (atom) but only share MEANING if they USE it in the same syntagmatic contexts.
import { createPGSL, embedInPGSL, verifyCoherence, computeCoverage } from '@interego/core';
const pgslA = createPGSL({ wasAttributedTo: 'agent-a', generatedAtTime: new Date().toISOString() });
const pgslB = createPGSL({ wasAttributedTo: 'agent-b', generatedAtTime: new Date().toISOString() });
embedInPGSL(pgslA, 'patient status critical');
embedInPGSL(pgslB, 'account status active');
const cert = verifyCoherence(pgslA, pgslB, 'agent-a', 'agent-b', 'status');
// cert.status === 'divergent' — "status" is shared but used differently
// cert.semanticOverlap === 0.15 — continuous 0-1 measure
// cert.obstruction.type === 'term-mismatch'
// cert.semanticProfile — per-atom usage analysis
const coverage = computeCoverage(['agent-a', 'agent-b', 'agent-c']);
// coverage.unexamined === 2 — the DANGEROUS state
Three states: Verified (sections glue), Divergent (obstruction found), Unexamined (dangerous — agents proceed as if aligned without verification).
Paradigm Constraints
Structural rules on what can fill positions in chains. The paradigm set P(S, i) is the set of all atoms appearing at position i across chains matching pattern S. Five operations: subset, intersect, union, exclude, equal.
// P(?, completed, ?) — everything anyone completed
// P(chen, ?, ?) — everything chen did
// P(?, type, Class) — all classes
// Constraint: P(?, severity, critical) ⊆ P(?, escalate, ?) — criticals must be escalated
Decision Functor (OODA Loop)
Natural transformation from observation presheaves to action categories: Observe → Orient → Decide → Act.
import { extractObservations, decide } from '@interego/core';
const obs = extractObservations(pgsl, 'agent-a', certificates);
const result = decide(pgsl, 'agent-a', certificates);
// result.strategy === 'exploit' | 'explore' | 'delegate' | 'abstain'
// result.decisions — ranked affordances with confidence scores
Progressive Persistence
Five-tier persistence with URI invariance — same content hash across all tiers:
| Tier | Storage | Durability | Resolution |
|---|
| 0 | Memory | Ephemeral | Direct lookup |
| 1 | Local disk | Survives restart | File read |
| 2 | Solid Pod | Federated | HTTP + WAC auth |
| 3 | IPFS | Global, immutable | CID gateway |
| 4 | Blockchain | Permanent | On-chain hash verification |
import { createPersistenceRegistry, recordPersistence, promoteToIpfs } from '@interego/core';
const registry = createPersistenceRegistry();
recordPersistence(registry, atomUri, 0, { promotedBy: 'agent-a' });
const record = await promoteToIpfs(pgsl, atomUri, { provider: 'pinata', apiKey: '...' });
// record.cid — globally dereferenceable IPFS CID
Virtualized RDF Layer
The entire system is queryable as standard RDF. Any SPARQL client (Comunica, Apache Jena, Protege) works.
| Endpoint | What |
|---|
GET /ontology | Full OWL ontology (iep:, pgsl:, Hydra, DCAT, PROV-O) |
GET /ontology/shacl | System SHACL shapes |
GET /api-doc | Hydra API description |
GET /catalog | DCAT/DPROD federation catalog |
GET/POST /sparql | W3C SPARQL Protocol — full system materialized |
POST /sparql/update | SPARQL INSERT DATA with PGSL write-back |
GET /dump.ttl | Full system Turtle export |
GET /dump.jsonld | Full system JSON-LD export |
Tested with Comunica SPARQL engine — standard RDF tooling interoperability confirmed.
Ingestion Profiles
import { ingestWithProfile } from '@interego/core';
// xAPI profile: preserves actor/verb/object/result nesting
const uri = ingestWithProfile(pgsl, 'xapi', {
actor: { account: { homePage: 'https://example.com', name: 'chen' }, name: 'CPT Sarah Chen' },
verb: { id: 'http://adlnet.gov/expapi/verbs/completed', display: { 'en-US': 'completed' } },
object: { id: 'urn:activity:ils-approach', definition: { name: { 'en-US': 'ILS Approach Rwy 28L' } } },
result: { score: { raw: 92, max: 100 }, success: true, duration: 'PT45M' },
});
// Ingested as multiple chains: core statement + identity/name/result chains
// (chen, completed, ils-approach-rwy-28L) — core, short atoms
// (chen, identity, https://learner.airforce.mil:chen) — IFI binding
// (chen, name, Sarah) — display name
// (chen, ils-approach-rwy-28L, score, 92) — result property
// LERS profile: issuer/subject/achievement/evidence nesting
const credUri = ingestWithProfile(pgsl, 'lers', {
issuer: 'credential.training.airforce.mil',
subject: { name: 'CPT Sarah Chen' },
achievement: { name: 'USAF Instrument Rating', level: 'Proficient', framework: 'USAF v3' },
evidence: { statementCount: 5, averageScore: 91.6 },
});
// Custom profiles: register your own
import { registerProfile } from '@interego/core';
registerProfile({
name: 'fhir',
description: 'FHIR observation: patient/encounter/observation nesting',
transform(input) { /* domain-specific mapping */ return '((patient),(encounter),(observation))'; },
});
Observatory
The Interego Observatory is a real-time dashboard for monitoring multi-agent federation:
CSS_URL=http://localhost:3456/ \
KNOWN_PODS=http://localhost:3456/lrs/,http://localhost:3456/competency/ \
PORT=5001 npx tsx examples/pgsl-browser/server.ts
# → Observatory at http://localhost:5001/observatory
# → PGSL Lattice Browser at http://localhost:5001/
Tabs: Federation (pod registry), Descriptors (facet browsing), Trust (chain visualization), Composition (algebraic operators), SPARQL (query interface), SHACL (validation), Coherence (usage-based verification with semantic profiles), Decisions (OODA decision functor per agent), PGSL Lattice (browser + Node Explorer)
Interactive Demo: Click through 7 phases of the TLA pipeline — agents publishing, discovering, signing, composing, verifying, and running coherence verification + decision functor across live Solid pods.
Multi-Agent Demos
Run these from the repository root after npm install && npm run build. The TLA and team demos,
and npm start in examples/multi-agent, start a local Community Solid Server with
npx @solid/community-server@7. They run it from a folder under your temp directory, outside the
repository, where its configuration loader cannot pick up the repository's newer query libraries.
The first run downloads the server.
TLA / xAPI / IEEE LERS Demo
A flight training pipeline for a 3-pilot cohort across 6 Solid pods:
npx tsx examples/multi-agent/tla-demo.ts --keep-alive
6 Phases:
- Setup — 6 pods, 6 ethers.js wallets, 3 EIP-712 delegations
- xAPI Ingestion — 15 statements from flight simulator, PGSL structural ingestion via xAPI profile, ECDSA-signed descriptors
- Competency Assessment — SPARQL queries, affordance engine, Pearl's causal model (SCM + counterfactual), competency mapping
- Credential Issuance — Composition (intersection), SHACL validation, IEEE LERS credentials, ECDSA signatures
- Learner Discovery — Bidirectional: learners discover, verify signatures + delegation chains, republish to own pods
- External Verification — Full trust chain audit, cohort overlap via SPARQL
Team Security Audit Demo
3 agents (Scanner, Analyst, Lead) across 3 pods:
npx tsx examples/multi-agent/team-demo.ts --keep-alive
Shows: trust escalation (SelfAsserted → ThirdPartyAttested → CryptographicallyVerified), composition operators, PGSL structural overlap, provenance chains.
Healthcare Coherence Demo
Three agents (ER, Radiology, Pharmacy) independently document a patient visit, then verify semantic alignment:
npx tsx examples/multi-agent/coherence-demo.ts
Shows: usage-based coherence verification, emergent data contracts from structural overlap, coherence certificates with per-atom semantic profiles.
Affordance Engine
Integrates 8 theoretical frameworks for autonomous agent decision-making:
| Framework | What it provides | Module |
|---|
| Gibson | Relational affordances (agent x environment) | computeAffordances() |
| Norman | Signifiers + anti-affordances | extractSignifiers() |
| Pearl | Affordances as interventional queries P(Y|do(X)) | CausalAffordanceEffect |
| Boyd (OODA) | Observe -> Orient -> Decide -> Act with IG&C | OODACycle |
| Endsley (SA) | Perception -> Comprehension -> Projection | SituationalAwarenessLevel |
| Bratman (BDI) | Beliefs -> Desires -> Intentions | AgentState |
| Friston | Active inference, surprise evaluation | evaluateSurprise() |
| Stigmergy | Affordance landscape tracking across pods | StigmergicField |
import { computeAffordances, computeCognitiveStrategy } from '@interego/core';
// What can this agent do with this descriptor?
const affordances = computeAffordances(agentProfile, descriptor);
// → { affordances: [...], antiAffordances: [...], signifiers: [...], saLevel: {...} }
// What cognitive strategy should answer this question?
const strategy = computeCognitiveStrategy('How many days between X and Y?');
// → { strategy: 'temporal-twopass', computationType: 'date-arithmetic',... }
Causality — Pearl's SCM Framework
import { buildSCM, doIntervention, isDSeparated, evaluateCounterfactual } from '@interego/core';
const scm = buildSCM({
variables: [{ name: 'X' }, { name: 'Y' }, { name: 'Z' }],
edges: [{ from: 'X', to: 'Y' }, { from: 'Y', to: 'Z' }],
});
const mutilated = doIntervention(scm, { variable: 'Y', value: '1' });
const separated = isDSeparated(scm, 'X', 'Z', new Set(['Y'])); // true
const counterfactual = evaluateCounterfactual(scm, {
intervention: { variable: 'X', value: '0' },
outcome: 'Z',
evidence: { Y: '1' },
});
Cryptography
All real. No mocks.
E2E Encryption (NaCl)
import { generateKeyPair, createEncryptedEnvelope, openEncryptedEnvelope } from '@interego/core';
const owner = generateKeyPair(); // X25519
const agent = generateKeyPair();
const envelope = createEncryptedEnvelope(turtleContent, [agent.publicKey, owner.publicKey], owner);
const decrypted = openEncryptedEnvelope(envelope, agent); // only authorized agents can read
Zero-Knowledge Proofs
import { proveConfidenceAboveThreshold, proveDelegationMembership, proveTemporalOrdering } from '@interego/core';
// Prove confidence > 0.8 without revealing exact value
const { proof } = proveConfidenceAboveThreshold(0.95, 0.8);
// Prove "I'm in the authorized agent set" without revealing which agent
const membershipProof = proveDelegationMembership(myAgentId, authorizedAgents);
// Prove "published before time T" without revealing exact time
const temporalProof = proveTemporalOrdering(myTimestamp, deadline);
Wallets & SIWE
import { createWallet, createDelegation, signDescriptor, verifySiweSignature } from '@interego/core';
const humanWallet = await createWallet('human', 'Alice'); // real secp256k1
const agentWallet = await createWallet('agent', 'Claude');
const delegation = await createDelegation(humanWallet, agentWallet, 'ReadWrite'); // EIP-712
const signed = await signDescriptor(descriptorId, turtle, agentWallet); // real ECDSA
IPFS Pinning
import { pinDescriptor, computeCid } from '@interego/core';
const cid = computeCid(turtleContent); // real SHA-256 CID
const anchor = await pinDescriptor(descriptorId, turtle, { provider: 'pinata', apiKey: '...' });
// → pinned to IPFS, dereferenceable globally
MCP Server
Setup
Add to .mcp.json (VS Code) or claude_desktop_config.json (Desktop):
{
"mcpServers": {
"context-graphs": {
"command": "cmd",
"args": ["/c", "npx", "tsx", "path/to/context-graphs/mcp-server/server.ts"],
"env": {
"CG_POD_NAME": "your-name",
"CG_AGENT_ID": "urn:agent:anthropic:claude-code:vscode",
"CG_OWNER_WEBID": "https://your-identity-server/users/you/profile#me",
"CG_OWNER_NAME": "Your Name",
"CG_BASE_URL": "https://your-css-instance/"
}
}
}
}
Auto-onboarding: first tool call provisions pod + registry + credential automatically.
Tool Categories
Core (6): publish_context, discover_context, get_descriptor, subscribe_to_pod, get_pod_status, analyze_question
Delegation (3): register_agent, revoke_agent, verify_agent
Federation (9): discover_all, subscribe_all, list_known_pods, add_pod, remove_pod, discover_directory, publish_directory, resolve_webfinger, unsubscribe_from_pod (releases a CG_MAX_SUBSCRIPTIONS slot)
Identity (2): setup_identity, link_wallet
PGSL (5): pgsl_ingest, pgsl_resolve, pgsl_lattice_status, pgsl_meet, pgsl_to_turtle
Progressive Tiers
Set CG_TOOL_TIER to control which tools are exposed. Tier membership is the source of truth — the sets in mcp-server/server.ts (CORE_TOOLS, FEDERATION_TOOLS, CRYPTO_TOOLS, PGSL_TOOLS) drive isToolEnabled:
| Tier | Tool sets exposed |
|---|
core | CORE_TOOLS only — new users learning the basics |
standard | + FEDERATION_TOOLS — teams federating across pods |
full | + CRYPTO_TOOLS — users with crypto/wallet integration |
all (default) | + PGSL_TOOLS — power users, researchers |
Identity & Delegation
The pod belongs to the owner (human/org). Agents are delegates.
Owner (human)
├── WebID: https://identity-server/users/alice/profile#me
├── DID: did:web:identity-server:users:alice
├── Pod: https://css-server/alice/
├── Authorized agents:
│ ├── claude-code-vscode [ReadWrite]
│ ├── claude-desktop [ReadWrite]
│ └── codex-cli [DiscoverOnly]
└── Delegation credentials: /alice/credentials/*.jsonld (VC format)
Supports: WebID, DID (did:web), W3C Verifiable Credentials, Open Badges 3.0, IEEE LERS, SIWE (ERC-4361), ERC-8004 agent identity tokens, Universal Wallet.
Federation — Three Discovery Approaches
- Known Pods —
CG_KNOWN_PODS env var
- Pod Directory Graphs — decentralized RDF registries
- WebFinger — RFC 7033 DNS-rooted discovery (same as ActivityPub)
Benchmarks
| Approach | Raw (500q) | Adjusted | Excl Preference |
|---|
| Agentic v3 (SPARQL + fact extraction) | 86.6% | 89.2% | 92.1% |
| Raw LLM (no system) | 92.4% | — | — |
| Agentic v1 (first run) | 83.0% | — | — |
The system adds value on structural tasks (counting, temporal reasoning, knowledge-update tracking) but a raw LLM with a large context window is competitive at pure text comprehension. The system's real value is not in beating LLMs at reading text — it's in providing composable, verifiable, federated context infrastructure that LLMs cannot provide: typed metadata, trust chains, access control, algebraic composition, structural dedup, and provenance.
Deployment
Local (zero internet)
# Just works — auto-starts Community Solid Server
CG_BASE_URL=http://localhost:3456/ npx tsx mcp-server/server.ts
The hosted fleet (Railway)
gh workflow run build-ghcr.yml -f image=interego-relay --ref master
gh workflow run deploy-railway.yml -f service=relay -f tag=<40-hex-sha> \
-f verify_url=https://relay.interego.xwisee.com/health
Runs: CSS (Solid server), Dashboard (observation UI), MCP Relay (HTTP bridge), Identity
Server (WebID + DID + SIWE), and the Foxxi vertical's own services.
cd deploy && bash azure-deploy.sh used to be documented here. The Azure resource group
and container registry are gone, so that command now fails partway through having already
run — which is worse than not being documented, because the reader finds out only after it
has started making changes.
Development
npm install
npm run build # TypeScript → dist/
npm test # Vitest across the tests/ directory
npm run test:watch # Watch mode
Test Suites
These nineteen are a selection, not the whole suite (the tree holds far more — run
npx vitest run tests/ for the total). The Tests column is checked on every vitest
run by tools/vitest-run-integrity.mjs: a row whose number stops matching the module's
real test count fails the run, and so does a row naming a file that no longer exists. It
is a gate because nine of these nineteen numbers were false at the commit this sentence
replaced — solid.test.ts said 20 against a real 44 — and a hand-typed count has no way
to stay true.
| Suite | Tests | Coverage |
|---|
context-graphs.test.ts | 46 | Builder, composition, validation, serialization |
solid.test.ts | 51 | Publish, discover, subscribe, agent registry |
federation.test.ts | 24 | Pod directory, multi-pod, WebFinger, Hydra |
causality.test.ts | 38 | SCM, do-calculus, d-separation, counterfactual |
pgsl.test.ts | 34 | Lattice, category, geometric morphism |
pgsl-sparql.test.ts | 19 | Triple store, SPARQL execution, existing generators |
pgsl-shacl.test.ts | 13 | Core/structural/domain SHACL validation |
pgsl-tools.test.ts | 19 | LLM tools, tool call parsing, tool loop |
projection.test.ts | 15 | Vocabulary mapping, binding strength |
affordance.test.ts | 26 | Gibson, Norman, OODA, BDI, Friston, stigmergy |
crypto.test.ts | 32 | Wallets, ECDSA, delegation, SIWE |
encryption-zk.test.ts | 50 | NaCl encryption, ZK proofs, selective disclosure |
sdk-extractors.test.ts | 19 | Category theory, semiotic functor |
xapi-conformance.test.ts | 60 | xAPI profile, IFI priority, result/context structure |
pgsl-coherence.test.ts | 10 | Coherence verification, coverage, certificates |
agent-framework.test.ts | 68 | AAT, Policy, PROV tracing, Personal Broker, AAT Decorator |
infrastructure.test.ts | 47 | Enclaves, Checkpoints, CRDT sync |
discovery.test.ts | 50 | Introspection, Virtual Layer, Metagraph, Marketplace |
multi-agent-integration.test.ts | 59 |
Specifications
| Document | What it covers |
|---|
| Interego Protocol 1.0 WD | Core spec: descriptors, facets, composition, serialization |
spec/architecture.md | Architecture overview + RDF 1.2 / SHACL 1.2 alignment statement |
spec/LAYERS.md | Layering discipline (L1 / L2 / L3); namespace-as-projection-contract; drift triggers |
spec/DERIVATION.md | Construction rules: every L2/L3 class must ground in L1 (CI-enforced) |
spec/CONFORMANCE.md | Four-level conformance test suite + badge program (L1 Core, L2 Federation, L3 Advanced, L4 Compliance) |
spec/STORAGE-TIERS.md | Local-first by design: 5-tier deployment ladder from library-only → P2P. Tier 1 (local pod) is the zero-config default; the MCP auto-spawns CSS on first publish |
docs/p2p.md | Tier 5 P2P transport — Nostr-style relay-mediated, ECDSA + Schnorr (BIP-340) dual signing, 1:N encrypted share via KIND_ENCRYPTED_SHARE. Mobile + desktop deployment topology (operator-bridge or user-bridge). |
spec/SOC2-PREPARATION.md | SOC 2 readiness package: scope, gap analysis, vendor inventory, solo-operator compensating controls, Type 1 → Type 2 timeline |
Related Concepts
This library is designed to compose with several adjacent theoretical frameworks:
- HELA — a topos-theoretic xAPI stack using the presheaf category ℰ = Set^(𝒞_xAPI^op)
- SAT (Semiotic Agent Topos) — the Semiotic Facet maps directly to SAT's Semiotic Field Functor (Σ)
- PGSL (Poly-Granular Sequence Lattice) — the substrate layer included in this repo; abstract data type for canonical sequence addressing
Spec Compliance
Implements the Interego Protocol 1.0 Working Draft:
-
Section 3.1: Context Descriptor structure
-
Section 3.4: Composition operators forming a bounded lattice
-
Section 3.5: Triple-level inheritance via effectiveContext()
-
Section 5: All facet types with W3C vocabulary alignment
-
Section 6: Serialization (Turtle, JSON-LD, TriG)
-
Section 7: SPARQL 1.2 query patterns
-
Paradigm Constraints (spec/paradigm-constraints.md): syntagm/paradigm, 5 operations, emergent semantics, coherence protocol, decision functor
-
Progressive Persistence (spec/progressive-persistence.md): 5-tier persistence, URI invariance, resolution protocol, structural encryption
Extensions beyond the spec: PGSL substrate, Pearl causality, affordance engine, E2E encryption, ZK proofs, IPFS anchoring, structural computation, cognitive strategy routing.
