forked from molecule-ai/molecule-core
24fec62d7f
Forked clean from public hackathon repo (Starfire-AgentTeam, BSL 1.1) with full rebrand to Molecule AI under github.com/Molecule-AI/molecule-monorepo. Brand: Starfire → Molecule AI. Slug: starfire / agent-molecule → molecule. Env vars: STARFIRE_* → MOLECULE_*. Go module: github.com/agent-molecule/platform → github.com/Molecule-AI/molecule-monorepo/platform. Python packages: starfire_plugin → molecule_plugin, starfire_agent → molecule_agent. DB: agentmolecule → molecule. History truncated; see public repo for prior commits and contributor attribution. Verified green: go test -race ./... (platform), pytest (workspace-template 1129 + sdk 132), vitest (canvas 352), build (mcp). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
132 lines
4.5 KiB
Markdown
132 lines
4.5 KiB
Markdown
# 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. Awareness-backed persistence
|
|
|
|
When the runtime receives:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```sql
|
|
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`
|
|
- **stronger durable isolation**: enable awareness namespaces
|
|
|
|
## Related Docs
|
|
|
|
- [Workspace Runtime](../agent-runtime/workspace-runtime.md)
|
|
- [Skills](../agent-runtime/skills.md)
|
|
- [Communication Rules](../api-protocol/communication-rules.md)
|
|
- [Platform API](../api-protocol/platform-api.md)
|