⚡ Nokido

Building an artificial organism — not just another AI agent

A local-first runtime that lets local models, cloud providers and coding agents work as one organism — routed, remembered, regulated and gated — on your machine, with your hardware, for your data.

MCP clients & runtimes :

LLM providers (20 vendors · 39 routed slots, by use-case) :

Languages: English · Français · Español · 简体中文 · Português · 日本語 · Deutsch · العربية

Full documentation (nothing removed): docs/README_complet.md — translated full versions: docs/i18n/README_complet.<lang>.md

🧭 In one minute

Nokido is the organism layer around the models: one MCP hub that clients reach, while the system — memory, regulation, gates — persists across sessions. The client stays disposable; the organism does not.

• Routing across local and cloud models by use case, with a local fallback and free-tier quota tracking.
• Long-term memory with provenance — FTS5/BM25 + BGE-M3 (1024-d) vector retrieval, fused and reranked.
• Regulation of CPU, RAM, queues and providers — homeostasis, reflexes, circadian cycles.
• Deterministic gates around actions — AST checks, secret scanning, six-ring RBAC, egress control.
• Agent messaging (M2M, swarms, ACP, A2A) and introspection of its own code and state.

Nokido keeps apart what is declared, observed and verified: a port that answers does not prove a model is loaded, and a probe that cannot look reports ILLISIBLE (unreadable), never “no”.

🧬 Architecture

                              NOKIDO
                        DIGITAL ORGANISM
                               │
        ┌──────────────────────┼──────────────────────┐
     NERVOUS                IMMUNE                 ENDOCRINE
      SYSTEM                SYSTEM                  SYSTEM
   events / routing       firewall / RBAC       resource regulation
   M2M / protocols        membrane / trust      quotas / pressure
        └──────────────────────┼──────────────────────┘
                  ┌────────────┴────────────┐
                MEMORY                   MUSCLES
           RAG / FTS / vectors      workers / tools / execution
                  └────────────┬────────────┘
                        CENTRAL INTEGRATION
                     Hub / MCP · ACP / A2A / M2M / SWARM
                               │
                 neural substrate: SNN / edge / NPU → future neuromorphic

Every module declares its organ (__FORGE_COLOR__) and the census forge_module_census --check keeps the anatomy complete in CI. Details: the organism · memory and retrieval · homeostasis · swarm cognition.

🚀 Quick start

From PyPI — nokido-agent 0.20.16, published after the install proof on Linux, Windows and macOS. The complete organism, its pinned components (checksums verified), then the hub:

pip install "nokido-agent[organisme]==0.20.16"
nokido-composants --tout          # deno, llama.cpp, models, knowledge pack, local token
nokido-doctor                     # what this machine has, lacks, or cannot read
nokido-hub                        # then: curl http://localhost:8766/health

Client only (talks to an existing hub): pip install nokido-agent==0.20.16.

Alpha. The package published on PyPI installs with pip (see the block above), and each release is proven to install on Linux, Windows and macOS before PyPI serves it. The cloned repository remains the reference path for the full organism — services, Deno supervisor, local models — until the one-command full install is delivered.

From a clone — the path CI itself uses:

git clone https://github.com/Nokido-labs/nokido.git
cd nokido
python -m venv .venv
.venv\Scripts\activate          # Linux / macOS: source .venv/bin/activate
pip install -r requirements.txt
python tools/nokido_doctor.py   # what this machine has, lacks, or cannot read
python tools/nokido_hub.py

With Docker (hub + Ollama):

cp Nokido.env.example Nokido.env
docker compose -f docker/nokido/docker-compose.yml --profile core up -d

Then curl http://localhost:8766/health should answer. pyproject.toml declares 17 extras (plus the all and full bundles). Requirements, Docker / native paths and verification: installation · verify · first use.

🔌 Connect a client

The hub serves MCP on http://localhost:8766/mcp. Supported clients and transports:

Each client gets its own agent token from the vault; an anonymous caller stays at ring 3. ACP (server and client) and an A2A Tier-1 surface complete MCP. Setup: 04 — MCP clients · 24 — Cloud peers.

The hub also exposes GET /api/graph/proprioception: imports / imported-by / call-graph per file, computed from the AST index of its own source.

🔬 Project status

Each line pairs a declared maturity with the evidence in this repository; tools/forge_capability_audit.py fails CI when a ✅ has no evidence or a paused service is shown as operational. For the living state, ask the body: nokido-doctor --vivant (from a clone: python tools/nokido_doctor.py --vivant).

                                  DECLARED             EVIDENCE IN THIS REPOSITORY
ANATOMY / ORGANISM
  Strict anatomical census        ✅ achieved          `forge_module_census` --check, 0 unclassified
  CI architectural gate           ✅ achieved          `anatomie` gate, blocking since 2026-09-06
  M2M memory separation           ✅ achieved          `forge_db_path`: one switch read by every process
  Emergency homeostasis           ✅ achieved          `NokidoHomeostasis` + `forge_homeostasis_orchestrator`
  Sleep / circadian regulation    🟡 partial           all 6 phases fire on measured inactivity (`forge_circadian_runner --auto`); 4 of their 10 service targets disabled by policy

COMMUNICATION
  MCP                             ✅ operational       `NokidoMCP` hub, enabled by default
  ACP                             🟡 partial           client side operational (`NokidoAcpWorker` drives claude, codex, opencode, agy sessions); server `NokidoAcpWs` disabled by default
  A2A Tier-1                      ⏸️ paused            `NokidoA2A`, disabled by default (code present)
  M2M                             ✅ operational       `forge_m2m_protocol` validator (intents, pointers)
  Swarm                           🟡 hardening         `forge_swarm` family: NR in CI for 13 of 14 modules (not the base one)

COGNITION
  AMI                             🟡 active            `forge_world_model` + `forge_ami_strategist`
  Active Inference                🟡 active            `forge_active_inference`; homeostat coupling = prototype
  Neuro-symbolic governance       ✅ operational       `NokidoGateConsumer` + `forge_golden_rules_ast`
  Autonomous evolution            🟡 guarded           `forge_mutation_judge`: one gate (owner arming, brake, human lock) + auto-brake on capability regression

PHYSIOLOGY
  Endocrine                       ✅ operational       `NokidoHormonesListener` + `forge_endocrine`
  Nervous system                  ✅ operational       `NokidoAfferent` + `NokidoOrganPulse`
  Immune system                   🟡 partial           `forge_semantic_firewall` + `forge_sovereign_membrane`
  Cortex ↔ autonomic loop         🟡 first piece       `forge_epistemic_daemon`: epistemic drive (gap → inquiry); full coupling not built

NEURAL SUBSTRATE
  Software SNN                    ✅ experimental      `forge_snn_core` + `forge_snn_router`, on demand
  NPU / edge                      🟡 in development    `NokidoBrainWorker`, disabled by default since 2026-07-24
  Neuromorphic hardware           🔬 future            —

Nokido is an alpha-stage research and engineering project; what it does not claim (AGI, guaranteed self-healing, production stability for every subsystem…) is written in the full README.

🔐 Security

Secrets live in a machine vault (DPAPI · Keychain · libsecret), never in .env. Callers get an integrity ring (six-ring RBAC); outbound text crosses the SemanticFirewall and the SovereignMembrane before any cloud model; the hub binds to localhost and cloud access is opt-in. Read SECURITY.md before exposing anything beyond localhost, and disclose vulnerabilities privately first. Model: 07 — Security · 08 — Vault and secrets.

📚 Documentation

• Full README — idea, organism, protocols, installation paths, roadmap, principles
• Wiki index (EN / FR) · What's new
• Architecture · Hardware roadmap
• MANIFESTO.md (French original) · English translation
• CONTRIBUTING.md · CODE_OF_CONDUCT.md · docs/CLA.md

License

AGPLv3-or-later · commercial licensing available — see LICENSE and COMMERCIAL.md.