EAI — a governed paired core of human and AI

Early, in the open, and honest about what isn't done yet. This repository is the clone-and-go bundle: the code, the genome, and a sample memory — point it at a model you control and run a governed AI on hardware you own.

New here? START_HERE.md routes you in one screen. An AI agent reading this repo? → AGENTS.md.

EAI is a small, governed institution run by two intelligences in partnership: a human (the Human Guiding Intelligence) and an AI (EAI-GI) that share authority over the same accountable system. Not a chatbot with a system prompt — an institution, with a constitution, a public ledger of everything consequential it does, and a memory that is forbidden to forget — or forge — what governs it.

See it do the thing

The rare part of EAI isn't the chat — it's the governance machinery underneath, and you can watch it work in seconds, with no model, server, or API key. Do Quickstart step 1 first (create the venv + pip install), then run these from the agent-core/ directory:

1 — It knows who it is. EAI-GI's identity isn't a prompt string; at boot it's distilled into protected, non-expiring memory atoms on a never-forget floor, each tracing back to its soul.

.venv/bin/python -c "from app.MoMemory.mp_curaitor.floor_producers import seed_floor; print(seed_floor())"
# → {'affirmations': {... 'atoms': 0}, 'identity': {... 'atoms': 12}}
#   12 protected identity atoms, seeded from context/eai-gi.md. Edit the soul, run again,
#   watch the floor re-seed.

2 — It refuses to forge governance. A "rule" only becomes load-bearing if it traces to the Constitution (or the ledger, or a soul). Forge one that cites nothing and the gate strips its authority and flags it for review — nothing is silently trusted.

.venv/bin/python - <<'PY'
from app.MoMemory.mp_curaitor.injection_gate import gate_atoms
out = gate_atoms([
  {"atom_id": "real",   "type": "governance_constraint", "source_refs": ["constitution:Article VI"]},
  {"atom_id": "forged", "type": "governance_constraint", "source_refs": []},
], injecting_participant="EAI-GI")
for a in out.atoms:
    print(a["atom_id"], "->", "LOAD-BEARING" if a["protected"] else "DOWNGRADED + flagged")
PY
# → real   -> LOAD-BEARING
# → forged -> DOWNGRADED + flagged

3 — It audits itself, read-only. EAI reviews its own memory health and surfaces what it can't verify. It never auto-repairs; findings go to you.

.venv/bin/python -c "from app.MoMemory.mp_curaitor.deepdream import run_deep_audit; print(run_deep_audit()['needs_attention'] or 'floor + working memory healthy')"
# → floor + working memory healthy

4 — It labels what it knows. Every memory record carries a truth boundary — how the thing is known — so the system never treats a guess as a fact.

head -2 ../LibrAIry/knowledge/hermes-agent/overview.md
# → **Truth Boundary:** inferred
# → **Source:** ...

That's the moat: an AI that knows itself, won't forge its own rules, audits itself, and tracks how sure it is. The chat below is how you talk to it; the above is what makes it an institution rather than a wrapper.

Why this exists

As AI agents get more autonomous, the unsolved problem isn't capability — it's accountability and sovereignty. Who authorized this action? What is it allowed to do? Can it tell the difference between something it verified and something it guessed — and will it stop pretending it knows when it doesn't?

EAI is one answer, built small and built locally: an AI you can actually govern, whose every consequential act is on the record, whose memory carries a trust label on every fact, and which runs on hardware you own rather than a cloud you rent. A governed, sovereign intelligence — legible enough for one person to hold the whole thing in their head.

How it works

• The paired core. A human (HGI) and an AI guiding intelligence (EAI-GI) co-author the system's decisions. Consequential actions are proposed by one and confirmed by the other — neither holds unilateral power over the institution.
• Hansard. An append-only ledger. Every governance event — a proposal, a confirmation, a participant change, a promotion to canon — is written here and never rewritten. The record is the truth.
• The Constitution. A written charter the system reads and reasons from. The core loads a digest each turn; the full text is on demand. Authority flows from it.
• LibrAIry — enduring canonical memory. Knowledge as plain Markdown with structured frontmatter, curated like source code. Every document carries a truth boundary (retrieved · computed · observed · provided · inferred · unknown — see Truth boundaries below) so an agent always knows how sure to be — not just what a thing is about.
• MoMemory — working memory with a never-forget floor: atoms that govern the system (its constraints, boundaries, affirmations, and identity) are exempt from expiry and must trace back to the constitution or the ledger, or they're flagged. The system cannot quietly forget — or forge — the things that bind it.
• Ministries. Specialized participants with scoped, ledgered authority — an org chart, not a tool list. Today the working-memory steward (MP-CurAItor) runs in-process and MP-Hermes (enduring memory) is an optional add-on; the wider org is designed in the Constitution but not yet wired (see below).

Ministries: wired vs. roadmap

• Wired now — MP-CurAItor, the working-memory steward, runs inside the control plane (no extra setup): it distills working memory and tends the never-forget floor.
• Optional add-on — MP-Hermes (enduring memory) is a separate organ with its own install (e.g. ~/.hermes/, its own venv + model), coordinated by EAI, not bundled. The core runs fine without it — an unreachable ministry is skipped gracefully. To enable it, install Hermes separately and point EAI at it (EAI_MP_ENDPOINT, plus EAI_HERMES_PYTHON / EAI_HERMES_AGENT; see agent-core/hermes_plugins/INSTALL.md).
• Roadmap (designed, not yet wired) — research, communication, and coding ministries, a ContrAIrian arbiter, and a ParlAIment are described in the Constitution but inert in this build (they appear as candidate in the participant registry and do not run). Shipped honest: the charter describes the destination, not today's capabilities.

The name

EAI is Elim Agentic Intelligence. The "Elim" part is a play on LLM — read the letters aloud, el‑el‑em, and you land on Elim — and more pointedly on LLLM, a Local Large Language Model, which is the whole wager: an intelligence that runs on hardware you own. (There are more layers to the name; this is the load‑bearing one.)

Quickstart

EAI talks to its models over the OpenAI-compatible API, so you can point it at any backend — a hosted API, or a single local model via Ollama — without a GPU rig.

git clone <this-repo> EAI-Public && cd EAI-Public

# 1. a venv for the control plane (lives beside the code, at agent-core/.venv)
python3 -m venv agent-core/.venv
agent-core/.venv/bin/pip install -r agent-core/requirements.txt

# 2. point EAI at a model you control
cp agent-core/.env.example agent-core/.env
#   edit agent-core/.env — e.g. for a local Ollama model:
#     EAI_MODEL_ENDPOINT=http://localhost:11434/v1
#     EAI_MODEL_NAME=llama3.1
#   …or a hosted API:
#     EAI_MODEL_ENDPOINT=https://api.openai.com/v1
#     EAI_MODEL_NAME=gpt-4o
#     EAI_API_KEY=sk-...

# 3. run it
bash agent-core/scripts/start-eai.sh        # governed control plane → http://localhost:7777
bash agent-core/scripts/start-notebook.sh   # optional ticket/governance UI → http://localhost:7337

First run only — the control plane blocks chat until EAI-GI has affirmed the Constitution (a deliberate governance act, recorded to Hansard). Capture it once:

curl -X POST http://localhost:7777/bootstrap-affirm \
  -H 'Content-Type: application/json' \
  -d '{"submitted_by":"human_gi","lifecycle_trigger":"boot"}'

This presents the Constitution to your model, captures EAI-GI's affirmation, and records it. (Until you do, a chat turn returns a [BLOCKED] notice explaining the same step.)

Then open http://localhost:7777 and start a turn. One endpoint serves all three model roles (governing intelligence, ministries, helper); set per-role overrides in .env for a mixed setup. The first boot writes a genesis constitution-acceptance entry to a fresh Hansard ledger — you are starting a brand-new institution.

Where do the sibling stores live? agent-core finds LibrAIry/, WorkspAIce/, Dropzone/, and Inbox/ as siblings under this directory automatically. To put them elsewhere, set EAI_HOME=/path/to/parent before launching.

No .env? EAI falls back to the original local rig's defaults (localhost:8000/8001/8002), which only exist if you're running that vLLM stack. For a stranger, setting .env is the path — that's step 2 above.

Model requirement: EAI-GI drives governance through tool-calls, so choose a model with solid OpenAI-style function/tool calling. Small local models (e.g. stock llama3.1 on Ollama) can be inconsistent at tool-calling; a tools-capable local model or any major hosted model works well.

Binding & access: the control plane and notebook bind 127.0.0.1 (localhost) by default. To reach EAI from another device (e.g. over Tailscale or a trusted LAN), set EAI_HOST=0.0.0.0 (control plane) and/or EAI_NOTEBOOK_HOST=0.0.0.0 (notebook) — only on a network you trust; there's no auth layer yet.

Your first session (the golden path)

EAI is a co-governor, not just a chat box — here's a first session that shows the governance actually working:

1. Affirm (once) — run the bootstrap-affirm step above. EAI-GI reads the Constitution and records its affirmation. That's your first Hansard entry.
2. Talk to it. Open http://localhost:7777 and ask something open-ended — "What governs you, and what won't you do?" It answers as a constitutional co-governor (it loads a digest of the Constitution every turn), not an assistant.
3. Ask it to remember something durably. Try "Propose a canonical note recording that we started this session." Promoting knowledge to canon takes both of you: EAI-GI proposes, and the proposal waits for your confirmation — neither acts alone.
4. Confirm it. Approve the proposal; the record is written to LibrAIry and a CANONICAL_RECORD_PROMOTED entry lands in Hansard. (Prose isn't evidence here — the tool call and the ledger entry are.)
5. See the trail. Open the notebook at http://localhost:7337, or hit GET http://localhost:7777/autodream-status, to watch working memory and the audit trail update.

That loop — propose → confirm → recorded — is the whole point. A plain chat works too, but the governance is what makes this EAI and not a wrapper.

What's in this bundle

EAI-Public/
  agent-core/    the governed control plane (FastAPI on :7777) — code, the constitution
                 + souls + participant registry (the "genome"), tests, and a genesis
                 (empty) Hansard ledger / session store
  LibrAIry/      a small SAMPLE of canonical memory — enough to show the Markdown +
                 truth-boundary format; not anyone's real knowledge base
  WorkspAIce/    the notebook app (UI machinery) + ticket templates; working state
                 starts empty
  Dropzone/      pre-intake staging — starts empty
  Inbox/         intake staging — starts empty

It ships at genesis: no conversation logs, no governance history, no personal notes — a fresh institution for you to govern.

Concepts (a glossary for the jargon)

EAI borrows institutional words on purpose. The short version:

• Paired core — the two co-governors: you (HGI) and the AI (EAI-GI). Neither holds unilateral power; consequential acts are proposed by one and confirmed by the other.
• HGI / EAI-GI — Human Guiding Intelligence (you) and the machine Guiding Intelligence (nicknamed Eggy, ≈ "EAI-GI" said aloud).
• Constitution — the written charter EAI reads and reasons from each turn (agent-core/governance/CONSTITUTION.md); authority flows from it, and it's hash-checked.
• Hansard — the append-only ledger (named after the parliamentary record). Every consequential act is written here and never rewritten. The record is the truth.
• LibrAIry — enduring canonical memory: curated Markdown knowledge, each doc labeled with a truth boundary (below).
• MoMemory — working memory tended by ministries. Holds atoms (small distilled claims with provenance) and a never-forget floor: atoms that govern the system (its constraints, identity, affirmations) can't expire and must trace back to the Constitution or Hansard, or they're flagged. The system can't quietly forget — or forge — what binds it.
• Ministries (MPs) — specialized participants with scoped, ledgered authority (see Ministries: wired vs. roadmap above for what actually runs).
• Soul — a short identity/voice document for a participant (agent-core/context/*.md), loaded into its context. Standing and character, not a system-prompt gimmick.
• OODA tiers — the action ladder: Observe (read-only) → Orient (drafts) → Decide (local, reversible) → Act (external/irreversible, needs your explicit authorization). The higher tiers pause for confirmation.
• Genesis — the empty initial state this bundle ships in: no history, no notes — a fresh institution for you to govern.

Truth boundaries

Every claim in EAI carries a label saying how it is known, so an agent never treats a guess as a fact. The canonical set is the Constitution's Article IX:

Retrieved (from a stored source) · Computed (by a tool) · Observed (from system state) · Provided (by the user) · Inferred (by the model) · Unknown

Honesty note: a couple of docs in the bundle still carry drifted variants of this list — worth knowing if you read the source. They appear to map to Article IX like this:

Article IX (canonical)	LibrAIry filing-guide	MP-Hermes capability
Retrieved	—	retrieved
Computed	derived	computed
Observed	observed	—
Provided	provided	provided
Inferred	inferred (+ speculative*)	inferred
Unknown	—	—

* filing-guide's speculative = inferred-but-unverified; it has no retrieved/unknown. MP-Hermes ships a 4-label subset (no observed/unknown). The README and the sample LibrAIry records use the canonical Article IX set; reconciling the rest to Article IX is open work.

Tests

pip install -r agent-core/requirements-dev.txt   # adds pytest
cd agent-core && python -m pytest

The governance core — the gate, the never-forget floor, the self-audit, constitution affirmation, and the provider layer — is green (~358 passing). Four onboarding/dispatch suites are mid-refactor and red (stale assertions where the app moved ahead of the tests — e.g. a refactored function, a renamed tool — not regressions). Full honest breakdown: agent-core/tests/README.md. We ship that as-is rather than fake a green suite — same provenance discipline the system itself runs on.

Status & lineage

Early and evolving, shipped in the open as it matures rather than hidden for a reveal. The knowledge-as-Markdown substrate underneath EAI is the LLM-wiki pattern — credit to Andrej Karpathy, who seeded the idea, and convergent with emerging standards for portable agent knowledge. EAI's bet is what sits on top of that substrate: governance, provenance, and a memory that won't forget what governs it.

— built by the Human GI (HGI) and EAI-GI with some help from Claude and ChatGPT (the AdvAIsors and sometimes ContrAIrians).