Memory, Tiers & Tools

Hierarchical Memory Architecture, the runtime tier system, and tools & capabilities.

Part of the Comprehensive Technical Documentation. Definitive reference based on a non-invasive scan of the molecule-core repository.

9. Hierarchical Memory Architecture

Three Scopes

Scope	Visibility	Write Access	Use Case
LOCAL	This workspace only	Self	Private scratch facts, reasoning, working state
TEAM	Parent + children + siblings	Self	Handoffs, coordination, team-level knowledge
GLOBAL	Readable by all workspaces	Root only	Org-wide policies, standards, institutional knowledge

Four Memory Surfaces

Surface	Storage	Endpoint	Purpose
Scoped agent memory	`agent_memories` table	`POST /workspaces/:id/memories`	HMA-backed distributed memory with scope enforcement
Key/value workspace memory	`workspace_memory` table	`POST /workspaces/:id/memory`	Simple structured state, UI-visible, optional TTL
Activity recall	`activity_logs` + `agent_memories`	`GET /workspaces/:id/session-search`	"What just happened?" contextual recall
Awareness-backed	External service	Same tool interface	When `AWARENESS_URL` + `AWARENESS_NAMESPACE` configured

Memory → Skill Compounding Flywheel

Task execution
  → Durable insight captured in LOCAL/TEAM memory
  → Repeated success patterns detected (repetition signal)
  → Memory row promoted → SKILL.md package created
  → Hot-reload (~3 seconds) → skill injected into live runtime
  → Agent Card updated → broadcast to peers via WebSocket
  → Future tasks use promoted skill → faster + more reliable
  → Organization becomes more capable over time

Key property: promotion events are visible in activity logs. Skills are inspectable in Canvas Skills tab. This is not hidden prompt inflation.

10. Runtime Tier System

Tier	Name	Container Flags	Use Case
T1	Sandboxed	Read-only rootfs, tmpfs /tmp, 512 MiB, no `/workspace` mount	Untrusted code, text-only analysis
T2	Standard (default)	Read-write, 512 MiB, 1 CPU, `/workspace` mount	Most agent workloads
T3	Privileged	`--privileged`, `--pid=host`, Docker network access	Internal tooling, elevated operations
T4	Full Access	T3 + `--network=host` + Docker socket mount	System-level orchestration, DevOps

Unknown tier values default to T2 for safety. Applied via provisioner.ApplyTierConfig() during container creation.

16. Tools & Capabilities

Workspace Tools (`workspace/builtin_tools/`)

Tool File	Purpose	RBAC
`memory.py`	HMA memory `commit_memory()` / `search_memory()`	memory.write, memory.read
`delegation.py`	A2A delegation to peer workspaces with retry + tracing	delegate permission
`approval.py`	Human-in-the-loop approval flow with polling/WebSocket	approve permission
`audit.py`	RBAC enforcement + audit trail logging	audit enforcement
`compliance.py`	OWASP Agentic compliance checks	compliance check
`governance.py`	Microsoft Agent Governance Toolkit integration	policy evaluation
`hitl.py`	Multi-channel HITL (dashboard, Slack, email)	hitl.bypass_roles
`sandbox.py`	Code execution (subprocess or Docker backend)	sandbox access
`telemetry.py`	OpenTelemetry span creation and tracing	trace emission
`awareness_client.py`	Awareness namespace memory wrapper	memory scope
`security_scan.py`	CVE and security scanning (pip-audit/Snyk)	security audit
`temporal_workflow.py`	Temporal.io workflow integration	workflow engine
`a2a_tools.py`	A2A delegation helpers and route resolution	delegate/receive

Built-In MCP Tools (from `.mcp.json`)

Server	Purpose
`molecule`	20+ platform management tools (workspace CRUD, chat, memory, teams, secrets, files, approvals)
`awareness-memory`	Persistent cross-session memory via Awareness SDK

On this page