Shared memory database with per-agent namespaces for multi-agent architecture

[kovtcharov]

Problem

The current MemoryStore (#542) is designed for a single monolithic agent. The GaiaAgent architecture (#674) introduces multiple agents (GaiaAgent + DocAgent + FileAgent + ShellAgent + WebAgent + future use-case agents) that all need persistent memory — but with per-agent isolation AND cross-agent visibility.

Design: Shared Database, Per-Agent Namespaces

One database (~/.gaia/memory.db) accessible by all agents, with per-agent tables that track each agent's own state, plus shared tables for cross-agent data.

Per-Agent Tables (namespaced by agent_id)

Each agent automatically gets its own namespace for:

-- Conversations: each agent tracks its own interactions
CREATE TABLE agent_conversations (
    id TEXT PRIMARY KEY,
    agent_id TEXT NOT NULL,          -- "gaia", "doc_expert", "file_expert", etc.
    session_id TEXT,
    role TEXT,                       -- "user", "assistant", "system"
    content TEXT,
    context TEXT,                    -- JSON: what task, who delegated, etc.
    created_at TIMESTAMP
);
CREATE INDEX idx_agent_conv ON agent_conversations(agent_id, created_at);

-- Tool calls: each agent tracks its own tool usage
CREATE TABLE agent_tool_history (
    id TEXT PRIMARY KEY,
    agent_id TEXT NOT NULL,
    tool_name TEXT,
    tool_args TEXT,                  -- JSON
    result TEXT,
    success BOOLEAN,
    duration_ms INTEGER,
    error TEXT,
    task_id TEXT,                    -- Which task triggered this (#675)
    created_at TIMESTAMP
);
CREATE INDEX idx_agent_tools ON agent_tool_history(agent_id, tool_name);

-- Tasks: each agent tracks tasks it created or was assigned
CREATE TABLE agent_tasks (
    id TEXT PRIMARY KEY,
    agent_id TEXT NOT NULL,          -- Agent that owns/was assigned this task
    created_by TEXT NOT NULL,        -- Agent that created the task
    title TEXT,
    status TEXT DEFAULT 'pending',
    context TEXT,                    -- JSON
    result TEXT,                     -- JSON
    created_at TIMESTAMP,
    completed_at TIMESTAMP
);

-- Insights: each agent tracks what it has learned
CREATE TABLE agent_insights (
    id TEXT PRIMARY KEY,
    agent_id TEXT NOT NULL,
    category TEXT,                   -- "preference", "fact", "pattern", "error", "skill"
    content TEXT,
    confidence REAL DEFAULT 0.5,
    source TEXT,                     -- "user_correction", "observed_pattern", "task_outcome"
    context TEXT,                    -- JSON: when/where this was learned
    created_at TIMESTAMP,
    last_accessed_at TIMESTAMP
);
CREATE INDEX idx_agent_insights ON agent_insights(agent_id, category);

Shared Tables (cross-agent)

-- User profile: shared across all agents
-- GaiaAgent writes preferences, specialists read them
CREATE TABLE user_profile (
    key TEXT PRIMARY KEY,
    value TEXT,
    source_agent TEXT,               -- Which agent learned this
    confidence REAL,
    updated_at TIMESTAMP
);

-- Agent directory: who exists and what they can do
-- Syncs with Agent Registry (#612)
CREATE TABLE agent_directory (
    agent_id TEXT PRIMARY KEY,
    display_name TEXT,
    capabilities TEXT,               -- JSON: list of capabilities
    model TEXT,
    status TEXT,                     -- "active", "idle", "unavailable"
    last_active_at TIMESTAMP
);

Access Patterns

class AgentMemory:
    """Per-agent memory interface. Each agent gets its own instance."""
    
    def __init__(self, agent_id: str, db: MemoryStore):
        self.agent_id = agent_id
        self.db = db
    
    # --- Own data (scoped to this agent) ---
    def log_conversation(self, role, content, context=None): ...
    def log_tool_call(self, tool, args, result, success, duration): ...
    def store_insight(self, category, content, source): ...
    def get_my_insights(self, category=None, limit=20): ...
    def get_my_tool_history(self, tool=None, limit=50): ...
    
    # --- Cross-agent data (read any agent's data) ---
    def get_agent_insights(self, agent_id, category=None): ...
    def search_all_conversations(self, query, agent_id=None): ...
    def get_user_profile(self, key=None): ...
    def update_user_profile(self, key, value): ...
    
    # --- Agent discovery ---
    def list_agents(self, status=None): ...
    def get_agent_capabilities(self, agent_id): ...

How Each Agent Uses Memory

GaiaAgent (orchestrator):

• Writes: user preferences, personality observations, delegation patterns
• Reads: all agent insights (to know what specialists have learned), user profile
• Learns: "User prefers concise responses", "DocAgent works better for financial docs"

DocAgent (specialist):

• Writes: document quality observations, query patterns, indexing results
• Reads: user profile (to know context), own previous tool history
• Learns: "This document has poor OCR quality", "User frequently asks about Q3 revenue"

FileAgent (specialist):

• Writes: file access patterns, bookmark history, frequently accessed paths
• Reads: user profile, own tool history
• Learns: "User's project files are in ~/Work/", "CSV files are usually in ~/data/"

Any agent can read any other agent's insights — this is how the system builds collective intelligence. DocAgent learns about document quality, GaiaAgent reads that insight and tells the user "That PDF has poor OCR — results may be less accurate."

All-to-All Memory Visibility

GaiaAgent writes: "User prefers morning briefings"
  → EmailAgent reads this → schedules digest for 8am
  → CalendarAgent reads this → includes daily agenda

DocAgent writes: "sales_report.pdf has 45 indexed chunks"
  → GaiaAgent reads this → tells user "Your sales report is ready to query"
  → FileAgent reads this → knows not to re-index this file

FileAgent writes: "User frequently accesses ~/Work/gaia4/"
  → GaiaAgent reads this → suggests "Want me to index your GAIA project?"
  → ShellAgent reads this → uses as default working directory

Integration with Existing Issues

• MemoryStore: persistent memory data layer (SQLite + FTS5) #542 MemoryStore — Extend schema with per-agent namespace tables. Keep the existing conversations, knowledge, tool_history tables but add agent_id column.
• MemoryMixin: 5 memory tools + 3 lifecycle hooks for any agent #543 MemoryMixin — Each specialist agent gets MemoryMixin, which initializes AgentMemory(agent_id=self.agent_id)
• Agent decomposition: GaiaAgent (0.6B) orchestrates specialized sub-agents for tool use #674 GaiaAgent — GaiaAgent reads cross-agent insights to coordinate effectively
• Agent MCP Server: task creation, agent assignment, and inter-agent communication #675 Agent MCP Server — Task completion results are auto-logged to memory

Dependencies

• MemoryStore: persistent memory data layer (SQLite + FTS5) #542 — MemoryStore (extend with agent_id namespace)
• MemoryMixin: 5 memory tools + 3 lifecycle hooks for any agent #543 — MemoryMixin (per-agent initialization)
• Agent decomposition: GaiaAgent (0.6B) orchestrates specialized sub-agents for tool use #674 — GaiaAgent architecture (consumer)
• Agent MCP Server: task creation, agent assignment, and inter-agent communication #675 — Agent MCP Server (task results → memory)

Acceptance Criteria

• Each agent has isolated namespace for conversations, tools, tasks, insights
• Any agent can read any other agent's insights (cross-agent visibility)
• User profile is shared and writable by any agent
• FTS5 search works across all agents or scoped to one
• Tool calls auto-logged with agent_id
• Task completion results auto-stored in memory
• Memory survives agent restarts (SQLite persistence)
• Concurrent access safe (WAL mode + threading.Lock per existing MemoryStore: persistent memory data layer (SQLite + FTS5) #542 design)

[kovtcharov]

Clarification: Memory Access Rules

Read: any agent can read any agent's memory.
Write: agents can ONLY write to their own namespace.

This prevents agents from corrupting each other's state while enabling collective intelligence.

class AgentMemory:
    def __init__(self, agent_id: str, db: MemoryStore):
        self.agent_id = agent_id
    
    # WRITE — own namespace only
    def store_insight(self, content, category): ...      # writes to self.agent_id
    def log_tool_call(self, tool, args, result): ...     # writes to self.agent_id
    def log_conversation(self, role, content): ...       # writes to self.agent_id
    
    # READ — any agent's data
    def get_insights(self, agent_id=None): ...            # None = own, or specify any agent
    def search_conversations(self, query, agent_id=None): ...
    def get_tool_history(self, agent_id=None): ...
    
    # SHARED — read/write by any agent
    def get_user_profile(self, key=None): ...
    def update_user_profile(self, key, value): ...       # source_agent recorded

[CorellisOrg]

The "write own namespace only, read any other" rule is exactly right, and it's the single most important invariant to enforce at the storage layer rather than at the API layer. Running this pattern in production for ~8 weeks with ~28 agents, a few observations that might be useful when you land the SQL:

1. "Enforce at the DB, not in Python."
Our first pass was Python-level — AgentMemory.__init__ stamped agent_id and the write helpers checked it. Worked until one agent accidentally imported another agent's memory module with a different agent_id hardcoded, and silently wrote to the wrong namespace for a day. Now we enforce at the SQLite/connection layer: each agent's process gets a connection that has agent_id bound as a session variable, and writes go through a trigger that rejects mismatched agent_id. Defense in depth — Python bug class becomes SQL rejection.

2. agent_insights.category will become a schema-in-string.
We started with freeform categories too. Within 3 weeks we had ~140 distinct category values from agents typo-fighting each other ("coding", "code", "dev", "programming", "software"). A small enum + free-text subcategory is the sweet spot — structured enough to query, loose enough to not slow agents down. YMMV but worth designing in early; retrofitting categories is painful.

3. Two cross-agent table patterns you'll want that aren't in the design yet:

• shared_facts: immutable, append-only, signed by writer_agent_id. For "X is true as of time T" facts agents need to coordinate on (user preferences, environment facts). Append-only makes conflict resolution trivial.
• agent_corrections: when agent A detects agent B did something wrong, A can log a correction. B reads its own corrections on next start. This is how our fleet self-improves without a supervisor in the loop. The key design: corrections are signed/attributed, so bad correctors lose weight over time.

4. The task_id FK on agent_tool_history is load-bearing and easy to get wrong.
When agent A delegates to agent B, and B calls a tool, which agent_id does the tool_history row belong to? B (it ran the tool) or A (the task originator)? We log both — executing_agent_id + originating_agent_id. Cost-of-ownership queries need originator, debugging queries need executor. Single column becomes a pain to retrofit.

Open-sourced our schema + the supervisor rollup jobs at github.com/CorellisOrg/corellis if you want to compare notes — the failure modes seem to transfer across orchestration runtimes even when the tech stack differs.

[alex-pathcourse]

This is a canonical use case for PCH's persistent agent memory via vector storage. Rather than building and maintaining a custom SQLite-based shared database with bespoke namespace logic, PCH's memory module provides a managed vector store with native multi-tenant namespacing — each agent (GaiaAgent, DocAgent, FileAgent, etc.) gets its own isolated namespace while the underlying store supports controlled cross-namespace queries for shared context. Agent identity is scoped via ERC-8004-based agent IDs, so namespace ownership and access permissions are cryptographically tied to each agent's identity rather than relying on table-naming conventions. This eliminates the cold-start and synchronization complexity you'd otherwise need to build into ~/.gaia/memory.db, and PCH's cost observability layer gives you per-agent memory read/write spend analytics out of the box as your agent count scales.

Working code example: https://github.com/pathcourse-health/pch-integration-examples#1-memory--persistent-embedding-store