docs: add docs/architecture/memory.md

content/docs/architecture/memory.md

@@ -0,0 +1,131 @@
+# 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)