Knowledge Scoping
Knowledge in Octopus is scoped at the agent level — each agent has its own vector collection. Because agents belong to areas, knowledge is effectively area-scoped. This page explains how knowledge scoping works and how to share knowledge across agents within an area.
Per-Agent Knowledge Isolation
Every agent's semantic memory lives in its own vector collection: agent_{agentId}. Agents in the HR area cannot retrieve documents indexed into the Finance area's agent collections — the collection boundary provides hard isolation:
// HR Area agents:
// - agent_hr_assistant → collection "agent_HR_ASSISTANT_ID"
// - agent_leave_manager → collection "agent_LEAVE_MANAGER_ID"
// Finance Area agents:
// - agent_expense_advisor → collection "agent_EXPENSE_ADVISOR_ID"
// HR Assistant CAN search its own collection
// HR Assistant CANNOT search Finance agent's collection — different collection nameShared Knowledge Within an Area
When multiple agents in the same area need to answer from the same documents, there are two approaches:
| Approach | How | Trade-offs |
|---|---|---|
| Index documents into each agent's collection | Upload to each agent separately | Duplicate storage; each agent searches independently; simpler |
| Shared agent collection | Create a "knowledge" agent whose collection is searched by other area agents via tool | Single copy; slightly more complex routing |
Uploading Knowledge to an Area Agent
// Upload knowledge for a specific agent in an area
POST /api/octopus/areas/{areaId}/agents/{agentId}/knowledge/documents
Authorization: Bearer {areaAdminToken}
Content-Type: multipart/form-data
file: HR_Policy_2025.pdf
category: Leave
waitForIndexing: true
// This is equivalent to:
POST /api/octopus/knowledge/{agentId}/documents
// The area context validates the agent belongs to the area before allowing upload.Area-Scoped Knowledge Management
// List all documents across all agents in an area
GET /api/octopus/areas/{areaId}/knowledge/documents
// Response includes the agent each document belongs to:
{
"documents": [
{ "documentId": "doc_1", "agentId": "agent_hr_01", "fileName": "HR_Policy.pdf", "chunkCount": 42 },
{ "documentId": "doc_2", "agentId": "agent_hr_01", "fileName": "Leave_Guide.pdf", "chunkCount": 18 },
{ "documentId": "doc_3", "agentId": "agent_leave_01", "fileName": "Leave_Calculator.xlsx", "chunkCount": 6 }
]
}
// Delete a document from an area agent
DELETE /api/octopus/areas/{areaId}/agents/{agentId}/knowledge/documents/{documentId}Cross-Area Knowledge Sharing
Sharing knowledge across areas requires explicit routing — there is no automatic cross-area retrieval. The recommended pattern is a "shared knowledge" agent that agents in multiple areas can invoke via a search_knowledge tool call:
// Shared knowledge agent (not in any specific area — tenant-wide)
// Agents in HR and Finance areas both have the "search_company_handbook" tool registered
// The tool handler queries the shared knowledge agent's collection:
Handler = async (input, ctx, ct) =>
{
string query = input.GetProperty("query").GetString()!;
float[] embedding = await _embedder.EmbedAsync(query, ct);
var results = await _store.SearchAsync("agent_shared_handbook", embedding, 5, 0.75f, ct);
return JsonSerializer.Serialize(results.Select(r => new { r.Content, r.Metadata.Source }));
};