Skip to content

Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.

11.6 KB
Raw Blame

Private, evidence-backed agent learning

Learning loop v2 (2026-10-05)

A created agent has one endless chat (MASTERPLAN §2.10), so its learning is paced and kept tidy instead of firing after every answer:

  • Review windows (dodaios/society/review_cadence.py). The person's turns collect in a window per chat. The window is reviewed as a whole when the person gives a clear learning signal (an explicit "remember", a lasting language choice, a correction or frustration, detected without a model), after 6 of their turns, after 8 tool steps, or on the next turn once the window is older than 12 hours. There is no timer: an idle agent costs nothing. Turns started by Dodaios, teammates or routines keep their per-turn review. Board messages in the window never count as the person's words.
  • Better review rules (dodaios/society/review.py, _LEARNING_RULES). A correction is the strongest signal; a lesson is one rule plus one clause of why; skills are improved before new ones are made, and a new skill covers a class of work. Environment failures the person can fix, "tool X does not work" claims, transient errors, one-off narratives and unresolved failures are never captured. Unattended reviews remove an entry only on the person's own retraction.
  • Notebook limits (dodaios/society/memory_books.py, HARD_LIMITS, twice the prompt budget). Past it, an agent or its review must consolidate (replace or remove) before adding; the review is told how full each notebook is. The person's own explicit requests are never refused.
  • Skill lifecycle (dodaios/society/skill_lifecycle.py). Each private skill has a usage record. Unused for 14 days it is stale, for 30 days archived: left out of the briefing, never deleted, active again once it is run or rewritten. The briefing lists at most 12 skills, most recently used first, so a long-lived agent's prompt does not grow with every skill.
  • Visible learning. Memory writes and learned skills already post a line into the agent's chat (memory_updated, learned_skill).

The seat rule below is unchanged: reviews and skill authoring run only on the agent's own seat.

Status (2026-09-30): the experience journal described below (dodaios/society/experience.py, learning/LEARNING.md, the lead's voice learning snapshot and tests/contract/test_agent_learning_loop.py) is not in the current tree; a history reconciliation merge removed it. Society agents learn through their USER.md/MEMORY.md notebooks and the turn review in dodaios/society/review.py. Dodaios' own learning is docs/dodaios-learning.md.

Seat rule (2026-09-30): an agent's turn review and skill learning run on exactly that agent's seat — the provider, model and auth mode its chat uses (dodaios/society/seat_brain.py). No other provider, subscription or key is asked. A review whose seat keeps failing costs at most four seat calls in total, spaced by a jittered backoff, and is then dropped (status dropped) with one log line. The attempt count and next due time are stored on the review row, so neither a burst of turns nor a restart adds calls; concurrent drain requests are coalesced into one extra pass.

Tier: T3 capability. Dodaios and every Society agent use the same portable learning loop, with separate ownership, files, review locks and provider scopes.

Behavior

  1. Each completed or failed chat turn enters the durable review queue. Voice completion queues Dodaios' own user feedback without waiting for a model.
  2. Failed tool results produce conservative warnings even if no review model is available. These warnings never claim that a remedy was verified.
  3. The existing provider-independent reviewer extracts useful facts, corrections, successful methods and failure lessons. Every accepted lesson must quote a single actual source of the appropriate class. Assistant prose is not proof.
  4. Later chat turns retrieve applicable private lessons and record their IDs against the turn receipt. Existing facts and private draft skills remain available. Dodaios' chat now participates in the same completion lifecycle.
  5. Explicit user corrections can retire an obsolete lesson. Explicit negative evaluations can suspend reuse. Merely retrieving a lesson or finishing a turn does not increase its measured benefit.

Voice uses an IO-free cached snapshot populated after runtime startup and after Dodaios reviews. It takes effect on the next existing realtime instruction refresh or new session; it does not force an extra provider connection or interrupt speech. Voice completion lacks verified tool outputs, so it learns direct user feedback but cannot manufacture a successful procedure from tool names alone.

Persistence and isolation

Existing facts remain in the configured vault at society/<agent-id>/memory.md. The application data directory contains these additional private files:

Path under society/<agent-id>/ Purpose
learning/journal.json Authoritative lessons, source receipts, exposures, evaluations
learning/LEARNING.md Readable projection; automatically repaired after interrupted writes
learning/journal.lock OS-released interprocess write lock
skills/ Existing private procedural skills, still drafts

Dodaios owns the reserved identity jarvis; its multiple chats and voice sessions share that identity. No ordinary agent retrieves Dodaios' learning or another agent's facts, lessons or skills. Agent IDs are validated without lossy slug normalization. Linked namespaces, linked journals and cross-owner journal copies are refused. Private memory read/modify/write operations also use a file lock.

The shared BrainManager also enforces the boundary: Society turns receive only their own briefing, written-response style and turn language. Dodaios' global profile, core memory, ambient wiki and pending global skill triggers are excluded, and Society turns cannot feed Dodaios' global curator. Missing private briefings fail closed on both API and CLI seats rather than falling back to Dodaios' identity.

The conversation database is the existing durable queue, scoped by session and explicit owner. Different agents review concurrently; turns of one owner are serialized. Failed reviews retry with exponential backoff and jitter, and resume after restart. Per-owner FIFO order prevents an older retry from undoing a newer correction. Idempotent receipts prevent duplicate learning and evaluation. Cancelled background tasks are awaited during shutdown before storage closes.

Evidence and trust

Feedback requires a direct user source; procedures require successful tool evidence; failures require failed tool evidence. Credentials are excluded from learning input and persistence. Lesson writes reject recognizable instruction injection and invisible formatting characters. These checks supplement, rather than replace, source labels and the normal ToolExecutor permission boundary. Learned text is advisory and never grants authority or activates draft skills.

The journal measures retrieval and user-attributed benefit/harm. These are operational evidence, not a claim of causality or a general intelligence score. The deterministic contracts prove state transitions and prompt integration; the live probe demonstrates one controlled project-specific planning improvement.

Verification

  • Contract: tests/contract/test_agent_learning_loop.py, including restart, strict scope, concurrent writers, poisoned input, corrections, negative feedback, failed turns, independent reviews and Dodaios chat/voice integration.
  • Regression: the Society, agent-chat and realtime session suites, plus existing conversation-continuity contracts.
  • Opt-in live proof: python scripts/verify_agent_learning.py --provider grok. It uses fresh temporary data and the existing provider registry, reviewer, ToolExecutor, completion hooks and prompt builder. No secret is printed. The selected provider can be changed; no provider is required by the feature.
  • Live observation: Grok returned UNKNOWN before learning, validate_larch_manifest after a user correction and full runtime restart, and UNKNOWN for another agent. One lesson was persisted; no reviews remained. The same proof passed after installing the application into a fresh Linux container with preinstalled portable dependencies and providing only one Grok credential through stdin. No host data directory or credential files were mounted. This probe caught and fixed a reviewer edge case: a user correction classified as an unexecuted skill now becomes grounded feedback instead of being discarded.
  • Windows Society/chat/realtime regression: 888 passed, three environment skips. The outdated API-only seat assertions and incomplete realtime confirmation doubles are corrected; all 15 previously reported baseline failures are resolved.
  • The expanded parallel Python verification passed 1,189 tests with three skips. CI preserves its test selection and passing-count floor, distributing complete test files across four workers to avoid the serial suite's job timeout.
  • Frontend verification passed all 4,338 tests and the production build. Stale composer, folded-trace and GPT-Live fixtures were updated; themed dropdowns retain required-choice validation. CLI gates and their 317 focused tests pass.
  • The rebuilt entry bundle is 1,086.6 KB against the unchanged 1,350 KB budget. Portrait rendering and inactive chat surfaces load on demand; the selected UI language and its fallback are ready before the first render. Cold locale loading, rapid language selection and deferred portrait lifecycles have focused tests.
  • The portable install gate passes all 24 advertised CPython/OS/architecture cells. uv.lock matches the existing project version and declared dependency constraints, including the PDF version already pinned in requirements.txt.
  • The four routing/output/hangup/language guards plus learning contracts passed (620 tests, one environment skip). A later Linux run passed all 27 learning contracts, including symlink isolation.
  • The final shared-brain isolation change passed 136 prompt, skill-routing, turn-override, continuity and learning tests, with one environment skip.
  • The isolated boot-budget probe passed: window 2,371 ms, interactive 19,358 ms, voice-ready 19,921 ms. These measurements are a regression check, not a promise that another machine will reach the same timings.

The implementation uses pathlib, JSON, SQLite, asyncio and the existing filelock dependency on Windows, Linux and macOS. The native symlink test can skip on Windows accounts without symlink permission; Linux runs that test. Native macOS CI passed the realtime and private-learning contracts at dc053c1d0 (55 passed, two capability skips). See the native macOS execution log. The final local Linux learning/continuity run passed all 51 tests.

Hermes reference

Reference inspected: NousResearch/hermes-agent, HEAD 44945d224c2ccd6e0a55f16223c7ab0dd39331bf (2026-09-19), and its persistent-memory documentation. Relevant ideas are private profiles, concise persistent memory, source recall, and procedural skill reuse. Dodaios extends these ideas with per-owner concurrent review, failure learning, exact-source checks, correction retirement, replay-safe receipts and explicit reuse measurements. Since 2026-10-05 a few well-separated portions are adapted from the upstream project under its MIT License; each carries a header comment, and the list lives in third_party/hermes-agent/.