ShugoCore

A continuous orchestration layer for synthetic functional agency.

ShugoCore coordinates models, tools, and a four-tier memory system so that an artificial agent can act in an environment, register the consequences, and adapt - indefinitely, without context degradation or unbounded state growth.

Where a chat model produces text, a functionally agentic system produces effects: decisions that become tool calls and API interactions, outcomes that become reward signals, and experience that consolidates into durable knowledge. ShugoCore is the layer that makes that cycle safe, auditable, and able to run continuously.

Design principles

Continuous. Long-running agency fails when memory is naive: the context window exhausts, or raw logs grow forever. ShugoCore's memory pipeline consolidates, decays, and promotes continuously so the observe-act loop can run for as long as the mission requires.

Functional. Decisions terminate in execution. Every action is gated by deterministic world-model invariants before it touches the environment, and every outcome is recorded as a structured episodic event that feeds reinforcement learning.

Accountable. Agency without accountability is unsafe. Hard constraints live in a read-only world model (Tier 3) that the agent's own execution path cannot rewrite, and every decision and outcome is logged.

Bounded. Every subsystem is capacity- or decay-bounded: ring-buffered episodes, salience-decayed facts, iteration-capped autonomous cycles, and a decoupled maintenance worker that never blocks the primary loop.

The orchestration loop

1. OBSERVE      task arrives; reasoning tokens enter the Tier 0 scratchpad
2. GATE         Tier 3 invariants check the action before anything runs
3. DECIDE       models are selected and aggregated, enriched with Tier 2 context
4. EXECUTE      the execution layer performs the tool / API interaction
5. EVALUATE     reinforcement learning turns the outcome into a reward signal
6. RECORD       the event lands in the Tier 1 episodic buffer
7. CONSOLIDATE a decoupled worker compresses episodes into Tier 2 facts,
                decays stale salience and prunes forgotten knowledge

System architecture

Memory architecture

[ Tier 0: Scratchpad / Working Memory ]  <-- Unfiltered Token Stream (In-Context)
                  |
                  v (Consolidation Pipeline)
[ Tier 1: Episodic / Short-Term Memory ]  <-- Event Logs, Recent Tool Execution (FIFO / Sliding)
                  |
                  v (Decay & Summarization Engine)
[ Tier 2: Semantic / Long-Term Memory ]  <-- Entity Maps, Consolidated Facts (SQLite + Vectors)
                  |
                  v (Abstraction / Generalization)
[ Tier 3: Core Identity & World Model ]   <-- System Invariants, Permanent Rules (Read-Only)

Memory dynamics

• Active consolidation (compression): episodic events are drained and summarized into compact semantic facts in Tier 2; raw logs are flushed.
• Decay & pruning (forgetting): Tier 2 salience decays exponentially since last access; re-accessed memories are reinforced on retrieval and low-salience memories are pruned.
• Selective promotion: critical failure modes and recurring patterns in Tier 1 are promoted into Tier 2 as high-salience procedural insights.
• Tier 2 -> Tier 3 review: MemoryManager.review_promotion_candidates() surfaces frequently re-accessed, high-salience facts; elevation into the world model stays an explicit privileged step (promote_to_core).

Isolation model

• Tier 0 / Tier 1 are created per MemoryManager (per-agent isolation - no cross-task context contamination).
• Tier 2 / Tier 3 are shareable: pass the same SemanticMemory / CoreIdentity instances into multiple MemoryManagers so planning nodes see one consistent world model.
• Consolidation, decay and pruning run in a daemon worker thread and never block the observation-action loop; use consolidate_now() for deterministic, synchronous control.

Safety model

Functional agency must be bounded by rules the agent cannot rewrite in the course of acting. Enforcement is layered, so bypassing any single component defeats nothing:

Key properties:

• Single gated path. Interactive tasks, autonomous cycles and the task queue all execute through DecisionEngine.execute_task - the autonomous loop cannot bypass the gate.
• Read-only at runtime. The world model changes only through the privileged promote_to_core() path, which requires operator attribution (authorized_by=) and appends to the Tier 3 ledger.
• Fail-closed everywhere. Missing verdict, missing consent, missing approval channel, unknown host, unknown command - all refuse.

Android & mobile compute nodes

ShugoCore runs on Android as a first-class ROS 2 participant (v1.1.0). One phone can be a sensor, an offload target, a teleop pendant, or a fully offline agent - the role is a config switch, and the same gated DecisionEngine path runs everywhere.

Transports: in-process JavaBridgeROS2Interface (Chaquopy + jros2 / Fast-DDS) or RosBridgeInterface (rosbridge JSON-over-WebSocket, the Termux path). AndroidRuntime maps the Android app lifecycle onto the agent, streams power and thermal state into the fallback controller (sustained thermal elevation pauses compute), and resolves secrets from the Android Keystore.

Accelerator selection is a policy, not a constant: acceleration.py prefers NPU → DSP → GPU → CPU per workload, degrades on device failure and demotes to CPU-only at thermal level 2 - always with a deterministic CPU fallback, so nothing breaks on hardware without an NPU.

The Kotlin-side reference client (bridge contract + Gradle app shell) lives in clients/android/; the full integration guide - wire topics, security model, launcher matrix, SoC accelerator cheat-sheet, Termux fallback - is docs/android_integration.md.

On-device model execution runs against the app's embedded llama.cpp engine (JNI, no external launcher required) or standard local launchers: ShugoCore probes llama.cpp (/health), Ollama (/api/tags) and LM Studio (/v1/models), and every backend URL must pass the loopback + port allowlist check before the first prompt leaves the process.

Android node control plane (v1.9.0)

The Android app is the management console for an embodied AI node: an always-visible NODE STATUS header (agent online, model, inference mode, memory, sensors n-of-n, human, policy, network, temperature, battery) above SERVER / AGENT / SENSORS / SECURITY / LOG tabs. Every row renders real runtime state via a getNodeSnapshot() service binder call — no decorative indicators.

• SERVER — the embedded llama.cpp engine serving an Ollama-compatible API on 127.0.0.1:11434 (native libraries are 16 KB page-size aligned for Android 15+ devices), four health indicators (MODEL LOADED / INFERENCE READY / API READY / AGENT READY), live request/token/latency counters, a GGUF model catalog with download/select, and a backup-server fallback: stopping the local stack while a desktop backup URL is configured re-points the agent at the backup and keeps it running. A MODEL TEST panel runs one controlled decision round-trip and shows Parse VALID/INVALID, the failure class (no response / invalid protocol / valid protocol), latency and the truncated raw response.
• AGENT — subsystem statuses, the current cycle with the last decision / action / evaluation taken from the Tier 1 head, the OBSERVE→GATE→DECIDE→EXECUTE→EVALUATE→RECORD→CONSOLIDATE pipeline with only the stages that actually ran highlighted, and memory tiers 0–3.
• SENSORS — a capability contract, not a permissions page: Android hardware → runtime permission → capability declaration → live stream → explicit agent acknowledgement, so the agent never assumes a capability exists just because Android granted a permission.
• SECURITY — Android permissions vs. agent authority shown as separate states, network posture with real enforcement (loopback always; LAN / internet fail-closed by default), tool allowlists, and the policy flags (fail-closed, audit, consent).
• LOG — a live category-filtered feed (MODEL / AGENT / SENSOR / POLICY / MEMORY / ERROR) backed by a ring-buffer log bus that both the Kotlin runtime and the Python agent write to.

Every DECIDE cycle terminates in a record, formalized as an outcome contract — SUCCESS, NO_ACTION (a model that answers but proposes nothing executable is a healthy, recorded cycle, not an error), POLICY_BLOCK, GOVERNOR_BLOCK, TASK_FAILURE, BACKEND_FAILURE (the model ensemble was unreachable), IN_FLIGHT, ENGINE_FAILURE — and the stage trail shows only the stages that actually ran. The decision prompt itself is generated from the engine's real action schema (available_action_types()), so the model can only ever be offered actions policy and execution actually support — including the always-safe record_observation internal action, which is also the rule-based fallback's target after three consecutive unproductive model cycles. The Kotlin↔Python boundary speaks JSON (get_status_json, recent_logs_json, update_capabilities_json, …) so no state is lost to crossing the runtime edge.

Desktop server mode (no high-end phone needed)

Users with a device older than the 2020 mid/high-tier recommendation can run the full agent on a desktop (macOS / Linux / Windows) and pair the phone as a lightweight node. The phone's AndroidBackend points at the desktop via the "Desktop server URL" field in the app - zero client protocol changes, because the desktop speaks the same Ollama wire contract plus the engine API.

pip install shugocore
shugocore-server --backend ollama --model qwen3.5:latest --host 0.0.0.0

Endpoints on the server:

Backends: ollama (default), llamacpp, openai, stub (offline tests). Full setup for each OS: docs/desktop_server.md.

Multi-agent networking with Shogunet

ShugoCore integrates with Shogunet for networking between multiple Shugocore agents. This enables fleet-wide collaboration over 5G, 4G, WiFi, LoRa, and Bluetooth networks with a codependent memory mesh.

Network action types

Side-effecting network actions require operator consent and approval, following the same pattern as other side-effecting actions.

Quickstart

from decision_engine import DecisionEngine
from shugonet_bridge import (
    ShugonetExecutionHandler,
    register_network_handlers,
   attach_network_fallbacks,
)
from agent_runtime import ShugonetAgentRuntime

# Create and connect the Shogunet runtime
runtime = ShugonetAgentRuntime(
   agent_id="agent-001",
    host_tcp_host="127.0.0.1",
    host_tcp_port=9000,
    host_relay_url="http://127.0.0.1:9001",
)
runtime.connect_to_host()

# Create the execution handler
shogonet_handler = ShugonetExecutionHandler(runtime)

# Create the decision engine with the network handler
engine = DecisionEngine(
    models=models,
    vector_db_config={'type': 'chroma'},
    shogonet_handler=shogonet_handler,
)

# Or register handlers after engine creation
register_network_handlers(engine.execution_layer, runtime)
attach_network_fallbacks(engine.fallbacks)

Network fallback triggers

Integration architecture

The shugonet_bridge.py module follows the same pattern as robotics_handler.py and mobile_nodes.py:

1. Action types are defined in policy.py and added to KNOWN_ACTION_TYPES
2. Execution handler dispatches network actions to the Shogunet runtime
3. Fallback severities are registered in the deterministic fallback controller
4. Handler registration occurs during DecisionEngine initialization

The bridge uses duck-typed contracts, so the Shogunet runtime can be swapped with any compatible implementation.

Continuous agent daemon

The "press go" entry point for continuous synthetic functional agency::

python3 continuous_agent.py --interval 2.0 --max-iterations 1000

This runs the README orchestration loop (OBSERVE → GATE → DECIDE → EXECUTE → EVALUATE → RECORD → CONSOLIDATE) as a bounded daemon:

• Iterations - --max-iterations caps loop passes (unlimited by default).

• Deadline - --max-seconds caps wall-clock runtime.

• Budget - every task flows through the governor's per-task step budget and deadline; a pathological task cannot stall the loop.

• Safety - the fallback controller can latch PAUSED / SAFE_STATE / HALTED at any moment; when PAUSED the loop sleeps instead of spamming refusals. Loop errors are reported to the fallback controller as continuous_loop_error triggers, so a stuck loop latches a safe state deterministically.

From Python::

from continuous_agent import ContinuousAgent

agent = ContinuousAgent(models=[...], interval=2.0, max_iterations=100) agent.start() agent.await_stop()

The daemon emits telemetry spans per loop pass (via telemetry.py) and exposes a status() snapshot (loops, tasks, successes, failures, governor state, fallback mode, Tier 1 backlog, Tier 2 fact count) for dashboards and the Shogunet network bridge.

Verifiable embeddings & privacy hardening

• Ethics checks are now real: can_explain requires a non-stub model and a writable audit chain; detect_bias scans task content for sensitive-attribute stereotypes and loaded language;is_privacy_compliant requires audit capability and rejects secret-key leakage in content; can_audit requires an operational audit chain (an empty fresh chain is auditable; a missing file is not). The policy gate enforces all four before any model call or execution.

• Deterministic hashing embeddings: vector_db.hashed_embedding() replaces the all-zero placeholder vectors with a dependency-free hashing bag-of-words embedding (matching SemanticMemory._embed，so environment observations are now actually searchable in cosine space an injected embedding_fn lets callers plug in real embedding models.

Fleet-shared memory (PostgreSQL + pgvector)

By default Tier 2 semantic memory is local SQLite (semantic_memory.db). For multi-agent deployments - the persistence half of the Shogunet memory mesh - several agents can share one PostgreSQL-backed knowledge base::

pip install 'shugocore[postgres]'

Then point memory_db_path at a DSN (a one-line config change; the engine routes it through pg_memory.open_semantic_memory())::

from pg_memory import open_semantic_memory
from decision_engine import DecisionEngine

engine = DecisionEngine(models=models,
                        memory_db_path="postgresql://user:pw@db:5432/fleet")

• Drop-in parity - PgSemanticMemory implements the full SemanticMemory surface (facts, entity graph, salience reinforce/decay/prune), so it can also be passed explicitly via DecisionEngine(semantic_memory=...) or MemoryManager(semantic=...).
• Embedding parity - identical deterministic hashing embeddings to the SQLite backend, so facts written by one agent on one backend are retrievable with the same similarity scores by another agent on the other.
• Server-side vector search - cosine distance is computed by pgvector (<=>); for fleet scale add an HNSW index (recipe in the module docstring).
• Fail-closed - missing psycopg2 or an unavailable pgvector extension raises with actionable instructions at construction; there is no silent local-fallback that would pretend to persist fleet memory.
• Tier 2 only - Tier 0/1 stay per-agent and Tier 3 stays read-only local, preserving the memory invariants (N0-N1) across the fleet.

One-time server prerequisite: CREATE EXTENSION vector; (pgvector).

Installation

Requires Python 3.9+.

From PyPI (recommended):

pip install shugocore

From the GitHub release (identical artifacts):

pip install https://github.com/SamurAI-Official/ShugoCore/releases/download/v1.10.0/shugocore-1.10.0-py3-none-any.whl

From source:

git clone https://github.com/SamurAI-Official/ShugoCore.git
cd ShugoCore
pip install -r requirements.txt          # core dependency: requests
python decision_engine.py                # run the built-in demo

Optional extras:

• websocket-client - rosbridge (WebSocket) transport for Termux-based Android nodes
• torch - enables CUDA/accelerated device selection (CPU-only mode without it)
• chromadb - enables persistent vector storage in vector_db.py (stub mode without it)
• shugonet - Shogunet networking runtime for multi-agent fleets (shugonet_bridge.py)
• psycopg2-binary - PostgreSQL + pgvector fleet-shared Tier 2 memory (pg_memory.py)

Published on PyPI - the v1.10.0 wheel built from this tree is also attached to the GitHub release.

Quickstart

from decision_engine import DecisionEngine

models = [
    {'id': 'gpt-4', 'type': 'text', 'weight': 0.5, 'backend': {'type': 'stub'}},
    {'id': 'deepseek', 'type': 'text', 'weight': 0.3, 'backend': {'type': 'ollama'}},
    {'id': 'llama', 'type': 'text', 'weight': 0.2, 'backend': {'type': 'ollama'}},
]

engine = DecisionEngine(
    models=models,
    vector_db_config={'type': 'chroma'},   # stub mode without chromadb
    news_api_key=None,                     # or set SHUGOCORE_NEWS_API_KEY
    memory_db_path='semantic_memory.db',   # Tier 2 storage
   audit_path='audit_chain.jsonl',        # tamper-evident audit chain
)

# Tier 3 invariants gate every task before execution
result = engine.execute_task({'type': 'test', 'content': 'say hello'})

# Side-effecting actions need an operator consent grant AND an approval:
engine.consents.grant('api_call', granted_by='operator')
engine.approvals.attach_operator(lambda request: True)  # operator channel

# Decisions carry long-term context retrieved from Tier 2
decision = engine.make_decision({'type': 'test', 'content': 'say hello'})
print(decision['memory_context'])

engine.shutdown()  # flushes episodic memory into Tier 2, stops maintenance worker

Autonomous operation

# Generate, execute, learn, consolidate - with a hard iteration cap
tasks = [engine.autonomy.generate_task("test", "collect environment readings")]
engine.autonomy.autonomous_learning_cycle(tasks, max_iterations=10)

# Adapt to new environment data; observations persist in Tier 2
engine.autonomy.adapt_to_environment({"mode": "field", "temperature": 22})

# Review which Tier 2 facts proved durable enough to become permanent rules
candidates = engine.memory.review_promotion_candidates(min_salience=2.0,
                                                       min_access_count=3)
for fact in candidates:
    print(fact["content"], fact["salience"], fact["access_count"])
    # Promotion is an explicit, operator-attributed privileged step:
    # engine.memory.promote_to_core("rule_key", "operator-approved rule",
    #                               authorized_by="operator")

Testing

python -m unittest discover -s tests -v     # 504 tests, no native deps

Beyond security and integration regression tests (v1.2.0), the suite includes hardware-facing stress suites:

• Lifecycle - 200 create/pause/resume/destroy cycles, concurrent pause/resume races, monitor resilience against bridge exceptions and garbage sensor data, power edge cases (boundary thresholds, plugged-in overrides, non-numeric battery values), and 25 node start/stop cycles asserted leak-free at the thread level.
• ROS 2 transports - bridge death mid-run, post-shutdown publish, malformed and non-object JSON packets, concurrent publish bursts under the rate limiter, emergency-stop bypass, round-trip payload fidelity, and rosbridge reconnect after socket drop.
• Thermal - ladder demotion at each level, 1000-cycle oscillation soak, combined thermal + power violations, streak/recovery semantics.
• Model execution - launcher detection and generation exercised against a real loopback HTTP double (tests/fake_llama_server.py) that speaks the llama.cpp, Ollama and LM Studio wire protocols with injectable failure modes: hang, HTTP 500, malformed JSON, empty choices, artificial latency.
• Android control plane - the capability-acknowledgement contract, the Chaquopy-safe JSON boundary calls, DECIDE-cycle semantics (every cycle terminates in a record), policy enforcement points, and the agent's honest stage trail — exercised against the same Python tree that is bundled into the APK (tests/test_android_control_plane.py).

A sensor_node soak runs for 5 seconds at 20 Hz against the pure-Python fake bridge and asserts monotonic heartbeats plus bounded, non-runaway output - this is the startup-routine safety check for real hardware.

To validate model execution against a genuine llama.cpp server:

SHUGOCORE_LIVE_LLAMA_URL=http://127.0.0.1:8080 python -m unittest tests.test_live_llama -v

Memory configuration

MemoryManager knobs (tuned when constructing MemoryManager directly; DecisionEngine uses these defaults):

Project structure

ShugoCore/
├── decision_engine.py        # orchestration entry point; single gated path
├── human_interaction.py      # human-interaction contract: observation bus + presence
├── autonomy.py               # autonomous task generation and learning cycles
├── model_manager.py          # model registry and performance tracking
├── subconscious.py           # structured-decision prompts via backends
├── model_backends.py         # Ollama HTTP / OpenAI-compatible / stub adapters
├── execution_layer.py        # verdict-verified, allowlisted execution
├── policy.py                 # capability registry, approval broker, consent
├── security.py               # secrets, redaction, rate limiting, breakers
├── audit.py                  # hash-chained audit log (+ verifier CLI)
├── reinforcement_learning.py # reward signals and weight updates
├── task_manager.py           # bounded queued task execution
├── state_machine.py          # execution interlocks (stall / budget / breaker)
├── fallbacks.py              # deterministic fallback controller
├── vector_db.py              # optional ChromaDB integration
├── logging_manager.py        # structured, redacted logging
├── memory_system.py          # four-tier memory architecture
├── ros2_interface.py         # ROS 2 abstraction (stub + rclpy)
├── robotics_handler.py       # robotics execution handler (e-stop, watchdog)
├── gazebo_simulation.py      # Gazebo/Ignition simulation layer
├── moveit_planner.py         # MoveIt 2 motion planning layer
├── simulation/               # physics simulation framework
│   ├── base.py               # BaseSimulation interface
│   ├── mujoco_sim.py         # MuJoCo physics backend
│   ├── stub_sim.py           # Deterministic stub fallback
│   ├── scenarios.py          # Standardized test scenarios
│   └── robots/               # Robot model definitions
│       ├── base.py           # RobotModel interface
│       ├── berkeley_humanoid_lite.py
│       ├── reachy2.py
│       └── unitree_g1.py
├── acceleration.py           # NPU / DSP / GPU / CPU accelerator policy
├── android_bridge.py         # JavaBridge + rosbridge transports, payload codec
├── android_runtime.py        # Android lifecycle, power/thermal monitor
├── android_node.py           # on-device node roles + launcher detection
├── mobile_nodes.py           # host-side mobile fleet management
├── shugonet_bridge.py        # multi-agent networking via Shogunet
├── telemetry.py              # telemetry hooks
├── token_budget.py           # context budgeting
├── version.py                # SemVer, frozen for the 1.x series
├── clients/android/          # reference Kotlin bridge client + Gradle shell
├── platforms/android/        # Android node app: 5-tab control-plane UI (ui/),
│                             #   runtime/ layer (log bus, node state, sensor
│                             #   capabilities), embedded llama.cpp JNI server,
│                             #   bundled Python agent (src/main/python)
├── docs/android_integration.md  # Android integration guide
├── tests/                    # security, integration & hardware-stress tests
└── requirements.txt

Runtime artifacts (semantic_memory.db, logs) are local and gitignored.

Roadmap

• Pluggable embedding backends for Tier 2 (current: dependency-free hashing vectors)
• PostgreSQL + pgvector storage option for shared multi-process deployments
• Entity/relation graphs alongside vector similarity in Tier 2
• Per-agent memory policies (isolation vs. sharing profiles)
• HMAC-signed audit chains and remote log shipping
• Human approval UI beyond the programmatic broker API
• Operator approval surface on the Android SECURITY tab (ApprovalBroker integration)
• Camera / microphone / GPS live-stream display in the SENSORS tab
• Per-model backend pools with health-based routing
• CI trusted publishing to PyPI via GitHub Actions (OIDC, no static token)
• Android llama.cpp-compatible host server for Termux (self-hosted launcher path)
• NPU bring-up on real devices (Snapdragon Hexagon / Dimensity APU) against the acceleration ladder
• Fleet dashboard for mobile nodes: pairing state, thermal headroom, offload telemetry

Contributing

Issues and pull requests are welcome. Please keep changes consistent with the architecture's invariants: Tier 0/1 stay per-agent, Tier 2/3 stay shareable, and nothing in the standard execution path may mutate Tier 3. Hardware-facing changes must keep the lifecycle, thermal, transport and model-execution stress suites green (python -m unittest discover -s tests).