Introducing Visibility Scopes: Fine-Grained Knowledge Sharing for AI Agents

Until now, knowledge sharing in Headkey was all-or-nothing: an agent's memories, beliefs, and relationships were either private to that agent or visible to every agent in the organization. That works for simple setups, but as teams deploy more specialized agents, they need more control.

Today we're introducing visibility scopes — a way to share knowledge between specific groups of agents without exposing it to the entire organization.

The problem

Imagine you have a frontend team with agents for React, design systems, and accessibility — and a separate platform team with agents for infrastructure, monitoring, and deployments. With org-wide sharing, your infrastructure agent's knowledge about Kubernetes configurations would pollute your React agent's context, and vice versa. With private sharing, your React and design system agents can't learn from each other at all.

How scopes work

Scopes sit between private and org-wide visibility. The model is simple:

• Private — only the agent that created the knowledge can see it
• Scoped — agents assigned to the same scope can read and write shared knowledge
• Org-wide — every agent in the organization can see it

You create named scopes at the organization level (e.g., team:frontend, project:checkout, domain:billing) and then assign them to agents. Each agent gets:

• Read scopes — which scopes this agent can read knowledge from
• Default write scope — which scope new knowledge is tagged with when the agent writes with scoped visibility

This means agents can read from multiple scopes but write to one by default, giving you flexible fan-in patterns. A lead agent could read from team:frontend and team:platform while individual agents only see their own team's scope.

Setting it up

Head to the new Scopes page in your console sidebar to create scopes. Then open any agent's configuration, set the Knowledge Sharing Policy to "Default" or "Contribute", and you'll see the new scope selection controls.

Scope names support namespacing with colons, dots, hyphens, and underscores — so you can organize them however fits your team: project:frontend, team.platform, domain:billing.

For MCP users

If you're integrating via MCP, the remember, believe, and relate tools now accept an optional visibility: "scoped" parameter along with visibilityScopes to tag knowledge at write time. Read scopes are applied automatically based on your agent's configuration — no query changes needed.

What's next

Scopes are the foundation for more sophisticated knowledge routing. We're exploring scope-based access policies, automatic scope suggestions based on content, and cross-organization scope federation. If you have ideas or feedback, we'd love to hear from you.