Multi-Agent Memory

This document describes how Hippocortex enables multiple AI agents to share, isolate, and transfer knowledge within an enterprise organization.

Overview

In enterprise deployments, organizations typically run multiple agents with different purposes: research agents, customer support agents, internal knowledge agents, and more. Hippocortex provides the infrastructure for these agents to:

Maintain individual memory -- each agent has its own learned knowledge
Share knowledge -- agents can read from shared namespaces
Transfer knowledge -- knowledge can be explicitly moved between agent scopes
Respect boundaries -- agents cannot access data outside their allowed scopes

Agent Identity

Every agent in Hippocortex has a registered identity stored in the agent_identities table.

Agent Identity Fields

Field	Type	Description
`id`	UUID	Unique agent identifier
`organization_id`	UUID	Parent organization
`team_id`	UUID (nullable)	Team assignment (scopes access)
`name`	string	Human-readable agent name
`agent_class`	string	Classification: `general`, `research`, `support`, `operations`
`description`	string	Agent purpose description
`status`	enum	`active` or `disabled`
`allowed_scopes`	JSON	Namespace access restrictions
`metadata`	JSON	Arbitrary agent metadata
`api_key_id`	UUID	Associated API key for authentication

Agent Classes

Class	Typical Use
`general`	General-purpose agent, no special restrictions
`research`	Research and analysis, often with broad read access
`support`	Customer-facing, restricted to support-relevant data
`operations`	Internal operations, infrastructure knowledge

Agent classes are informational labels. Access control is enforced through scopes and namespace permissions, not classes.

Namespace Scoping

Namespaces are the primary mechanism for organizing and isolating agent memory.

Namespace Architecture

Organization: Acme Corp
|
+-- Namespace: "shared-knowledge"     (defaultAccess: public)
|   +-- All agents can read
|   +-- Only authorized agents can write
|
+-- Namespace: "research-data"        (defaultAccess: team)
|   +-- Only Research Team agents can access
|
+-- Namespace: "customer-support"     (defaultAccess: team)
|   +-- Only Support Team agents can access
|
+-- Namespace: "agent-alpha-private"  (defaultAccess: private)
|   +-- Only Agent Alpha has access
|
+-- Namespace: "classified"           (sensitivity: restricted)
    +-- Explicit grants required, all access is audit-logged

Agent Scope Configuration

Scopes restrict which namespaces an agent can access and what operations it can perform:

{
  "allowedScopes": [
    {
      "namespace": "shared-knowledge",
      "access": "write"
    },
    {
      "namespace": "research-data",
      "access": "read"
    },
    {
      "namespace": "customer-support",
      "access": "none"
    }
  ]
}

Access levels:

Level	Capture	Synthesize	Learn	Delete
`write`	Yes	Yes	Yes	No
`read`	No	Yes	No	No
`none`	No	No	No	No

If allowedScopes is empty or not set, the agent inherits access from its team role and organization role.

Cross-Agent Knowledge Transfer

How Transfer Works

The @hippocortex/transfer package implements cross-agent knowledge transfer:

Source Agent's Namespace           Target Agent's Namespace
       |                                     |
       v                                     |
[Select artifacts to transfer]               |
       |                                     |
       v                                     |
[Validate transfer permissions]              |
       |                                     |
       +-- Source agent has read access?      |
       +-- Target agent has write access?     |
       |                                     |
       v                                     |
[Copy artifacts]                             |
       |                                     |
       v                                     v
[Update provenance: mark as transferred] --> [Store in target namespace]
       |                                     |
       v                                     v
[Create transfer audit entry]          [Reindex for retrieval]

Transfer API

POST /v1/organizations/{orgId}/transfers
Content-Type: application/json
Authorization: Bearer <ADMIN_OR_OPERATOR_TOKEN>

{
  "sourceNamespace": "research-data",
  "targetNamespace": "shared-knowledge",
  "artifactIds": ["art_abc123", "art_def456"],
  "transferMode": "copy",
  "reason": "Research findings ready for general consumption"
}

Transfer modes:

Mode	Behavior
`copy`	Artifacts are duplicated to the target namespace. Source retains originals.
`move`	Artifacts are moved to the target namespace. Removed from source.
`link`	A reference is created in the target namespace. Original stays in source.

Transfer Provenance

Transferred artifacts maintain provenance tracking:

{
  "id": "art_new123",
  "content": "...",
  "provenance": {
    "transferredFrom": {
      "namespace": "research-data",
      "originalId": "art_abc123",
      "transferredAt": "2026-03-15T00:00:00Z",
      "transferredBy": "user_admin",
      "reason": "Research findings ready for general consumption"
    }
  }
}

Memory Isolation Guarantees

Isolation Levels

Level	Guarantee
Tenant	Complete data isolation between billing accounts. No shared tables, queries always scoped by tenant_id.
Organization	Data isolation within a tenant. Organizations cannot see each other's data.
Namespace	Memory partition isolation. Queries are scoped to accessible namespaces.
Agent	Scope-based access restriction. Agents only see namespaces in their allowedScopes.

Query Scoping

Every retrieval query is scoped at multiple levels:

-- Simplified query illustration
SELECT * FROM semantic_memories
WHERE tenant_id = $1           -- tenant isolation
  AND organization_id = $2      -- org isolation
  AND namespace_id = ANY($3)    -- namespace scope (filtered by agent's allowed scopes)
  AND ... (semantic search conditions)

Cross-Namespace Query Prevention

The retrieval engine enforces namespace boundaries:

Auth middleware resolves the user/agent's accessible namespaces
The namespace list is passed to the retrieval engine
Vector search, graph traversal, and episodic search all filter by namespace
Results from inaccessible namespaces are never returned

Shared Knowledge Patterns

Pattern 1: Shared Knowledge Base

All agents contribute to and read from a common namespace:

Agent Alpha ---write--> [shared-knowledge] <--read--- Agent Beta
Agent Gamma ---write--> [shared-knowledge] <--read--- Agent Delta

Use case: Building a shared organizational knowledge base.

Pattern 2: Specialist Agents with Read-Only Access

Specialist agents have private write namespaces but share read access:

Research Agent ---write--> [research-data]
                           [research-data] --read--> Support Agent
                           [research-data] --read--> Ops Agent

Support Agent  ---write--> [support-data]
                           [support-data] is private to Support Agent

Use case: Research agent discovers knowledge that other agents can reference.

Pattern 3: Pipeline Agents

Agents process data in sequence, each writing to the next agent's input namespace:

Capture Agent --write--> [raw-captures]
                         [raw-captures] --read--> Analysis Agent

Analysis Agent --write--> [analyzed-data]
                          [analyzed-data] --read--> Summary Agent

Summary Agent --write--> [summaries]
                         [summaries] --read--> All Agents

Use case: Multi-stage data processing pipeline.

Pattern 4: Hierarchical Knowledge

Parent namespaces contain general knowledge, child namespaces contain specialized knowledge:

[company-wide]      (all agents read)
     |
     +-- [engineering]    (engineering agents read/write)
     |
     +-- [sales]          (sales agents read/write)
     |
     +-- [legal]          (legal agents read/write, restricted sensitivity)

Agent Context in Memories

When an agent captures or creates a memory, the agent identity is recorded:

{
  "id": "mem_xyz",
  "content": "Customer reported issue with API latency...",
  "capturedBy": {
    "type": "agent",
    "agentId": "agt_support_001",
    "agentName": "Support Agent",
    "agentClass": "support"
  },
  "namespace": "customer-support",
  "organization": "org_acme"
}

This enables:

Attribution: Know which agent contributed each piece of knowledge
Filtering: Query memories by contributing agent
Trust scoring: Weight agent contributions differently based on agent class or track record

Best Practices

Start with broad namespaces, narrow as needed: Begin with a "shared" namespace, split into specialized namespaces as data grows
Use team assignment for default scoping: Assign agents to teams to inherit team namespace access
Explicit scopes for sensitive data: Use allowedScopes to restrict access to sensitive namespaces
Transfer over duplication: Use the transfer API instead of having agents write to multiple namespaces
Audit restricted access: Enable audit logging for restricted-sensitivity namespaces
Review agent scopes quarterly: As agent purposes evolve, update their scope configurations