Interego — Memória Federada para Agentes IA
markjspivey-xwisee/interego
Memória persistente e federada para agentes IA, controlada por você
Ver no GitHubMCP server que fornece contexto persistente, verificável e federado para agentes de IA, armazenado em pods Solid sob seu controle. Funciona com Claude, Cursor, Cline e outros clientes MCP, permitindo que agentes mantenham memória portável entre sessões e máquinas com segurança criptográfica.
Instalação
npx convez-ai markjspivey-xwisee/interego1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Agentes IA com memória de longa duração entre sessões
- Compartilhamento seguro de contexto entre múltiplos agentes
- Aplicações federadas com dados verificáveis e auditáveis
Veredito

Framework sólido e bem arquitetado para memória distribuída de agentes, com suporte nativo a MCP e federação Solid. Status de referência em Azure: pronto para avaliar, mas requer self-hosting antes de dependência em produção.
README
A tradução para o português deste README ainda está na fila.
@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://interego-relay.livelysky-8b81abb0.eastus.azurecontainerapps.io/mcp"
}
}
}
/mcp is the Streamable HTTP transport — a single endpoint that carries request, response, and notifications. Current MCP clients (Claude Code, Cursor, Codex CLI, Windsurf, Cline) prefer it. If your client only speaks the older SSE-style transport, use /sse on the same host — both endpoints are live on the relay and back the same identities and pods.
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://interego-relay.livelysky-8b81abb0.eastus.azurecontainerapps.io/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://interego-relay.livelysky-8b81abb0.eastus.azurecontainerapps.io/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.
If a client only supports the older SSE-style endpoint, swap /mcp for /sse on the same host. Everything else stays identical.
Status: reference implementation. Hosted on the maintainer's free Azure instance 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 (
cg:/cgh:/pgsl:/ie:/align:) are frozen for v1.0 pending Candidate Recommendation. Editors commit no breaking changes through 2027-05-16 without a deprecation cycle. Seespec/STABILITY.mdfor the practical adopter-facing commitment, andspec/architecture.mdfor 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, cg:supersedes chains, the PGSL content-addressed lattice — the L1 protocol is Context Graphs 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 (src/kernel/) and as first-class MCP tools alongside the 27 named compatibility shims (publish_context, register_agent, pgsl_*, invoke_affordance, …). 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
| If you want to… | Go here |
|---|---|
| Use Interego from an AI coding agent right now (Claude Code / Cursor / Windsurf / Cline) | Recipe: add the MCP server |
| Try the hosted reference deployment without running anything | The deployed Azure surfaces |
| Mount Interego under an OpenClaw / Hermes / Codex runtime | The MCP path above is the default. OpenClaw and Hermes also have native memory-slot plugins (integrations/openclaw-memory/, integrations/hermes-memory/) when you want it tighter than MCP. Compliance teams add integrations/compliance-overlay/ on top. Full map: docs/integrations/agent-runtime-integration.md. |
| Build a TypeScript app on top of the substrate | Developer entry point |
| Build a vertical (LRS adapter, agent collective, organizational memory) | Vertical applications |
| Run a live demo of multi-agent emergent coordination | demos/ — 25 end-to-end scenarios (24 + 25 are the dual-audience pilot demos) |
| Understand the spec / category-theoretic foundations | spec/architecture.md + docs/ARCHITECTURAL-FOUNDATIONS.md |
| Run a SOC 2 / EU AI Act / NIST RMF audit against an Interego pod | spec/SOC2-PREPARATION.md |
| Set up Interego for a non-technical friend or family member | The hosted front door — they enroll a passkey or wallet directly (~30s, no command line), or their MCP client drives it on first call |
| Browse the protocol primitives via web UI | Identity Dashboard + PGSL Browser |
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 —
cg:modalStatus(Asserted / Hypothetical / Counterfactual) pluscg:supersedeschains 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_contextproduces 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-graphshare_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 Azure 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 viacg:Affordancedescriptors using only the protocol's own primitives. No vertical-specific client code needed at the agent. - An optional per-vertical bridge (
applications/<vertical>/bridge/) — a tiny standalone Express + MCP server that reifies the affordances as named MCP tools. Run it when you want LLM tool-name ergonomics; the bridge derives MCP tool schemas from the affordance declarations (single source of truth — never hand-written).
Current example verticals:
learner-performer-companion/— human-protagonist wallet: SCORM/cmi5/PDF training content + W3C VCs (Open Badges 3.0 / IMS CLR / IEEE LERS) + xAPI history + performance records. Grounded chat with verbatim citation, honest no-data, tamper detection.agent-development-practice/— agent-as-subject: complexity-informed (Cynefin) probe-sense-respond cycle. Probes Hypothetical; multi-coherent-narrative syntheses; evolution steps requireexplicitDecisionNotMade;passport:LifeEventbiographical record carries humility forward.lrs-adapter/— boundary translator: bidirectional xAPI ↔ Interego with version negotiation (2.0.0 → falls back to 1.0.3). Counterfactual always skipped on projection; Hypothetical skipped without opt-in.agent-collective/— multi-agent federation: tool authoring + attestation + teaching packages + cross-bridge encrypted chime-ins.organizational-working-memory/— federated organizational memory: typed people / projects / decisions / follow-ups / content-addressed notes on the org pod, plus a per-source navigation surface (uniformls / cat / grep / recentverbs) that isolates each external source behind its own sub-handler so the main agent's context is never polluted by per-source tool noise. Demo 15 walks the closed loop: a Curator distills an external page into typed entities; a separate Surfacer agent — different process, no shared memory — recovers the state from the org pod alone.
See
applications/README.mdfor the vertical framing + the layering discipline. - A first-principles affordance declaration (
-
CAS-safe
publish()— manifest updates use HTTP If-Match (RFC 7232 optimistic concurrency) with retry on 412. Fixes the read-then-write race where parallel publishes against the same pod could clobber each other's manifest entries. Cold-start usesIf-None-Match: *so two cold-start clients don't race either. -
Local-first 5-tier storage ladder —
spec/STORAGE-TIERS.mddocuments the deployment progression from Tier 0 (library only, no daemon) → Tier 1 (default — MCP auto-spawns local CSS) → Tier 4 (federated cross-pod) → Tier 5 (P2P relay-mediated). Tier 1 is zero-config; everything else inherits up the stack. Smoke tests for tiers 0/1/4 intests/storage-tiers.test.ts. -
P2P transport (Tier 5) —
src/p2p/ships a Nostr-style relay-mediated transport so mobile (claude.ai app, ChatGPT app) and desktop (Claude Code, custom MCP clients) interop with no central server we operate. Two signing schemes coexist on the wire: ECDSA (Ethereum-style address — matches the existing wallet identity used everywhere else) and BIP-340 Schnorr (32-byte x-only pubkey — for public-Nostr-relay interop). Same wallet, two pubkey representations,verifyEventauto-dispatches by format. 1:N encrypted share viaKIND_ENCRYPTED_SHARE(30043) — Tier 4's cross-pod E2EE works over P2P transport too. Seedocs/p2p.mdfor the cross-surface deployment topology + 16 passing tests intests/p2p.test.ts. -
Personal bridge —
examples/personal-bridge/is the ready-to-run reference deployment for Tier 5: a small Node process you run on your own infrastructure (laptop / Raspberry Pi / NAS / Tailscale-exposed home server). EmbedsInMemoryRelay, exposes MCP atPOST /mcp+ REST + an admin UI. One URL forever, all your devices. Local-first by default (EXTERNAL_RELAYSenv var is empty); sharing is per-publish (share_with) or per-bridge (broadcast to public Nostr relays). Seeexamples/personal-bridge/README.mdfor quick start + cross-device connection table. -
SOC 2 readiness package —
spec/SOC2-PREPARATION.md(scope, timeline, vendor inventory, mapping of Interego features to SOC 2 controls, solo-operator compensating controls),spec/policies/(15 written policies covering CC1–CC9, A1, C1, P-series),spec/OPS-RUNBOOK.md(deploy/access/key-rotation/backup procedures with current vs target state).SECURITY.md+ RFC 9116/.well-known/security.txton every container app. Operational events (deploy, access change, wallet rotation, incident, quarterly review) build into compliance-grade descriptors viabuildDeployEvent/buildAccessChangeEvent/buildWalletRotationEvent/buildIncidentEvent/buildQuarterlyReviewEventandtools/publish-ops-event.mjs— Interego eats its own dog food as the SOC 2 evidence substrate. -
Compliance grade publish + regulatory mapping (L4 conformance) —
publish_context(..., compliance: true, compliance_framework: 'eu-ai-act' | 'nist-rmf' | 'soc2')produces audit-trail-grade descriptors. Upgrades trust toCryptographicallyVerified, signs with ECDSA (secp256k1), embeds inlinecg:proofin the TrustFacet, writes a sibling.sig.jsonto the pod, auto-pins both to IPFS when configured, validates against the named framework. Wallet rotation + history supported viarotateComplianceWallet/importComplianceWallet. Seespec/CONFORMANCE.md§L4 +docs/ns/eu-ai-act.ttl/nist-rmf.ttl/soc2.ttl. -
Audit endpoints on the relay —
/audit/events,/audit/lineage,/audit/compliance/<framework>,/audit/verify-signature,/audit/frameworks. Public read; auditors verify any compliance descriptor's signature without trusting the relay. Companion:examples/compliance-dashboard.html— open in a browser, no install. -
Privacy-hygiene preflight —
screenForSensitiveContentruns inpublish_contexton both surfaces; flags API keys, JWTs, PEM keys, Luhn-valid credit cards, US SSNs, emails/phones/IPs across three severity tiers. Warning surfaced to the calling agent; never silently filtered. -
Agent enablement —
docs/AGENT-PLAYBOOK.md(operational "when X do Y" rules for any LLM driving the MCP) +docs/AGENT-INTEGRATION-GUIDE.md(one-page integrator guide for OpenClaw/Cursor/Cline/Aider/custom). Both fetched on demand viadocs://interego/playbook+docs://interego/integration-guide. SERVER_INSTRUCTIONS strengthened from descriptive to prescriptive (proactive triggers, modal defaults, error patterns). -
MCP discoverability — both stdio (
@interego/mcp0.5.0) and HTTP relay (@interego/mcp-relay0.3.0) advertise system instructions, doc resources, workflow prompts oninitialize. Prompts includepublish-memory,discover-shared-context,verify-trust-chain,whats-on-my-pod,publish-audit-record,compose-contexts,explain-interego. -
Attribute-Based Access Control (L2
abac:) — policies are typed context descriptors with SHACL predicates; attributes resolve cross-pod; sybil-resistant viafilterAttributeGraph. Seeexamples/demo-abac-cross-pod.mjs,demo-abac-sybil-resistance.mjs,demo-abac-zk-proof.mjs,demo-abac-emergent-policy.mjs,demo-abac-policy-supersession.mjs. -
Public Agent Attestation Registry (L2
registry:) — federated NPM-for-AI-agents primitive; multiple registries co-exist; reputation aggregates cross-registry. -
Capability Passport (L2
passport:) — agent biographical identity that survives infrastructure migration (framework / pod / model changes). -
Interego Name Service (L2 — attestation-based naming) — a name is a verifiable attestation (
<did> foaf:nick "alice"), not a claimed registration: federated discovery + a pluggable trust policy, no central registrar, no root. Reference runtime insrc/naming/—attestName/resolveName(forward, trust-ranked) /namesFor(reverse). No new ontology terms. Seeexamples/demo-name-service.mjs(runs offline against an in-memory pod). -
Code domain ontology (L3
code:) — first L3 domain example. Demonstrates that a non-trivial domain expresses fully on top of L1 primitives. -
RDF 1.2 + SHACL 1.2 alignment — triple-term annotations (
{| ... |}), directional language tags,sh:reifierShapevalidation per April 2026 CR/WD. -
Conformance test suite — four levels (L1 Core / L2 Federation / L3 Advanced / L4 Compliance) with badge output. Run
node spec/conformance/runner.mjs. -
Federated transactions + Constitutional layer + CRDT offline merge spec + DP+ZK aggregate spec + TLA+ proof outlines — protocol-level guarantees and design specs.
-
Runnable demo scripts in
examples/covering emergence demos, ABAC scenarios, Idehen-inspired (federated reasoning, nanotation pipeline), Verborgh-inspired (distributed affordances, cross-app interop, pod-as-graph views), agent registry, code domain. End-to-end compliance walkthrough atexamples/compliance-end-to-end.mjs—node examples/compliance-end-to-end.mjsto see ops event → check → framework report → wallet load, no live pod required. Most demos readCG_DEMO_POD/CG_DEMO_POD_Benv vars; defaults point at the maintainer's deployed pods. -
End-to-end demo scenarios in
demos/scenarios/— autonomous multi-agent runs against the real Claude Code CLI, including Demo 22 (two agents design + ratify + play a commit-reveal RPS game) and Demo 23 (four agents emerge a federated zero-copy semantic layer over heterogeneous data sources viahyprcat:/align:/amta:composition). Demos 24 and 25 are the dual-audience pilots (organizational working memory + learning). Seedemos/README.md. -
Agent-runtime integration paths —
docs/integrations/agent-runtime-integration.mdmaps five ways an OpenClaw / Hermes Agent / Codex / Cursor / Claude Code runtime can mount Interego: (1) MCP server (config-only — every substrate primitive becomes an LLM tool), (2) OpenClaw memory plugin (pod-rooted typed memory replacing the local SQLite, with a fixed 5-tool HATEOAS surface that reaches the whole substrate), (3) agentskills.io SKILL.md ascg:Affordance(skills become federated, attestable, governable via existing primitives), (4) compliance overlay (every agent action becomes a signed, framework-cited descriptor), (5) Hermes memory provider (aMemoryProviderplugin for Nous Research's Hermes Agent — same pod-rooted memory + HATEOAS shape). All five are translators, not extensions — no protocol surface added.hermes-full-substrate.md/openclaw-full-substrate.mdexplain how a runtime reaches all of Interego without tool-list bloat. -
Foxxi performance architecture (regime-first) — the
foxxi-content-intelligence/vertical routes work by work regime (Evident / Knowable / Emergent / Turbulent), not by content: a performance situation is classified before it is planned, and the endpoint refuses to silently default to a gap frame (the gap frame is correct for the Knowable regime only).regimeSourceprovenance governs calibration authority — only trajectory-derived regimes calibrate, so a caller can't assert or gap-frame its way past the invariant. Exposed as a signed, followablecontextualize-and-planaffordance an agent invokes as itself. Built and then dogfooded on the team that built it — seeENGAGEMENT-REPORT.md(full breakdown + Mermaid diagrams; openENGAGEMENT-REPORT.htmlin a browser for the rendered version) andREFLEXIVE-DOGFOOD.md.
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 (interego-relay.eastus...) | Publicly-hosted Azure deployment. OAuth-gated MCP at /mcp exposing the 8 categorical substrate verbs (mint, dereference, compose, act, restrict, extend, promote, decompose) plus 27 compatibility shims for the named-tool surface (publish_context, discover_context, register_agent, invoke_affordance, etc.) — 35 entries total. 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. Parity with the local stdio MCP server. 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 (share_with) or per-bridge (mirror to public Nostr relays via EXTERNAL_RELAYS). Tier 5 substrate. Vertical bridges run alongside this generic bridge on different ports — see applications/. |
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-Poly1305envelope with one wrapped key per authorized agent. CSS / Azure Files / IPFS pinning services see only ciphertext. Descriptor metadata (facets, manifest entries) stays plaintext so federation queries still work. Seedocs/e2ee.md. - Persistent pod state. Solid pod storage is file-backed with an Azure Files volume mounted at
/data. State survives container restarts. - Cleartext mirror for federation reasoning. Cross-descriptor relationships inside encrypted payloads —
cg:revokedIf,prov:wasDerivedFrom,cg: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
cg:Affordance,cgh:Affordance,hydra:Operation, anddcat: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
cg:affordanceblocks bycg:action, and invokes any declared capability without the harness pre-registering it. Invocations publish back as descriptors withprov:wasDerivedFromciting the source affordance — discovered capabilities carry full provenance. Seeexamples/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
cg:AuthorizedAgentwith its owndid:webidentity and X25519 keypair. The relay maps the OAuthclient_nameto 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:bob@example.com"])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:keyEd25519 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. Seedeploy/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-712transferWithAuthorization+ x402.org facilitator).
Discovery
effective_atinterval-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 (
cg:,cgh:,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:). Seedocs/ns/README.md. All terms enforced by CI lint. - CI ontology-lint gate.
tools/ontology-lint.mjsscans TS source for<prefix>:<Term>emissions and verifies each against its correspondingdocs/ns/<prefix>.ttl. New code cannot landcg:NewTypewithout a matching OWL declaration. - CI derivation-lint gate.
tools/derivation-lint.mjsenforces that every L2/L3 ontology class has explicit L1 grounding (owl:equivalentClass/rdfs:subClassOf/cg:constructedFrom/ declared primitive). Currently 91/91 grounded. - 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/ cg: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 ↔ cg: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 HTTP/SSE 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, Azure Container Apps, identity server, relay
│ ├── identity/ WebID + DID + Ed25519 + WebFinger + bearer tokens + SIWE
│ ├── mcp-relay/ HTTP/SSE 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 cg: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) ordiscover_context→ findurn:cg: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 real Azure CSS + 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.
🧑💻 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:cg: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://interego-relay.livelysky-8b81abb0.eastus.azurecontainerapps.io/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:
- Landing page / enroll: https://interego-identity.livelysky-8b81abb0.eastus.azurecontainerapps.io — passkey / wallet / DID enrollment, friendly first-time-user surface
- Your dashboard: https://interego-identity.livelysky-8b81abb0.eastus.azurecontainerapps.io/dashboard — your DID, registered credentials, pod inbox (requires you've enrolled first)
- PGSL Browser: https://interego-pgsl-browser.livelysky-8b81abb0.eastus.azurecontainerapps.io
👶 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:
- Recovery flows — what to do when you lose a credential or rotate keys
- Mobile parity — what works from phone-based clients
- OAuth setup per client — Claude Code / Cursor / Hermes / OpenClaw / ChatGPT
🛠 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
# Deploy to your own Azure (one-time)
./deploy/azure-deploy.sh
CI auto-deploys five container apps on every push to master that touches their inputs (workflow): interego-dashboard, interego-pgsl-browser, interego-relay, interego-identity, interego-css. Per-image path filters mean an unrelated change to one image's inputs won't rebuild the others.
The remaining container apps are deployed manually — they aren't wired into the workflow's matrix:
interego-foxxi-bridge(Dockerfile:deploy/Dockerfile.foxxi-bridge)interego-css-gate(Dockerfile:deploy/Dockerfile.css-gate)interego-foxxi-microsite(Dockerfile:deploy/Dockerfile.foxxi-microsite)interego-foxxi-dashboard(Dockerfile:deploy/Dockerfile.foxxi-dashboard)interego-foxxi-scorm-player(Dockerfile:deploy/Dockerfile.foxxi-scorm-player)interego-main(Dockerfile:deploy/Dockerfile.interego-main)
Manual deploy for any of those uses the standard two-step ACR build + container-app update:
# Build the image in ACR from the current checkout, SHA-tagged for clean rollback.
az acr build \
--registry contextgraphsacr \
--image <name>:<tag> \
-f deploy/Dockerfile.<name> .
# Point the running container app at the new image.
az containerapp update \
-n <containerapp-name> \
-g context-graphs-rg \
--image contextgraphsacr.azurecr.io/<name>:<tag>
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:cg:my-analysis:1' as IRI)
.describes('urn:graph:project:arch-v1' as IRI)
.temporal({ validFrom: '2026-03-20T00:00:00Z' })
.delegatedBy(
'https://id.example.com/alice/profile#me' as IRI, // owner (human)
'urn:agent:anthropic:claude-code:vscode' as IRI, // agent (AI)
)
.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 (cg:, 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
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_PODSenv 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
Azure Container Apps
cd deploy && bash azure-deploy.sh
Deploys: CSS (Solid server), Dashboard (observation UI), MCP Relay (HTTP bridge), Identity Server (WebID + DID + SIWE).
Development
npm install
npm run build # TypeScript → dist/
npm test # Vitest across the tests/ directory
npm run test:watch # Watch mode
Test Suites
| Suite | Tests | Coverage |
|---|---|---|
context-graphs.test.ts | 44 | Builder, composition, validation, serialization |
solid.test.ts | 20 | Publish, discover, subscribe, agent registry |
federation.test.ts | 21 | Pod directory, multi-pod, WebFinger, Hydra |
causality.test.ts | 38 | SCM, do-calculus, d-separation, counterfactual |
pgsl.test.ts | 31 | 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 | 23 | Gibson, Norman, OODA, BDI, Friston, stigmergy |
crypto.test.ts | 25 | Wallets, ECDSA, delegation, SIWE |
encryption-zk.test.ts | 30 | NaCl encryption, ZK proofs, selective disclosure |
sdk-extractors.test.ts | 17 | Category theory, semiotic functor |
xapi-conformance.test.ts | 60 | xAPI profile, IFI priority, result/context structure |
pgsl-coherence.test.ts | 9 | 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 | 8 scenarios: AAT enforcement, enclave merge, CRDT sync, full pipeline |
Specifications
| Document | What it covers |
|---|---|
| Interego 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 |
spec/policies/ | 15 written policies (info sec, access, change, IR, BCP, vendor, classification, encryption, SDLC, logging, AUP, retention, risk, vulnmgmt, privacy) |
spec/OPS-RUNBOOK.md | Operational procedures: deploy, access reviews, wallet rotation, backup, monitoring, quarterly + annual cadence |
SECURITY.md | Coordinated disclosure contact + severity SLA + scope. Mirrored at /.well-known/security.txt (RFC 9116) on every container app |
spec/FEDERATED-TRANSACTIONS.md | Saga pattern for cross-pod atomic writes; isolation levels; failure modes |
spec/CONSTITUTIONAL-LAYER.md | Self-amending policies; tiered ratification; graceful forks |
spec/CRDT-OFFLINE-MERGE.md | Descriptor-fragment-level CRDTs for offline-first collaboration |
spec/AGGREGATE-PRIVACY.md | Privacy-preserving aggregate queries (DP + ZK) across pods |
spec/proofs/ | TLA+ formal-spec outlines (modal lattice, supersession, ABAC composition) |
docs/AGENT-PLAYBOOK.md | Operational "when X do Y" rules for any LLM driving the MCP — proactive triggers, privacy, modal defaults, error patterns |
docs/AGENT-INTEGRATION-GUIDE.md | One-page integrator guide for AI agent harnesses (OpenClaw, Cursor, Cline, Aider, custom) |
docs/ns/eu-ai-act.ttl | EU AI Act mapping (Articles 6, 9, 10, 12, 13, 14, 15, 50) |
docs/ns/nist-rmf.ttl | NIST AI Risk Management Framework — Govern / Map / Measure / Manage |
docs/ns/soc2.ttl | SOC 2 Trust Services Criteria — CC + Availability + PI + Confidentiality + Privacy |
| Paradigm Constraints | Emergent semantics, coherence verification, decision functor |
| Progressive Persistence | 5-tier persistence, URI invariance, structural encryption |
| Presentation Notes | 10-slide W3C presentation outline with demo instructions |
docs/EMERGENCE.md | Four emergent-property demos with falsifiable success criteria |
docs/ARCHITECTURAL-FOUNDATIONS.md | Holonic hypergraphics + polygranular composition + Peircean substrate — categorical interpretation of why the protocol's choices hang together as one construction |
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 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.