Memory Architecture (HMA)

Molecule AI's memory model is built around one principle:

memory boundaries should follow organizational boundaries.

That is the purpose of HMA: Hierarchical Memory Architecture.

The Three Scopes

These are the scopes exposed through the runtime memory tools:

• commit_memory(content, scope)
• search_memory(query, scope)

What Exists In The Current Implementation

There are multiple memory surfaces, and the distinction matters.

1. Scoped agent memory (agent_memories)

This is the HMA-facing storage used by:

• POST /workspaces/:id/memories
• GET /workspaces/:id/memories
• runtime tools commit_memory / search_memory

It stores durable facts with a LOCAL, TEAM, or GLOBAL scope.

2. Workspace key/value memory (workspace_memory)

This is the simpler key/value surface used by the canvas Memory tab:

• GET /workspaces/:id/memory
• POST /workspaces/:id/memory
• DELETE /workspaces/:id/memory/:key

It is useful for structured per-workspace state and optional TTL entries. It is not the same thing as scoped HMA memories.

3. Activity recall (session-search)

GET /workspaces/:id/session-search provides a thin recall surface over recent activity rows and memory rows. It is for “what just happened in this workspace?” rather than long-term semantic storage.

4. Awareness-backed persistence

When the runtime receives:

AWARENESS_URL=...
AWARENESS_NAMESPACE=workspace:<id>

the same memory tools keep the same interface, but durable memory writes/reads are routed through the workspace's awareness namespace.

This is the current production direction of the memory boundary: stable tool surface, stronger backend isolation.

Access Model

Molecule AI's memory rules follow the same hierarchy logic as communication rules:

• LOCAL belongs to one workspace
• TEAM follows the immediate team boundary
• GLOBAL is readable widely but writable only from the root side

The platform-side memory handlers still apply reachability checks for shared/team reads instead of trusting callers blindly.

Current Schema Reality

The current agent_memories migration is intentionally simple:

CREATE TABLE IF NOT EXISTS agent_memories (
    id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    workspace_id UUID REFERENCES workspaces(id),
    content      TEXT NOT NULL,
    scope        VARCHAR(10) NOT NULL CHECK (scope IN ('LOCAL', 'TEAM', 'GLOBAL')),
    created_at   TIMESTAMPTZ DEFAULT now(),
    updated_at   TIMESTAMPTZ DEFAULT now()
);

pgvector is not enabled by default in the shipped migration. The repo keeps vector support as an optional future extension, not as a current hard dependency. The docs should reflect that explicitly.

Why This Architecture Matters

Memory To Skill Promotion

Molecule AI intentionally separates:

• durable fact storage
• repeatable operational procedure

The documented promotion path is:

1. a durable workflow is captured in memory
2. repeated success becomes a signal
3. the workflow is promoted into a skill package
4. the runtime hot-reloads that skill

This is why memory and skills are presented as adjacent systems, not one merged blob.

Practical Summary

If you need:

• private agent recall: use LOCAL
• shared team handoff knowledge: use TEAM
• org-wide guidance: use GLOBAL
• simple UI-visible structured state: use workspace_memory
• recent decision/task recall: use session-search
• stronger durable isolation: enable awareness namespaces

Related Docs

• Workspace Runtime
• Skills
• Communication Rules
• Platform API