molecule-core/docs/architecture/memory.md

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

Scope	Meaning	Intended use
LOCAL	visible only to the current workspace	private scratch facts and local recall
TEAM	visible to the local team boundary	handoffs between a parent and its direct children, or siblings under the same parent
GLOBAL	readable across the tree; writable only from the root side	org-wide guidance, standards, shared institutional knowledge

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. Memory v2 plugin (memory_records / memory_namespaces)

This is the production-direction backend, behind the RFC #2728 HTTP contract. The plugin runs as a sidecar on each tenant EC2 (auto-spawned by entrypoint-tenant.sh when MEMORY_PLUGIN_URL is set), owns its own tables under the memory_plugin schema, and serves:

• POST /workspaces/:id/v2/memories (canvas MemoryInspectorPanel)
• GET /workspaces/:id/v2/memories
• DELETE /workspaces/:id/v2/memories/:id
• runtime tools commit_memory_v2, search_memory, commit_summary, forget_memory
• legacy MCP tool names commit_memory / recall_memory via the scope→namespace shim in mcp_tools_memory_legacy_shim.go

Capability negotiation (FTS, embedding, TTL, pin, propagation) is declared by the plugin via GET /v1/health; workspace-server adapts the tool surface to what the plugin actually supports. See memory-plugin-v1.yaml for the full wire contract.

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

Flat shared memory model	Molecule AI HMA
easy to over-share	scopes align to hierarchy
unclear ownership	each memory belongs to a workspace and a scope
recall and procedure blur together	memory stores facts, skills store repeatable procedure
hard to govern	org structure and memory rules reinforce each other

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
• semantic / FTS search across memories: use the v2 plugin endpoints (/v2/memories?q=…); they go through the plugin's pgvector + tsvector indexes when the plugin declares the capability

Related Docs

• Workspace Runtime
• Skills
• Communication Rules
• Platform API