1. The architecture in one paragraph
The graph database is the central organizing principle. Everything the system knows — people, agents, relationships, organizations, information, actions, events — is nodes and edges in one in-house graph. Models and agents query the graph, never the relational store (complex relationship queries are exactly what relational Postgres is bad at and a graph is for). Alongside the graph: pgvector holds embeddings for semantic search (vectors are searchable meaning, never authority), and plain Postgres tables remain for accounts and ordinary API serving only. There is exactly one context store; every permission decision is made in the graph service on every command — never in the agent layer, so it cannot be sweet-talked.
2. The primary nodes
The hierarchy runs: Ecosystem (the foundation — one server-side installation; the Genesis Ecosystem is Kiduna) → Organization (duna) → Alliance → Guild → Ally → Member. Institutions are deliberately not in the hierarchy — an Institution is a special type of Alliance (§ below). An ecosystem is created from its Genesis Profile, and everything else is created from there.
| Node | What it is | Key properties |
|---|---|---|
| Ecosystem | one installation of the server-side stack — the foundation level; ecosystems interoperate over KAP | Genesis Profile, registry refs, KAP endpoints |
| Member | a person — the Source of their ally | identity, contact points, handle (unique across members and allies; never “username”), wallet ref |
| Ally | the member’s agent — one per member, working across all dunas. Every ally is really the Genesis Ally (Ki) personalized by its Source’s context (Orchestration §1); anchored on-chain as an NFT in the Source’s wallet — transferable, and co-ownable only by transfer to a Squads wallet, whose holders then vote to instruct it as its Source | handle (unique), Source ref, Contract, NFT ref; role-personas (used in Moves) hang off it |
| Relationship | the member↔︎member bond — first-class, because trust between people is the system’s load-bearing edge; between two people it is always a relationship, never a “connection” | the two members, relationship history, and grants (§4) |
| Guild | an ad-hoc named group — the lightest social object: a sharing scope and nothing more | name, members; no wallet, no chain footprint |
| Alliance | a working group with money: shared Squads wallet, its own rules and processes | members, purpose, wallet ref, duna context (an alliance lives within a duna; membership flows through) |
| Organization (duna) | the formal unit — a legally registered DUNA with treasury, Forum, and policies. Always begins life as an Alliance; becomes an Organization when its WV Org ID validates on-chain | org ID, purpose, members, treasury + squad wallet, Forum ref, policies |
| Institution | a special type of Alliance — outside the hierarchy — that restricts membership and pays for/sponsors accounts; always tied to a registered legal entity that is not a DUNA; cannot vote | entity identity + jurisdiction, squad wallet, enrolled members (≤10 from its $1K Compute purchase), compute multiple |
| Code | trust made portable — invitation and credential in one signed object (JWT) whose claims reference the registry addresses (issuer member’s FROST wallet, ally NFT, alliance/organization Squads wallet — Protocol §4) | issuer, scope, access level, expiry, uses, binding, registry claims |
| Tool | anything the system can operate on a member’s behalf | provider (Stripe, Sphere, Google Workspace, calendars, Telegram, the browser plugin…), scopes per grant |
| Item | any shareable thing: information, wisdom, files, skills, made things (pages, bots, agents) | owner, kind, access level (§3), metadata (§5) |
| Action | a thing that can be done — every action is registered as a node so it can surface in Chat or Live identically and be permission-checked uniformly (Actions) | name, family, surfaces, role gate, level behavior, command refs |
| Record | what happened: artifacts, transcripts, renderings, seals, payouts — the audit trail and the system’s memory | refs, hashes, access level |
Supporting nodes: Wallet (member FROST / alliance & institution Squads / duna treasury), Token (each duna’s Compute; the pass/fail voting token), Forum (a duna’s decision space), Proposal (lives in a Forum; passed proposals become Policy), Training and Portal (Moves, sim-flagged — §7).
Two agent families, exactly: Allies (always of a member) and Actors (everything else — the electors, operators, performers, and background workers that do the system’s labor). There is no third kind.
3. The four access levels — one enum, everywhere
Every Item, Tool grant, Relationship, Guild, Alliance, and Organization carries exactly one of:
| Level | Meaning |
|---|---|
| public | anyone can access it, no permission needed |
| private | anyone can see it exists; access requires permission — ask the author (who sets the terms, which can include payment) or present a code |
| secret | not listed, not discoverable; a code is required even to find it |
| personal | for the member and their ally only — no grant, no code, no exception, ever |
Build note (2026-07-09): the visibility enum currently implemented in the knowledge base is public / private / personal — secret is missing and is not optional; it must land before any code-gated content ships.
This is the entire visibility model, and it is deliberately the same enum for information and for social structure (whether a relationship is visible, whether an alliance is discoverable, whether an organization appears in search). Everything added to the system is available across the whole system at the root — one store, no walls — with these levels as the only gate. Enforcement is level checks + Relationship grants (§4) + code claims, evaluated by the graph service on every command.
4. Relationships and grants
A Relationship is a stated bond with stated access. When two members connect, each side independently sets what level the other holds — over their information and their tools, per domain if they wish (“may see my open calendar slots and book them; nothing financial”). Grants live on the Relationship, are evaluated on every read and every tool call, and are changed by one sentence to your ally at any time. Relationship history accrues on the Relationship node; it is how allies authenticate and weight what they hear (Orchestration §2).
5. One store, metadata, and memory
Context about any subject is stored once, keyed to the subject, with every fact carrying its access level and its provenance. Every added Item carries four metadata fields — author, name, handle, description — enough for the middleware to judge relevance and to credit the author when the item is used. What any ally can use about you is the one store filtered through your levels and grants; changing a level is one property change that binds every agent instantly. Memory grows agentically: completed work writes Records; Records are embedded (pgvector) for retrieval; nobody ever “updates a database” by hand.
6. Money and deciding — what the database holds
All payment execution happens on the web rails and the chain (Protocol); the graph holds the organizational truth around it: engagement terms and splits as Records, balances mirrored for display, the compute meter (usage at 7× API cost against member balances). Deciding: each duna has a Forum; proposals carry the duna commands they will execute, rendered as receipts whose plain sentences the graph service generates from the commands’ own parameters — never hand-written (commands that can’t yet generate an honest sentence show their raw name until they can; Protocol §3); every member votes with one pass/fail token — equal, free (with one structural exception: members enrolled with an Institution cannot vote on proposals whose counterparty is that Institution — the graph service refuses the vote command); passed proposals execute their commands atomically and become Policy nodes, so the organization’s rulebook is a query, not a document someone maintains. Lineage lives here too: enrollment lineage is recorded off-chain (the Clan, four generations); a clan member’s Compute purchase — the only event that pays lineage — creates commission Records at the duna’s schedule, and a commission is pending (earned, recorded, not yet settled on-chain) until the purchase’s funds are on-chain: immediately for USDC, roughly monthly for fiat awaiting the bridge (Real Work, Real Money §3).
7. Moves in the data
A Training is a sim-flagged subgraph: real grammar (role-personas, actors with routines, connections, alliances, organizations, Forums), optionally real channels for exercises — and structurally no real financial edges: sim wallets and sim Compute are incapable of touching real rails. Records from trainings are real (what a member learned persists) and marked with training provenance.
Changes in v5.2: the Ecosystem node added at the foundation of the hierarchy (Genesis Profile; Genesis Ecosystem = Kiduna); members are Sources; handles (unique across members and allies, never “username”); allies are the Genesis Ally (Ki) personalized, NFT-anchored, co-ownable via Squads; Institutions redefined as a special type of Alliance outside the hierarchy. v5.0: Connection renamed Relationship (between two people it is always a relationship, never a “connection”); Games naming; build status — pgvector replacing Pinecone is live (knowledge_chunks; search/upload/delete), graph nodes for registration/onboarding/user details landing in the graph DB, internal graph event endpoint up, sharing-preferences API in progress. v4.6: lineage and pending-commission records specified in §6. v4.5: Code claims reference the registry addresses. v4.4: receipt-sentence generation fixed as a graph-service build requirement. v4.3: Institution recusal enforced at the vote command. v4.2: graph-central architecture confirmed (in-house graph + pgvector; Postgres for accounts/APIs only); Institution and Guild nodes; Action promoted to a node; Allies/Actors as the only agent families; item metadata fixed at author/name/handle/description. Full history: versions.