Concepts / Architecture

Core runtime stays separate from infrastructure.

localmelo is organized around one rule: melo/ contains the agent runtime and contracts; support/ contains config, backends, providers, onboarding, and gateway infrastructure. Track 2 keeps online working context separate from Hippo's durable memory routing.

online loop verified memory policies evolving sleep pipeline planned

Overall diagram

The diagram shows the online path from user ingress to final answer, plus the offline sleep pipeline that is intentionally still a future personalization track. Memory is shown as a Track 2 session boundary: the agent-facing cache stays fast while Hippo routes durable writes. Click a component to inspect responsibilities and important files.

Reading guide: solid lines are runtime data flow, dashed lines are model/provider or offline paths, and the amber dashed region marks checker validation boundaries.

melo - core agent runtime

support - infrastructure

checker - validation boundary validates: ingress · plan · execute · memory

User / Client

CLI or HTTP

infra

Gateway

sessions · HTTP

planner model consumer

Agent / Planner

main loop · orchestration

store model consumer

Memory

working + Hippo branches
history stays raw

executor

Executor

tools · builtins · policy

offline

Sleep

future personalization

planned offline workflow
preprocessing / training /
evaluation / promotion

infra model layer

Providers

LLM · Embedding contracts

infra

Backends

local · cloud · registry

infra

Config / Onboard

TOML config · probes

data flow

model / provider

checker boundary

fail to replan

Track 2 / Memory Session

Memory subgraph

When the agent decides a candidate is worth remembering, v1 keeps the agent-side decision as a bool and sends the same candidate to two branches: working for active context and Hippo for durable or specialized placement. Long-term writes wait for a rehearsed working-memory signal or another strong write signal.

online session

agent Remembered candidate bool=true proposal, not a storage decision

working Working memory short-lived active cache with LRU-style refresh; only rehearsed memories can become long-term candidates

hippo Hippo router chooses NEW, UPDATE, RELATED, CONFLICT, or IGNORE; long-term writes await rehearsal

promotion gate: fresh -> rehearsed before long-term persistence

durable and specialized memory

Long / Profile one physical long store in v1; semantic, episodic, profile, and reflection metadata kinds

Tools authoritative registry plus procedural skill/template memory; no checker bypass

Personalized filtered sleep samples for Track 4, not raw runtime history

History append-only task and step records for debugging, audit, replay, and provenance only

Working branch

Reused active memories are touched or compacted so the current task context stays bounded and fresh. Only rehearsed memories can become long-term candidates.

Hippo branch

Hippo owns classification, metadata, provenance, relation links, conflict handling, and whether a write is immediate or deferred to sleep.

Extensible shape

The same subgraph pattern leaves room for later agent, executor, and sleep diagrams without forcing those concerns into the memory session view.

Boundaries to preserve

Boundary	Rule	Why it matters
`melo/` to `support/`	`melo/` must not import infrastructure implementations.	The runtime stays portable and testable.
Agent to executor	Tool calls go through checker and workspace policy.	Unsafe shell/file operations are rejected before execution.
Agent to memory	The agent proposes a remembered candidate; working memory and Hippo receive it in parallel after checker limits apply.	The agent stays independent of SQLite, vector search, profile tables, tool memory internals, and sleep samples.
History to PersonalizedMemory	`PersonalizedMemory` only receives selected sleep samples; it must not ingest raw history directly.	Track 4 receives curated training inputs without turning the audit log into online recall or training data by default.
Backends	Local backends are connectors only.	Runtime management belongs outside localmelo core.

Implementation status

Implemented

Online runtime

Direct CLI, gateway routing, built-in tools, checker boundaries, backend registry, and provider contracts are in place.

Active

Memory system

Track 2 now treats working memory and Hippo as parallel branches. The five-action Hippo controller, metadata-typed profile memory, procedural tool memory, and selected sleep samples are the active design direction.

Planned

Sleep pipeline

Training and evaluation modules are scaffolds. The next step is a design issue, not immediate implementation.