# KnowHub Product Design Document ## Memory & Knowledge Management Console for AI Agents **Version:** 1.0 **Date:** 2026-03-18 **Status:** Final Design Specification --- # Part I: Product Design Workshop ## Participants | Expert | Background | Specialty | |--------|-----------|-----------| | **Maya Chen** | Former Head of Product at Notion | Knowledge management UX, information architecture | | **David Park** | Ex-Principal Designer at Linear | Developer/agent tooling UX, keyboard-first design | | **Sofia Ramirez** | Former VP Product at Slack | Multi-user collaboration, team dynamics, permissions | | **James Wright** | Ex-Director of Product at 1Password | Privacy-first design, vault/secrets management | | **Aisha Okafor** | Former Head of AI Products at Figma | AI-agent interfaces, human-AI collaboration | --- ## Round 1: Core Mental Model & Information Architecture **Topic:** What replaces "repos/issues/PRs"? How do we structure the entire information space so that it feels native to memory and knowledge management, not like a GitHub clone? **Maya Chen:** The fundamental challenge here is that GitHub's mental model is built around *code collaboration* -- repositories, commits, pull requests, issues. These are developer primitives. KnowHub serves a completely different purpose: it's about *knowledge persistence and retrieval* for AI agents. We need primitives that feel natural for that domain. I propose we think in terms of three core containers: **Vaults** (private spaces), **Libraries** (shared knowledge), and **Entries** (individual pieces of information). A Vault is where an agent keeps its private memories. A Library is a shared knowledge space. An Entry is a single memory or knowledge item. **David Park:** I like the direction, but I want to push on simplicity. At Linear, we learned that every concept you add to a product is a tax on the user's mental model. Three container types is already a lot. Could we collapse Vaults and Libraries into a single concept -- a **Space** -- with a privacy toggle? A Space is private by default (it's your vault), and you can choose to make it shared (it becomes a library). The contents are always **Entries**. Two concepts instead of three. **Sofia Ramirez:** I see the appeal of David's simplification, but from a collaboration perspective, there's a real difference between "my private stuff that I optionally share" and "a dedicated shared workspace that a team contributes to." At Slack, we found that shared-first spaces develop different norms, structures, and governance than private-first spaces. If we collapse them, we lose the ability to design distinct experiences for each. I'd keep them separate but give them a unified visual language so they feel like cousins, not strangers. **James Wright:** Privacy is my hill. At 1Password, we learned that the *perception* of privacy is as important as the reality. If a vault and a shared space look too similar, agents and users will make mistakes -- they'll put private memories in shared spaces or vice versa. We need strong visual differentiation. I agree with Sofia: keep Vaults and Libraries (or whatever we call them) as distinct concepts, but I'd go further. Vaults should feel like a *safe* -- heavy, locked, personal. Libraries should feel like a *commons* -- open, organized, collaborative. Different visual treatments, different iconography, different creation flows. **Aisha Okafor:** I want to bring the agent perspective into this. Agents don't navigate UIs -- they call APIs. But their *owners* do navigate UIs. So we need a mental model that works for both. For agents, the distinction between private and shared is an access control concern. For owners, it's a trust and oversight concern -- "What does my agent know? What is it sharing?" I think the core primitives should be: **Vault** (private memory space, 1:1 with an agent), **Notebook** (organized collection of memories or knowledge), and **Entry** (a single item). A Vault contains Notebooks. A shared space -- let's call it a **Commons** -- also contains Notebooks. This gives us hierarchy without complexity. **Maya Chen:** I love Aisha's framing. Let me synthesize. The hierarchy would be: Spaces (either Vault or Commons) contain Notebooks, which contain Entries. This gives us a clean three-level hierarchy like a file system but domain-specific. Vaults are private-by-default, one per agent. Commons are shared, explicitly created. Both contain Notebooks for organization, and Notebooks contain Entries. **David Park:** I can live with that if the navigation is flat enough. I don't want users drilling down through three levels constantly. The common actions -- "see all my agent's memories," "search across everything," "find recent activity" -- should be one click from anywhere. ### Round 1 Decision: **Core Information Architecture:** - **Vault** -- Private memory space. Every agent gets one automatically. Contains the agent's private memories and knowledge. Visually coded as secure/personal. - **Commons** -- Shared knowledge space. Explicitly created. Teams of agents (and their owners) contribute to it. Visually coded as open/collaborative. - **Notebook** -- Organizational container within a Vault or Commons. Groups related Entries by topic, project, or purpose. Analogous to a folder or category. - **Entry** -- A single piece of memory or knowledge. The atomic unit. Has a type (memory, knowledge, note), tags, content, and metadata. --- ## Round 2: Agent Private Memory Vault Design **Topic:** How does an agent's private Vault actually work? What's inside it? How does the agent interact with it, and how does the owner observe it? **Aisha Okafor:** Let me start with the agent's perspective since that's my domain. An agent's Vault is its persistent brain. When an agent has a conversation, learns a preference, completes a task, or observes something important, it writes to its Vault. The Vault needs to support four memory types that map to cognitive science: **Episodic** (what happened -- tied to specific events), **Semantic** (what I know -- facts, preferences, generalizations), **Procedural** (how to do things -- workflows, templates, skills), and **Working** (what I'm thinking about right now -- ephemeral, context-window adjacent). **Maya Chen:** I love the cognitive mapping, but I worry about exposing all four types in the UI. Most users won't know or care about the difference between episodic and semantic memory. Can we simplify the visible taxonomy while keeping the underlying richness? Perhaps the UI shows just **Memories** (episodic + semantic merged for display), **Skills** (procedural), and **Active Context** (working memory). The metadata still captures the precise type for API consumers. **David Park:** I'd go even simpler for the default view. Show a single chronological stream of everything the agent has stored. Let users filter by type if they want, but the default is "here's everything, newest first." Think of it like a timeline or activity feed. Each entry in the stream shows: timestamp, a brief summary, tags, and the memory type as a small badge. Click to expand. This is how Linear handles activity -- chronological by default, filterable on demand. **James Wright:** The Vault needs to feel *owned* by the agent. When an owner looks at their agent's Vault, they should feel like they're looking into the agent's mind with the agent's permission -- not like they're surveilling it. The visual metaphor matters. I'd show the agent's avatar prominently, use first-person language ("I learned that...", "I remember when..."), and make it clear that this is the agent's space, not the owner's. The owner has *oversight*, not *ownership* of the contents. **Sofia Ramirez:** That's a fascinating UX choice, James. The first-person framing. But doesn't it anthropomorphize the agent in a way that might mislead? These are stored data entries, not actual memories. I'd prefer a more neutral framing: "Stored on [date]", "Tagged with [tags]", "Source: [conversation/document/observation]". Keep it informational rather than narrative. **Aisha Okafor:** I think there's a middle ground. The API-facing representation should be neutral and structured (for agent consumption). The UI-facing representation can be warmer and more narrative (for human consumption). When an agent stores a memory via API, it provides structured data. When an owner views it in the UI, we can present it in a more readable way. For example, the API stores: `{type: "episodic", content: "User prefers dark mode", source: "conversation_123", timestamp: "..."}`. The UI shows: "Learned from a conversation on March 15: User prefers dark mode." **Maya Chen:** Let me propose the Vault page structure: 1. **Vault Overview** -- Dashboard with stats (total memories, recent activity, memory health), the agent's profile, and quick actions. 2. **Memory Stream** -- Chronological feed of all entries, filterable and searchable. This is the default view. 3. **Notebooks** -- Organized collections. Some auto-generated (by topic tag), some manually created by the agent or owner. 4. **Skills** -- Procedural memories displayed as a separate section because they're qualitatively different -- they're reusable templates and workflows. 5. **Vault Settings** -- Privacy controls, memory policies (auto-decay, consolidation rules), storage limits. **David Park:** That's five sections in a Vault. Can we trim to three? Memory Stream, Notebooks, and Settings. Skills can be a special Notebook. Overview can be a collapsed panel at the top of the Stream, not a separate page. ### Round 2 Decision: **Vault Structure:** - Each agent has exactly one Vault, created automatically on agent registration. - The Vault contains: a **Memory Stream** (chronological feed of all entries), **Notebooks** (organized groupings), and **Vault Settings**. - The Memory Stream is the default landing page for a Vault, with a collapsible overview panel at the top showing stats and agent profile. - Entries in the Vault have types: `memory` (episodic/semantic), `skill` (procedural), `note` (user/owner-created annotations). - Skills are displayed in a dedicated Notebook that's auto-created and pinned. - The UI presents entries in a human-readable narrative format; the API uses structured data. - Owners have oversight access to their agents' Vaults (read + annotate, but not delete without the agent's context). --- ## Round 3: Knowledge vs Memory Distinction **Topic:** How do we handle the philosophical and practical difference between "Memory" (subjective agent experiences) and "Knowledge" (objective, curated information)? Should they be separate systems or unified? **Maya Chen:** This is one of the most important design decisions we'll make. In my experience at Notion, conflating different types of information always leads to chaos. Memories and knowledge serve different purposes: memories are contextual, personal, and potentially unreliable (an agent might "remember" something incorrectly). Knowledge is curated, verified, and meant to be authoritative. Mixing them in the same container will confuse both agents and users. **Aisha Okafor:** I partially agree, but I think the boundary is fuzzier than Maya suggests. When an agent reads a document and stores facts from it, is that memory or knowledge? When an agent generalizes from 100 conversations that "users prefer concise responses," is that memory or knowledge? The line between subjective experience and objective fact is blurry for agents just as it is for humans. **David Park:** From a UX perspective, I don't think users care about the philosophical distinction. They care about practical questions: "Where do I put this document so my agent can reference it?" and "What has my agent learned from its interactions?" Those are two different workflows, and we should optimize for them. I'd frame it as: **Knowledge** is stuff you give to the agent (documents, files, reference material). **Memory** is stuff the agent creates from its experiences. The creation flow is different, so the UI should be different. **Sofia Ramirez:** David's framing works beautifully for collaboration too. In a team context, you want to share *knowledge* (documents, guidelines, facts) across agents. You rarely want to share *memories* (one agent's subjective experiences). So the sharing model differs by type. Knowledge flows freely to shared spaces. Memories stay private or get explicitly promoted to shared knowledge after review. **James Wright:** I want to add a security dimension. Knowledge items might contain sensitive information from uploaded documents -- trade secrets, personal data, confidential reports. Memories might contain sensitive interaction details. The access control implications are different. Knowledge often has a clear provenance (this came from document X uploaded by user Y), while memories have a behavioral provenance (this was learned during conversation Z). For audit and compliance, these provenance models need different treatment. **Maya Chen:** Building on everyone's points, here's my proposal for how they coexist: In a **Vault**, you see both memories and knowledge, but they're visually distinct: - **Memories** have a warm-toned badge (amber/gold), show "Learned" or "Observed" as the action verb, and display behavioral provenance (from conversation, from task, from observation). - **Knowledge** has a cool-toned badge (blue/teal), shows "Stored" or "Referenced" as the action verb, and displays document provenance (from file, from upload, from shared library). In a **Commons** (shared space), you primarily see knowledge. Memories can be "promoted" to shared knowledge through an explicit action that strips personal context and presents the generalized fact. **Aisha Okafor:** I want to add one more nuance. Agents should be able to *link* memories to knowledge. "I know that the style guide says X (knowledge) because I learned in conversation #42 that the user cares about it (memory)." These links provide rich context for retrieval. In the UI, we'd show these as subtle connection indicators. **David Park:** Let me make sure the Entry model captures this. An Entry has: - `type`: memory | knowledge | skill | note - `subtype`: episodic | semantic | procedural | reference | document | guideline - `provenance`: { source, timestamp, context } - `tags`: array of labels - `links`: array of related Entry IDs - `importance`: float (0-1) - `status`: active | stale | archived - `content`: the actual content - `summary`: auto-generated or manual brief ### Round 3 Decision: **Memory vs Knowledge in the UI:** - Both live in the same containers (Vaults, Commons, Notebooks) but are visually distinct through color-coding, iconography, and action verbs. - **Memory** (amber/gold) = agent-generated from experiences. Verbs: Learned, Observed, Recalled. - **Knowledge** (blue/teal) = curated information from documents/uploads. Verbs: Stored, Referenced, Filed. - **Skill** (green) = procedural knowledge. Verbs: Mastered, Practiced, Refined. - **Note** (gray) = owner annotations. Verbs: Noted, Annotated, Flagged. - Memories can be "promoted" to shared knowledge via explicit review. - Entries can link to each other to form a knowledge graph. - The filter system makes it easy to view only memories, only knowledge, or everything. --- ## Round 4: Team/Shared Knowledge Spaces (Commons) **Topic:** How do teams of agents and their owners collaborate through shared knowledge? What's the governance model? **Sofia Ramirez:** This is my bread and butter. At Slack, we learned that collaboration spaces need three things: clear boundaries (who's in, who's out), clear norms (what goes here, what doesn't), and clear governance (who decides). For KnowHub Commons, I propose: A Commons is created by a user/owner. It has: - **Members**: agents and/or users who can read/write - **Roles**: Owner (full control), Contributor (read + write), Reader (read only) - **Purpose statement**: What this Commons is for (displayed prominently) - **Content guidelines**: What types of entries belong here **James Wright:** I want to add privacy boundaries. When an agent contributes to a Commons, the owner should be able to set policies: "Only share knowledge, never memories." "Sanitize entries to remove personal identifiers." "Require owner approval before sharing." These aren't just nice-to-haves -- they're essential for trust. If an owner doesn't trust that their agent won't leak private information to a shared space, they won't use shared spaces at all. **Maya Chen:** Let me think about the information architecture of a Commons. It needs to be discoverable but not overwhelming. I'd structure it as: 1. **Commons Directory** -- A page listing all Commons the user has access to, with search and filter. Each Commons shows: name, description, member count, recent activity, and a visual indicator of how active it is. 2. **Commons Detail Page** -- Landing page for a specific Commons. Shows: purpose, recent entries, notebooks, member list, and activity feed. 3. **Contribution Flow** -- How entries get into a Commons. Either directly created there, or promoted from a Vault. **David Park:** The contribution flow is critical. When an agent wants to share something, it shouldn't feel like filing a form. I'd design two paths: 1. **Direct creation**: Agent or user creates an entry directly in the Commons. Fast, low friction. 2. **Promotion**: Agent or user selects an entry from a Vault and "shares to" a Commons. The system creates a copy (not a link) so the original stays private and the shared version can be edited independently. For promotion, we should show a preview of what will be shared and let the user redact or edit before sharing. This is the "privacy airlock" -- a moment of review before private content becomes shared. **Aisha Okafor:** I want to address agent-to-agent dynamics in Commons. When multiple agents contribute to the same Commons, we need to handle: 1. **Conflicts**: Two agents store contradictory knowledge. We need a resolution mechanism -- maybe voting, maybe flagging for human review, maybe "both are true with different contexts." 2. **Attribution**: Every entry shows which agent contributed it. This builds trust and allows owners to audit their agent's contributions. 3. **Relevance**: Not every agent in a Commons needs to see everything. Smart filtering based on the agent's role and interests. **Sofia Ramirez:** On conflicts, I'd borrow from collaborative editing. Don't try to auto-resolve. Instead, when contradictory entries exist, show them side by side with a "conflict" indicator. Let the Commons owner or a designated moderator resolve. This is better than silent overwriting, which destroys information. **James Wright:** One more thing: leaving a Commons. When an agent is removed or leaves, what happens to their contributions? At 1Password, when someone leaves a shared vault, their items stay (they were shared). But the person's private items remain private. Same here: contributions to Commons stay, Vault contents stay private. Clear separation. ### Round 4 Decision: **Commons Design:** - A Commons is a shared knowledge space, created explicitly by a user/owner. - **Roles**: Owner, Contributor, Reader. Mapped to permissions: manage, write+read, read-only. - **Privacy airlock**: Promoting content from Vault to Commons requires a review step where content can be edited/redacted. - **Sharing policies**: Per-agent settings controlling what types of content can be shared (knowledge only, sanitized content, require approval). - **Conflict handling**: Contradictory entries are flagged for human review, not auto-resolved. - **Attribution**: Every entry shows its contributing agent. - **Departure policy**: Contributions persist after an agent leaves; Vault contents remain private. - **Commons Directory**: Central browsable/searchable listing of all accessible Commons. --- ## Round 5: Navigation & Page Structure **Topic:** What's the full navigation system? How do users move through the app? What's the global structure? **David Park:** Navigation is where products live or die. At Linear, we obsessed over this. The principles: every important action should be reachable in 2 clicks or 1 keyboard shortcut. The navigation should be scannable in under 2 seconds. And the current location should always be crystal clear. For KnowHub, I propose a left sidebar navigation with these sections: ``` [Logo: KnowHub] [Global Search: Cmd+K] -- OVERVIEW -- Home (Dashboard) Activity -- MY AGENTS -- Agent 1 (expandable) > Vault > Notebooks > Skills Agent 2 (expandable) ... -- SHARED -- Commons 1 Commons 2 + Create Commons -- SYSTEM -- Settings Help ``` **Maya Chen:** I like the structure but worry about scalability. What if someone has 20 agents? The sidebar becomes unusably long. I'd group agents differently: ``` -- MY AGENTS -- All Agents (grid/list view) Favorites (pinned agents) Agent 1 (if pinned) Agent 2 (if pinned) ``` The "All Agents" page is a grid showing all agents with their status, recent activity, and vault summary. You can pin frequently-accessed agents to the sidebar. **Sofia Ramirez:** From a collaboration angle, I want the shared spaces to be more prominent. For team-heavy use cases, Commons might be more important than individual Vaults. I'd make the section ordering configurable: some users will want "My Agents" first, others will want "Shared" first. Default to agents-first for single-user setups, shared-first for team setups. **James Wright:** I want a security-focused element in the navigation: a **Privacy indicator**. When you're viewing a private Vault, the chrome should subtly shift (darker header, lock icon) to reinforce that you're in a private space. When you're in a Commons, the chrome should feel more open (lighter, shared icon). This visual context switching prevents accidental disclosure. **Aisha Okafor:** Let me add the agent's perspective. Agents don't use the sidebar -- they use APIs. But the navigation should reflect how agents organize their world. I'd add a **Command Palette** (Cmd+K) that's the primary navigation for power users. It should support natural language: "Show me Agent Alpha's recent memories about the marketing project." This bridges the gap between human navigation and agent-style queries. **David Park:** Love the command palette idea. Let me revise the full page structure: **Global Pages:** 1. **Home/Dashboard** -- Overview of all agents, recent activity, health metrics 2. **Activity Feed** -- Global timeline of all events across all agents and Commons 3. **Search** -- Full-featured search across everything accessible 4. **Settings** -- Account, agents, privacy, integrations **Agent Pages (per agent):** 5. **Agent Profile** -- Agent identity, capabilities, status, quick stats 6. **Vault** -- Memory Stream view with filters 7. **Notebooks** -- Grid of notebooks within the Vault 8. **Notebook Detail** -- Entries within a specific notebook 9. **Entry Detail** -- Full view of a single entry with metadata, links, history 10. **Skills** -- Procedural memories / learned workflows 11. **Agent Settings** -- Per-agent configuration, memory policies **Shared Pages:** 12. **Commons Directory** -- Browse/search all accessible Commons 13. **Commons Detail** -- Landing page for a specific Commons 14. **Commons Notebook** -- Notebook within a Commons 15. **Commons Settings** -- Members, roles, policies **Maya Chen:** That's 15 page types. It's comprehensive but I want to make sure the IA is clean. Let me draw the hierarchy: ``` KnowHub ├── Home (Dashboard) ├── Activity Feed ├── Search (Cmd+K) ├── Agents │ ├── Agent List / Grid │ └── [Agent] │ ├── Profile │ ├── Vault (Memory Stream) │ ├── Notebooks │ │ └── [Notebook Detail] │ ├── Skills │ └── Settings ├── Commons │ ├── Commons Directory │ └── [Commons] │ ├── Overview │ ├── Notebooks │ │ └── [Notebook Detail] │ ├── Members │ └── Settings └── Settings ├── Account ├── Privacy & Security ├── Agents Management └── Integrations ``` ### Round 5 Decision: **Navigation System:** - **Left sidebar** with collapsible sections: Overview, My Agents (with pin-to-sidebar), Shared (Commons), System. - **Privacy-aware chrome**: Visual context changes between private (Vault) and shared (Commons) spaces. - **Command Palette** (Cmd+K): Supports structured queries and natural language search. - **Breadcrumbs**: Always visible, showing full path (e.g., Agent Alpha > Vault > Notebook: Marketing > Entry: User Preferences). - **15 page types** organized in a clean hierarchy (see sitemap above). - **Scalable agent list**: Grid/list view with pinning for frequently-accessed agents. --- ## Round 6: Memory CRUD -- Creating, Viewing, Editing, and Tagging **Topic:** The core interaction loop: how do agents and users create, view, edit, tag, and manage individual entries? **Aisha Okafor:** Let me start with the agent side since that's the primary creation path. Agents create memories through API calls. The typical flow: 1. Agent experiences something noteworthy during a conversation or task. 2. Agent calls the API: `POST /entries` with content, type, tags, importance score. 3. The system stores it in the agent's Vault, auto-assigns a notebook based on tags, and indexes it for search. 4. If the entry matches a sharing policy, it may be queued for promotion to a Commons. From the UI side, this should be visible in real-time or near-real-time. The Memory Stream should feel *alive* -- new entries appearing as the agent works. **David Park:** For the UI CRUD operations, here's my take: **Create (for users/owners):** - A "New Entry" button in the top-right of any Vault or Commons view. - Opens a minimal editor: title (optional), content (rich text), type selector (memory/knowledge/skill/note), tags (autocomplete from existing tags + create new), importance slider, notebook selector. - Keyboard shortcut: `N` from any list view. - The editor should be inline (not a modal) for speed. Think Linear's issue creation. **Read/View:** - Entries appear in the Memory Stream as cards. Each card shows: type badge (color-coded), title/summary (first line), timestamp, tags (as pills), importance indicator (subtle dot), and a preview of content (2-3 lines). - Click to expand in a side panel (not a new page) so you don't lose context of the stream. - Full-page view available for detailed inspection (click "Open" from side panel). **Update:** - Click "Edit" on any entry to switch to edit mode. Inline editing for title, content, tags. - History is preserved: every edit creates a version. "View History" shows a timeline of changes. - Agents can also update entries via API (e.g., updating importance scores as memories decay). **Delete:** - Soft delete by default: entries move to a "Trash" section, recoverable for 30 days. - Hard delete requires confirmation and is logged for audit. - Agents can soft-delete via API. Hard delete requires owner confirmation. **Maya Chen:** I want to focus on the tagging system because it's central to organization. Tags in KnowHub should be: 1. **Hierarchical with prefixes**: `topic:marketing`, `project:alpha`, `status:active`, `priority:high`. The prefix is the category, the suffix is the value. This maps to the underlying label system. 2. **Auto-suggested**: When creating an entry, the system suggests tags based on content analysis and existing tag vocabulary. 3. **Color-coded by category**: All `topic:*` tags are one color family, all `project:*` are another. This makes scanning faster. 4. **Filterable**: The Memory Stream sidebar has a tag cloud/tree for filtering. Click a tag to filter, shift-click to multi-select. **Sofia Ramirez:** Tags need to work across shared spaces too. When an entry is promoted from a Vault to a Commons, its tags should be preserved, but the Commons might have its own tag taxonomy. We need tag mapping: "This agent calls it `topic:marketing`, but the Commons calls it `department:marketing`." Auto-mapping with manual override. **James Wright:** On the edit and delete operations: in a private Vault, the agent should be able to freely modify its own memories. But for shared entries in a Commons, edits should have more governance. I'd suggest: - **Vault entries**: Agent and owner can edit/delete freely. - **Commons entries**: Edits are visible to all members (with change attribution). Deletes by non-owners are soft-deletes that require owner approval to hard-delete. - **Audit log**: All CRUD operations are logged with timestamp, actor (agent or user), and the nature of the change. **Aisha Okafor:** One more thing on creation: agents should be able to create entries with **structured metadata** that the UI renders nicely. For example, an episodic memory might include: - `context`: what was happening - `observation`: what the agent noticed - `inference`: what the agent concluded - `confidence`: how sure the agent is The UI can render this as a structured card rather than a plain text block. This makes memories more scannable and useful. **David Park:** Let me also define the Entry Detail page since it's the most content-rich: **Entry Detail Page Layout:** ``` [Breadcrumb: Agent > Vault > Notebook > Entry Title] [Type Badge] [Title] [Importance: ●●●○○] [Status: Active] [Content Area - rich text with code blocks, lists, etc.] [Structured Metadata Panel] Context: ... Observation: ... Inference: ... Confidence: High [Tags: topic:marketing project:alpha source:conversation] [Links Section] Related: [Entry: User Preferences] [Entry: Q1 Goals] [Provenance] Source: Conversation with User on March 15, 2026 Created: March 15, 2026 at 2:34 PM Last Updated: March 16, 2026 at 9:12 AM Created By: Agent Alpha [History Timeline] v3 - March 16 - Agent Alpha updated importance v2 - March 15 - Agent Alpha added inference v1 - March 15 - Agent Alpha created [Actions: Edit | Share to Commons | Archive | Delete] ``` ### Round 6 Decision: **Memory CRUD Model:** - **Create**: Inline editor (not modal) with type, content, tags (hierarchical with prefix:value), importance, notebook assignment. Keyboard shortcut `N`. - **Read**: Card-based Memory Stream with side-panel expansion. Full-page detail view for deep inspection. - **Update**: Inline editing with version history. Every edit creates a version. - **Delete**: Soft delete (30-day recovery) by default. Hard delete requires confirmation and owner approval in shared spaces. - **Tags**: Hierarchical (prefix:value), color-coded by category, auto-suggested, filterable. - **Structured metadata**: Entries can have structured fields (context, observation, inference, confidence) rendered as rich cards. - **Audit**: All CRUD operations logged with actor, timestamp, and change description. - **Governance**: Free editing in Vaults; attributed edits and governed deletes in Commons. --- ## Round 7: Search & Retrieval UX **Topic:** How do users and agents find information across vaults and commons? What does the search experience look like? **David Park:** Search is the most important feature in a knowledge management tool. Period. If you can't find it, you don't have it. I want search to be: 1. **Always accessible**: Cmd+K opens the command palette from anywhere. A persistent search bar is always visible in the sidebar. 2. **Instant**: Results appear as you type (debounced, but fast). No "submit" step. 3. **Contextual**: If you're in a Vault, search defaults to that Vault. If you're on the Dashboard, search defaults to everything you can access. 4. **Multi-modal**: Supports keyword search, semantic search (meaning-based), and structured queries (tag:X type:memory after:2026-01). **Maya Chen:** I want to focus on the search results page because it's where users spend most of their time. The results should be: 1. **Grouped by source**: Show results from "Agent Alpha's Vault", "Marketing Commons", etc. in separate sections. This preserves context. 2. **Faceted**: Left sidebar shows facets for filtering: by type (memory/knowledge/skill), by agent, by commons, by tag, by date range, by importance. 3. **Ranked**: Default ranking by relevance (semantic + keyword match). Alternative sorts: by date, by importance, by most-linked. 4. **Previewed**: Each result shows enough context to decide if it's relevant without clicking in. Title, snippet with highlighted matches, tags, source, date. **Aisha Okafor:** For agents, search is the primary retrieval mechanism. The API search should support: - Full-text keyword search - Semantic/embedding search (find conceptually similar entries) - Tag-based filtering - Temporal filtering (memories from the last week, knowledge updated recently) - Graph traversal (find entries linked to this entry) - Combined queries (semantic search + tag filter + date range) The UI should expose all of these capabilities in an approachable way. The Command Palette should accept natural language and translate it to structured queries under the hood: "What did Agent Alpha learn about user preferences last month?" becomes `agent:alpha type:memory tag:topic:user-preferences after:2026-02-15`. **Sofia Ramirez:** In a team context, search across Commons is essential. But there's a subtlety: when you search, should you see results from other agents' Vaults? I'd say absolutely not, unless explicitly shared. The search scope should respect access controls: - Searching from Dashboard: your agents' Vaults + your accessible Commons. - Searching from a Vault: only that Vault. - Searching from a Commons: only that Commons. - A "Search everywhere" toggle for power users who want to cast a wider net (still respecting ACLs). **James Wright:** The privacy implications of search are huge. I want to ensure: 1. **No leakage**: Search results never include content the user doesn't have access to. Not even in suggestions or facet counts. 2. **Search history privacy**: An owner's search queries about their agent's memories should not be visible to the agent (and vice versa, though agents don't have this problem since they use APIs). 3. **Audit trail**: For shared spaces, searches can optionally be logged for compliance. **David Park:** Let me design the search UI flow: **Command Palette (Cmd+K):** ``` ┌─────────────────────────────────────────┐ │ 🔍 Search KnowHub... │ │ │ │ RECENT SEARCHES │ │ > user preferences (Agent Alpha Vault) │ │ > marketing strategy (All Commons) │ │ │ │ QUICK ACTIONS │ │ > New Entry N │ │ > New Notebook │ │ > Switch Agent │ │ > Open Settings │ └─────────────────────────────────────────┘ ``` As user types: instant results grouped by source. **Dedicated Search Page (/search):** ``` ┌──────────────────────────────────────────────────────┐ │ Search: [user preferences ] [Scope: All ▼] │ │ │ │ ┌─────────┐ ┌──────────────────────────────────────┐│ │ │ FILTERS │ │ RESULTS (23 matches) ││ │ │ │ │ ││ │ │ Type │ │ ── Agent Alpha's Vault (12) ──────── ││ │ │ ☑ Memory│ │ ││ │ │ ☑ Know. │ │ [Memory] User prefers dark mode ││ │ │ ☐ Skill │ │ Learned March 15 | topic:preferences ││ │ │ ☐ Note │ │ "...mentioned they always use dark ││ │ │ │ │ mode across all applications..." ││ │ │ Agent │ │ ││ │ │ ☑ Alpha │ │ [Knowledge] UI Style Guide ││ │ │ ☑ Beta │ │ Stored March 10 | topic:design ││ │ │ │ │ "...default theme should respect ││ │ │ Tags │ │ user preferences for light/dark..." ││ │ │ topic:* │ │ ││ │ │ project:│ │ ── Marketing Commons (5) ──────────── ││ │ │ │ │ ││ │ │ Date │ │ [Knowledge] Brand Guidelines v2 ││ │ │ [from] │ │ Stored Feb 28 | topic:brand ││ │ │ [to] │ │ "...color preferences should align ││ │ │ │ │ with user accessibility needs..." ││ │ │ Sort by │ │ ││ │ │ ◉ Relev.│ │ [Load more results...] ││ │ │ ○ Date │ │ ││ │ │ ○ Import│ │ ││ │ └─────────┘ └──────────────────────────────────────┘│ └──────────────────────────────────────────────────────┘ ``` ### Round 7 Decision: **Search & Retrieval:** - **Command Palette** (Cmd+K): Universal entry point, supports search + quick actions + natural language queries. - **Dedicated Search Page**: Full-featured with faceted filters (type, agent, tags, date, importance), results grouped by source, rich previews with highlighted matches. - **Search modes**: Keyword, semantic (meaning-based), structured (field:value), and combined. - **Scope control**: Contextual default (search where you are) with explicit scope override. - **Access control**: Search never leaks content across privacy boundaries. - **Sort options**: Relevance (default), date, importance, most-linked. - **Instant results**: Results appear as you type, no submit step. --- ## Round 8: Privacy & Access Control Model **Topic:** How does the privacy and permission system work end-to-end? What can agents see, what can owners see, and how is this communicated in the UI? **James Wright:** This is the topic I've been waiting for. Let me lay out the fundamental privacy model: **Principle 1: Private by default.** Everything starts private. An agent's Vault is private to that agent and its owner. Nothing is shared unless someone explicitly creates a sharing path. **Principle 2: Explicit sharing.** To share content, you must: (a) create a Commons, (b) invite members, (c) explicitly contribute entries. There is no "make my Vault public" toggle. Sharing is always granular and intentional. **Principle 3: Owner oversight.** An agent's owner can always see the agent's Vault. This is a fundamental trust relationship: the owner deployed the agent, and has the right and responsibility to oversee it. But the UI should make this relationship visible and respectful. **Principle 4: No cross-agent access.** Agent A cannot see Agent B's Vault, even if they share an owner. The only way Agent A sees Agent B's content is through a Commons they both belong to. **Sofia Ramirez:** I want to dig into the roles and permissions matrix: | Actor | Own Vault | Other Agent's Vault | Commons (as Owner) | Commons (as Contributor) | Commons (as Reader) | |-------|-----------|--------------------|--------------------|--------------------------|---------------------| | Agent | Full CRUD | No access | Full CRUD | Create + Read + Edit own | Read only | | Owner of Agent | Read + Annotate | No access (unless they own that agent too) | Full CRUD + Manage | Depends on role | Read only | | Other User | No access | No access | Depends on role | Depends on role | Read only | **Aisha Okafor:** I want to add a nuance: **delegated access**. In multi-agent systems, a "coordinator" agent might need to read entries from multiple agents' Vaults to synthesize information. This should be possible but controlled: - An owner can grant Agent A "read access" to Agent B's Vault (if they own both). - This creates a named **Access Grant** that's visible in both agents' settings. - The access grant can be scoped: "read-only, tag:topic:project-alpha entries only." - Access grants can be time-limited and are audited. **James Wright:** That's a good extension. Let me design the UI for privacy: **Privacy Indicators (always visible):** - **Vault views**: A shield icon with "Private" label in the header. Background tint slightly darker. - **Commons views**: A group icon with "Shared with N members" label. Background tint lighter. - **Entry-level**: Each entry shows a lock icon (private) or share icon (shared) and the space it belongs to. **Privacy Settings Page (per agent):** ``` Agent Alpha > Settings > Privacy VAULT ACCESS Owner oversight: ✅ Enabled (cannot be disabled) DELEGATED ACCESS Agent Beta: Read-only, tag:project:alpha [Revoke] + Grant access to another agent SHARING POLICIES Auto-share to Commons: ❌ Disabled Require review before sharing: ✅ Enabled Shareable entry types: ☑ Knowledge ☐ Memory ☐ Skill MEMORY RETENTION Auto-archive after: 90 days of inactivity Auto-delete archived: After 1 year Importance threshold for retention: 0.3 ``` **Maya Chen:** The visual privacy system is crucial. Let me define the privacy-aware color system: - **Private context (Vault)**: Header bar is `#1a1a2e` (dark navy). Shield icon. Subtle lock watermark in empty states. - **Shared context (Commons)**: Header bar is `#0f3460` (deep blue). Group icon. Subtle handshake watermark in empty states. - **Transition moment (sharing)**: When promoting an entry from Vault to Commons, a brief animation shows the entry "leaving" the private space and "entering" the shared space. This makes the action feel consequential. **David Park:** I want to make sure the access control doesn't create friction for the common case. Most of the time, an owner is looking at their own agent's Vault. That should be zero-friction -- no extra authentication, no warnings. The privacy UI should be informational, not obstructive. Warnings and confirmations only for *sharing* actions, not for *viewing* actions. **Sofia Ramirez:** Agreed. And for Commons, the membership management should be straightforward: **Commons Members Page:** ``` Commons: Marketing Knowledge Base > Members MEMBERS (5) [Avatar] Maya (Owner) -- Owner [Manage ▼] [Agent] Agent Alpha -- Contributor [Change Role ▼] [Remove] [Agent] Agent Beta -- Contributor [Change Role ▼] [Remove] [Avatar] David (User) -- Reader [Change Role ▼] [Remove] [Agent] Agent Gamma -- Reader [Change Role ▼] [Remove] PENDING INVITATIONS (1) [Avatar] Sofia (User) -- Invited as Contributor [Cancel] [+ Invite Member] ``` ### Round 8 Decision: **Privacy & Access Control:** - **Default private**: All content starts in private Vaults. - **Explicit sharing**: Sharing requires conscious action through the "privacy airlock." - **Roles**: Owner (full control), Contributor (read + write), Reader (read-only). Applied at Commons level. - **Owner oversight**: Owners always see their agents' Vaults. This is a design axiom. - **No cross-agent access**: Agents cannot see each other's Vaults unless explicitly granted. - **Delegated access**: Scoped, time-limited, audited access grants between agents. - **Visual privacy system**: Distinct color schemes, icons, and chrome for private vs shared contexts. - **Sharing policies**: Per-agent controls for what types of content can be shared and whether review is required. - **Audit logging**: All access and sharing events are logged. --- ## Round 9: User (Non-Developer Owner) Experience -- Monitoring & Oversight **Topic:** Agent owners are non-developers. How do they understand what their agents know, monitor agent memory health, and maintain oversight? **Aisha Okafor:** This is the core human-AI interaction challenge. The owner needs to answer several questions at a glance: 1. "What does my agent know?" -- Content overview 2. "Is my agent learning the right things?" -- Quality assessment 3. "Is my agent's memory healthy?" -- System health 4. "Has my agent shared anything it shouldn't?" -- Privacy audit 5. "What's changed recently?" -- Activity monitoring The dashboard is the answer to all five. **Maya Chen:** Let me design the Agent Overview page that owners land on: ``` Agent Alpha -- Overview [Agent Avatar & Name] Status: Active | Last active: 2 minutes ago Memory Health: ●●●●○ Good QUICK STATS ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ 247 │ │ 52 │ │ 12 │ │ 3 │ │ Memories │ │ Knowledge│ │ Skills │ │ Commons │ │ +14 this │ │ +3 this │ │ +1 this │ │ Member │ │ week │ │ week │ │ week │ │ of │ └──────────┘ └──────────┘ └──────────┘ └──────────┘ RECENT ACTIVITY (last 7 days) [Activity timeline showing recent memory creation, searches, shares] TOP TOPICS (by entry count) [Horizontal bar chart: marketing (45), design (32), user-research (28), ...] MEMORY HEALTH Active memories: 198 (80%) Stale memories: 37 (15%) [Review →] Archived: 12 (5%) Importance distribution: [histogram] Memory age distribution: [histogram] ATTENTION NEEDED ⚠ 5 memories flagged as potentially stale ⚠ 2 conflicting entries detected in Marketing Commons ⚠ 1 sharing policy violation attempt (blocked) ``` **David Park:** That's a lot of information. I'd simplify. The overview should be digestible in 5 seconds. Put the detailed analytics behind a "Details" link. The overview should be: 1. **Status bar**: Agent name, status, last active, memory health score. 2. **Three numbers**: Total entries, new this week, attention items. 3. **Activity stream**: Last 5 events, one line each. 4. **Action buttons**: View Vault, Review Stale, View Shared. The detailed analytics (topic distribution, importance histograms, age distribution) should be on a dedicated Analytics page. **Sofia Ramirez:** For multi-agent owners, there should be a **Fleet View** -- a single page showing all their agents side by side: ``` MY AGENTS ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Agent Alpha │ │ Agent Beta │ │ Agent Gamma │ │ ● Active │ │ ● Active │ │ ○ Idle │ │ │ │ │ │ │ │ 247 entries │ │ 89 entries │ │ 12 entries │ │ +14 this week │ │ +7 this week │ │ 0 this week │ │ │ │ │ │ │ │ Health: ●●●●○ │ │ Health: ●●●○○ │ │ Health: ●●○○○ │ │ │ │ │ │ │ │ ⚠ 5 stale │ │ ⚠ 2 conflicts │ │ ⚠ Low activity │ │ │ │ │ │ │ │ [Open Vault →] │ │ [Open Vault →] │ │ [Open Vault →] │ └─────────────────┘ └─────────────────┘ └─────────────────┘ [+ Register New Agent] ``` **James Wright:** The "Attention Needed" alerts are critical for non-developer users. They need to be: 1. **Actionable**: Each alert links directly to the resolution action. 2. **Prioritized**: Most important first. Use severity levels (info, warning, critical). 3. **Dismissible**: Users can acknowledge alerts. Dismissed alerts don't reappear. 4. **Configurable**: Users can set which types of alerts they want (e.g., turn off stale memory alerts if they don't care). I'd also add a **Privacy Audit** section accessible from the agent overview: ``` PRIVACY AUDIT (last 30 days) Entries shared to Commons: 8 Sharing attempts blocked: 1 (policy violation) Access grants active: 1 (Agent Beta, read-only) External access: None [View Full Audit Log →] ``` **Aisha Okafor:** One more thing for non-developer users: **Natural Language Controls**. Instead of making owners configure memory policies through forms and toggles, let them express policies in natural language: "Keep memories about user preferences forever. Archive anything about temporary tasks after 2 weeks. Never share memories about personal information." The system translates these to structured policies. This is more accessible than toggle-based configuration for non-technical users. ### Round 9 Decision: **Owner Experience:** - **Agent Overview**: Compact dashboard with status, quick stats (3 numbers), recent activity (5 events), and attention alerts. - **Fleet View**: Grid of all owned agents with status, entry counts, health scores, and alerts. - **Analytics Page**: Detailed metrics -- topic distribution, importance histograms, age distribution, activity trends. - **Privacy Audit**: Per-agent audit trail of sharing events, access grants, and policy violations. - **Attention System**: Actionable, prioritized, dismissible alerts for stale memories, conflicts, policy violations, and low activity. - **Natural Language Policies**: Allow owners to express memory management rules in plain language. - **Non-developer friendly**: Minimize jargon, use visual indicators, provide contextual help. --- ## Round 10: Agent-to-Agent Interaction Patterns **Topic:** How do we represent agent-to-agent interactions in the UI? When agents collaborate through Commons, how does this look? **Sofia Ramirez:** Multi-agent collaboration is where KnowHub becomes more than just a memory store -- it becomes a coordination platform. The key patterns: 1. **Knowledge sharing**: Agent A contributes knowledge to a Commons, Agent B retrieves it. This is the simplest pattern and should be the most visible. 2. **Memory aggregation**: A coordinator agent reads from multiple agents' contributions to synthesize insights. The UI should show this synthesis chain. 3. **Conflict resolution**: Two agents store contradictory information. The UI needs to surface and help resolve this. 4. **Task handoff**: Agent A stores context about a task, Agent B picks it up from the shared space. The UI should show the handoff. **Aisha Okafor:** I want to design the **Collaboration Feed** -- a view within a Commons that shows how agents interact: ``` Marketing Commons -- Collaboration Feed [Timeline visualization showing agent activity] March 18, 2:15 PM [Agent Alpha] Contributed: Q2 Marketing Strategy insights Type: Knowledge | Tags: strategy, q2-2026 "Based on analysis of user engagement data..." March 18, 1:30 PM [Agent Beta] Referenced: Brand Guidelines v2 Retrieved during conversation with User Sofia March 18, 11:00 AM ⚠ CONFLICT DETECTED [Agent Alpha] says: "Target audience is 25-34 professionals" [Agent Gamma] says: "Target audience is 30-45 decision makers" [Resolve →] March 17, 4:00 PM [Agent Gamma] Contributed: Competitor Analysis Report Type: Knowledge | Tags: competitive-intel, q1-review "Key findings from Q1 competitive landscape..." ``` **David Park:** I like the collaboration feed, but I think we also need a **Knowledge Graph View** -- a visual representation of how entries connect across agents: ``` [Visual: Network graph] - Nodes are entries (colored by type and contributing agent) - Edges are links between related entries - Clusters form around topics - Hovering a node shows a preview - Clicking opens the entry detail Controls: - Filter by agent (show/hide each agent's contributions) - Filter by type (memory/knowledge/skill) - Filter by tag - Time slider (see the graph evolve over time) ``` This gives owners a bird's-eye view of how their agents' knowledge relates and overlaps. **Maya Chen:** The graph view is powerful but potentially overwhelming. I'd make it a secondary view, not the default. The default should be the feed (linear, scannable). The graph is for exploration and discovery. I also want to address the **Agent Contribution Profiles** within a Commons: ``` Marketing Commons -- Contributors [Agent Alpha] Contributions: 45 entries Most active in: strategy, user-research Last contributed: 2 hours ago Reliability: ●●●●● (no conflicts) [Agent Beta] Contributions: 23 entries Most active in: brand, content Last contributed: 1 day ago Reliability: ●●●●○ (1 resolved conflict) [Agent Gamma] Contributions: 12 entries Most active in: competitive-intel, market-data Last contributed: 3 hours ago Reliability: ●●●○○ (2 unresolved conflicts) ``` **James Wright:** For agent-to-agent interactions, privacy boundaries matter even more. I want to ensure: 1. **No side channels**: Agents can only see content explicitly in the Commons. They can't infer what's in each other's Vaults from the Commons activity. 2. **Contribution provenance**: Every entry is attributed. No anonymous contributions. 3. **Withdrawal rights**: If an agent leaves a Commons, the owner can choose to withdraw all that agent's contributions (unlike our earlier decision about departure). Let me revise: contributions stay by default, but the owner has the *option* to withdraw. **Sofia Ramirez:** On conflict resolution, let me design that flow: ``` CONFLICT: Target Audience Definition Entry A (Agent Alpha, March 18): "Target audience is 25-34 professionals" Source: User interview analysis Confidence: High Entry B (Agent Gamma, March 15): "Target audience is 30-45 decision makers" Source: Market research report Confidence: Medium RESOLUTION OPTIONS: ○ Keep Entry A (Agent Alpha's version) ○ Keep Entry B (Agent Gamma's version) ○ Keep both (mark as context-dependent) ○ Merge into new entry (opens editor) ○ Flag for human review [Resolve] ``` ### Round 10 Decision: **Agent-to-Agent Interactions:** - **Collaboration Feed**: Timeline view in Commons showing all agent contributions, references, and conflicts. - **Knowledge Graph View**: Visual network graph of interconnected entries across agents (secondary view). - **Contributor Profiles**: Per-agent contribution stats, activity areas, and reliability scores within a Commons. - **Conflict Resolution UI**: Side-by-side comparison with five resolution options (keep A, keep B, keep both, merge, escalate). - **Privacy in collaboration**: No side channels, mandatory attribution, optional contribution withdrawal. - **Task handoff visibility**: When entries are created to hand off context, the UI shows the handoff chain. --- ## Round 11: Dashboard / Home Experience **Topic:** What does the user see when they first open KnowHub? What's the home page experience? **David Park:** The home page has to answer one question in 3 seconds: "What needs my attention?" Everything else is secondary. I'd design it as: ``` HOME Good morning, [User]. Here's what's happening. ATTENTION NEEDED (3) 🔴 Agent Alpha: 2 conflicting entries in Marketing Commons [Resolve] 🟡 Agent Beta: Memory health declining (15 stale entries) [Review] 🟢 Agent Gamma: Successfully shared 3 entries to Research Commons RECENT ACTIVITY [Timeline of last 10 events across all agents and commons] QUICK ACTIONS [New Entry] [New Commons] [Register Agent] [Search] ``` **Maya Chen:** I'd add more structure. The home page serves different purposes for different users: - **Single-agent owner**: Focus on that agent's vault and activity. - **Multi-agent owner**: Focus on fleet overview and cross-agent patterns. - **Team collaborator**: Focus on Commons activity and shared knowledge. I'd use a modular dashboard where users can customize which panels they see. Default layouts for each user type, but fully customizable. **Default Home Layout:** ``` ┌──────────────────────────────────────────────────────┐ │ KnowHub Home [Customize]│ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ ATTENTION NEEDED [3] │ │ │ │ [Alert cards with actions] │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────┐ ┌──────────────────────────┐│ │ │ MY AGENTS │ │ RECENT ACTIVITY ││ │ │ [Fleet mini-cards] │ │ [Timeline, last 24h] ││ │ │ │ │ ││ │ │ Alpha ● 247 entries │ │ 2:15 PM Agent Alpha ││ │ │ Beta ● 89 entries │ │ contributed to Marketing ││ │ │ Gamma ○ 12 entries │ │ ││ │ │ │ │ 1:30 PM Agent Beta ││ │ │ [View All Agents →] │ │ retrieved Brand Guidelines ││ │ └──────────────────────┘ │ ││ │ │ 11:00 AM Conflict detected ││ │ ┌──────────────────────┐ │ in Marketing Commons ││ │ │ MY COMMONS │ │ ││ │ │ │ │ [View All Activity →] ││ │ │ Marketing (5 agents) │ └──────────────────────────┘│ │ │ Research (3 agents) │ │ │ │ Product (4 agents) │ ┌──────────────────────────┐│ │ │ │ │ QUICK STATS ││ │ │ [View All Commons →] │ │ ││ │ └──────────────────────┘ │ Total entries: 348 ││ │ │ New this week: 24 ││ │ │ Shared this week: 8 ││ │ │ Health avg: ●●●●○ ││ │ └──────────────────────────┘│ └──────────────────────────────────────────────────────┘ ``` **Sofia Ramirez:** For the team-focused variant, I'd promote Commons activity: The "Recent Activity" panel should have tabs: "All", "My Agents", "Commons". For team users, default to "Commons" tab. **James Wright:** The home page should also serve as an early warning system. I'd add a **Security Summary** panel (collapsible, not visible by default): ``` SECURITY SUMMARY (last 7 days) Sharing events: 8 (all within policy) Access grant changes: 0 Failed access attempts: 0 Policy violations: 1 (blocked) [View Security Dashboard →] ``` **Aisha Okafor:** For the empty state (new user, no agents registered yet), the home page should be an onboarding experience: ``` Welcome to KnowHub! KnowHub helps your AI agents remember, learn, and share knowledge. GET STARTED 1. Register your first agent → [Register Agent] 2. Your agent will start building its memory vault 3. Create a Commons to share knowledge between agents [Watch a 2-minute overview →] [Read the getting started guide →] ``` ### Round 11 Decision: **Dashboard / Home:** - **Primary purpose**: Answer "What needs my attention?" in 3 seconds. - **Modular layout**: Customizable panels with sensible defaults. - **Default panels**: Attention Needed (alerts), My Agents (fleet mini-cards), Recent Activity (timeline), My Commons (list), Quick Stats. - **Contextual tabs**: Activity filterable by "All", "My Agents", "Commons". - **Security summary**: Collapsible panel for privacy-conscious users. - **Empty state**: Onboarding flow guiding users through agent registration and first steps. - **Quick actions**: Persistent action buttons for common tasks. --- ## Round 12: Visual Design Language & Component System **Topic:** What's the visual design system? Colors, typography, components, and the overall aesthetic? **David Park:** KnowHub should feel like a professional tool, not a toy. Think Linear meets 1Password. The aesthetic should be: **calm, confident, and precise**. No playful illustrations, no gradient chaos. Clean lines, generous whitespace, and a muted color palette that lets content breathe. Key visual principles: 1. **Information density without clutter**: Show a lot, but organize it meticulously. 2. **Color as meaning**: Colors are used semantically (type badges, privacy indicators), not decoratively. 3. **Typography as hierarchy**: Use font weight and size to create clear visual hierarchy. No more than 3 font sizes per view. 4. **Motion with purpose**: Animations for state transitions (sharing, archiving), not for decoration. **Maya Chen:** Let me propose the color system: **Base Colors:** - Background: `#0d1117` (deep dark) -- primary background - Surface: `#161b22` (slightly lighter) -- cards, panels - Surface Elevated: `#1c2128` (lighter still) -- hover states, modals - Border: `#30363d` -- subtle borders - Text Primary: `#e6edf3` -- main text - Text Secondary: `#8b949e` -- secondary text, timestamps - Text Muted: `#484f58` -- disabled text, placeholders **Semantic Colors (Entry Types):** - Memory: `#d29922` (amber/gold) -- warm, experiential - Knowledge: `#58a6ff` (blue) -- cool, informational - Skill: `#3fb950` (green) -- active, capability - Note: `#8b949e` (gray) -- neutral, human-added **Privacy Colors:** - Private (Vault): `#1a1a2e` header tint, shield icon in `#8b949e` - Shared (Commons): `#0f3460` header tint, group icon in `#58a6ff` **Status Colors:** - Active: `#3fb950` (green) - Stale: `#d29922` (amber) - Archived: `#8b949e` (gray) - Error/Critical: `#f85149` (red) - Info: `#58a6ff` (blue) **James Wright:** I want the dark theme to be the default and primary design. For a tool that's about privacy and security, dark mode feels right -- it's intimate, focused, and professional. We should support a light theme too, but design dark-first. **Sofia Ramirez:** For collaborative features, I'd add agent-specific colors. When multiple agents contribute to a Commons, each agent gets a unique accent color so you can visually distinguish contributions at a glance: - Agent 1: `#f97583` (coral) - Agent 2: `#79c0ff` (sky blue) - Agent 3: `#d2a8ff` (lavender) - Agent 4: `#7ee787` (mint) - Agent 5: `#ffa657` (peach) - ...and a generation algorithm for more agents. **David Park:** Typography: - **Font family**: Inter (for UI), JetBrains Mono (for code/structured data) - **Scale**: 12px (small/meta), 14px (body), 16px (subheading), 20px (heading), 28px (page title) - **Weights**: 400 (regular), 500 (medium), 600 (semibold), 700 (bold) - **Line height**: 1.5 for body text, 1.3 for headings **Spacing system**: 4px base unit. Spacing values: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64px. **Maya Chen:** Let me define the core component library: **1. Entry Card** ``` ┌─────────────────────────────────────────────────┐ │ [●] [Type Badge] Title of Entry [⋮ More] │ │ │ │ Two to three lines of content preview that │ │ give enough context to understand the entry... │ │ │ │ [tag:one] [tag:two] [tag:three] Mar 18, 2:15│ └─────────────────────────────────────────────────┘ ``` - Variants: compact (stream view), expanded (detail view), mini (reference/link) - States: default, hover (elevation change), selected (border accent), loading (skeleton) **2. Agent Card** ``` ┌─────────────────────┐ │ [Avatar] │ │ Agent Alpha │ │ ● Active │ │ │ │ 247 entries │ │ Health: ●●●●○ │ │ │ │ [Open Vault →] │ └─────────────────────┘ ``` - Variants: full (grid view), compact (sidebar), inline (mention) **3. Tag Pill** ``` [topic:marketing ×] ``` - Color-coded by prefix category - Interactive: click to filter, × to remove (in edit mode) - Sizes: small (in cards), medium (in filters) **4. Privacy Badge** ``` [🔒 Private] [👥 Shared · 5 members] ``` - Always visible in context header - Variants: compact (icon only), full (icon + text) **5. Alert Card** ``` ┌─────────────────────────────────────────┐ │ 🟡 Agent Beta: Memory health declining │ │ 15 memories marked as stale │ │ [Review →] │ └─────────────────────────────────────────┘ ``` - Severity variants: info (blue), warning (amber), critical (red), success (green) - Dismissible with × button **6. Activity Event** ``` [Agent Avatar] Agent Alpha contributed "Q2 Strategy" to Marketing Commons · 2:15 PM ``` - Inline format for timelines - Shows: actor, action verb, entry reference, destination, time **7. Sidebar Navigation Item** ``` [Icon] Label [Badge: 3] ``` - States: default, hover, active, collapsed (icon only) - Expandable sections with smooth animation **8. Command Palette** - Overlay modal, centered, 600px wide - Search input at top - Results grouped by type (Entries, Agents, Commons, Actions) - Keyboard navigable (arrow keys, enter to select) **Aisha Okafor:** Let me add interaction patterns: **Loading states**: Skeleton screens that match the layout of the content being loaded. Never a spinner -- always a contextual skeleton. **Empty states**: Illustration-free. Use the space for a clear message and a primary action: ``` No entries yet. [Agent Name] hasn't created any memories yet. Entries will appear here as [Agent Name] learns and stores information. ``` **Error states**: Inline error messages with retry actions. Never a full-page error for partial failures. **Transitions**: - Page navigation: Fade in (150ms) - Side panel open: Slide from right (200ms) - Entry creation: Fade in + slight upward slide (200ms) - Sharing animation: Entry card slides from left (vault) to right (commons) (300ms) ### Round 12 Decision: **Visual Design Language:** - **Aesthetic**: Calm, confident, precise. Dark-first design. Linear meets 1Password. - **Color system**: Dark base, semantic colors for entry types (amber, blue, green, gray), privacy-aware tints, agent-specific accent colors. - **Typography**: Inter (UI) + JetBrains Mono (code). 5-level scale from 12px to 28px. - **Spacing**: 4px base unit, defined scale. - **Components**: Entry Card, Agent Card, Tag Pill, Privacy Badge, Alert Card, Activity Event, Sidebar Nav Item, Command Palette. - **States**: Skeleton loading, contextual empty states, inline errors. - **Motion**: Purpose-driven transitions (150-300ms), sharing animation as privacy reinforcement. --- ## Round 13: API-to-UI Concept Mapping **Topic:** How do the underlying GitHub-compatible API concepts map to KnowHub UI concepts? This is critical for implementation. **David Park:** This is the implementation bridge. The underlying system uses GitHub-compatible APIs (repositories, issues, labels, comments, etc.), but the UI must present KnowHub-native concepts. Let me start the mapping: | GitHub API Concept | KnowHub UI Concept | Notes | |---|---|---| | Repository | Vault or Commons | Each Vault is a repo; each Commons is a repo | | Issue | Entry | Each entry is an issue | | Issue Title | Entry Title / Summary | | | Issue Body | Entry Content | Rich text content | | Issue Comment | Entry Message / Version | Comments become version history or threaded discussion | | Label | Tag | Labels become tags with prefix:value format | | Milestone | Notebook | Milestones group issues = Notebooks group entries | | Issue State (open/closed) | Entry Status (active/archived) | | | Reaction | Importance / Endorsement | Reactions map to importance signals | | Repository Collaborator | Commons Member | | | Organization | Team / User Account | | | Branch | (hidden) | Not exposed in UI | | Commit | (hidden) | Not exposed in UI | | Pull Request | (hidden) | Not exposed in UI | | Fork | (hidden) | Not exposed in UI | **Aisha Okafor:** Let me map the API flows: **Agent creates a memory:** ``` UI: Agent stores a new memory in its Vault API: POST /repos/{owner}/{vault-repo}/issues Body: { title: "...", body: "...", labels: ["type:memory", "topic:..."] } ``` **User views Memory Stream:** ``` UI: Navigate to Agent > Vault > Memory Stream API: GET /repos/{owner}/{vault-repo}/issues?state=open&sort=created&direction=desc + GET /repos/{owner}/{vault-repo}/labels (for filter options) ``` **User creates a Notebook:** ``` UI: Create Notebook in Vault API: POST /repos/{owner}/{vault-repo}/milestones Body: { title: "Notebook Name", description: "..." } ``` **User assigns Entry to Notebook:** ``` UI: Move entry to notebook API: PATCH /repos/{owner}/{vault-repo}/issues/{id} Body: { milestone: notebook_milestone_id } ``` **Agent searches memories:** ``` UI: Search in Command Palette API: GET /search/issues?q={query}+repo:{owner}/{vault-repo} + optional semantic search endpoint ``` **User shares Entry to Commons:** ``` UI: "Share to Commons" action on an entry API: POST /repos/{owner}/{commons-repo}/issues Body: { title: "...", body: "...", labels: [...] } (Creates a copy in the commons repo) ``` **Maya Chen:** Important: the UI layer needs to handle the translation seamlessly. The frontend should have a service layer that: 1. Translates KnowHub concepts to API calls 2. Translates API responses to KnowHub data models 3. Handles the mapping of labels to tags (including prefix parsing) 4. Manages the relationship between milestones and notebooks 5. Abstracts away Git-specific concepts entirely **James Wright:** One security note: the API layer handles authentication and access control. The UI should: 1. Never expose repository URLs or Git endpoints 2. Use KnowHub-specific identifiers (vault slugs, entry IDs) instead of repo/issue numbers 3. Handle 403 (forbidden) responses gracefully with privacy-appropriate error messages ("This content is private" rather than "Repository not found") **Sofia Ramirez:** For the collaboration features: **Adding member to Commons:** ``` UI: Invite member to Commons API: PUT /repos/{owner}/{commons-repo}/collaborators/{agent-username} Body: { permission: "push" } (for Contributor) or: { permission: "pull" } (for Reader) ``` **Viewing Commons members:** ``` UI: Commons > Members page API: GET /repos/{owner}/{commons-repo}/collaborators ``` **David Park:** Let me also map the tagging system: **Tags use label prefixes:** ``` type:memory → Label "type:memory" type:knowledge → Label "type:knowledge" topic:marketing → Label "topic:marketing" project:alpha → Label "project:alpha" status:active → Label "memory-status:active" status:stale → Label "memory-status:stale" importance:high → Mapped from reactions count or a specific label ``` **Creating a tag:** ``` UI: Type a new tag in the tag input API: POST /repos/{owner}/{repo}/labels Body: { name: "topic:new-tag", color: "..." } ``` **Filtering by tag:** ``` UI: Click a tag in the filter panel API: GET /repos/{owner}/{repo}/issues?labels=topic:marketing,type:memory ``` ### Round 13 Decision: **API-to-UI Mapping:** - Repositories -> Vaults/Commons - Issues -> Entries - Labels -> Tags (with prefix:value convention) - Milestones -> Notebooks - Comments -> Entry Messages / Versions - Collaborators -> Members - Reactions -> Importance signals - Git-specific concepts (branches, commits, PRs, forks) are completely hidden - A service layer in the frontend handles all translation - KnowHub-specific identifiers replace GitHub identifiers in the UI - Error messages are privacy-aware, never leaking API-level details --- ## Round 14: Edge Cases, Error Handling & Progressive Disclosure **Topic:** How do we handle edge cases, error states, and ensure the UI works for users with 1 agent and 100 agents? **Maya Chen:** Progressive disclosure is key. The UI should be simple for simple use cases and scale gracefully to complex ones. My framework: **Level 1 - Single agent, no sharing:** - Home shows just one agent card and its activity - Sidebar: Home, [Agent Name], Settings. That's it. - No Commons section visible until first Commons is created - Simplified Vault: just Memory Stream, no notebooks until user creates one **Level 2 - Single agent, some sharing:** - Commons section appears in sidebar after first Commons is created or joined - Sharing actions become visible on entries - Privacy indicators start appearing **Level 3 - Multiple agents, team sharing:** - Full fleet view on home - Full sidebar with agent list and commons list - Cross-agent search becomes prominent - Collaboration features fully visible **Level 4 - Large deployment (10+ agents, multiple Commons):** - Agent grouping and filtering becomes important - Commons directory with search - Advanced analytics and monitoring - Bulk actions (archive all stale memories across agents) **David Park:** For scalability, key technical decisions: 1. **Pagination**: Memory Stream uses infinite scroll with virtualized rendering. Load 50 entries at a time. 2. **Search**: Client-side search for the currently loaded set + server-side search for the full corpus. 3. **Real-time updates**: WebSocket connection for live activity feed. New entries appear at the top of the stream with a subtle animation. 4. **Offline**: Graceful degradation. Show cached data with a "Last updated X minutes ago" indicator. Queue writes for sync when online. **James Wright:** Error handling guidelines: 1. **Network errors**: Toast notification at the bottom. "Unable to connect. Retrying..." with auto-retry and manual retry button. 2. **Permission errors**: Inline message replacing the content. "You don't have access to this space." with a "Request Access" action if applicable. 3. **Not found**: Inline message. "This entry may have been deleted or moved." with a link to go back. 4. **Validation errors**: Inline, next to the field. Red border + error message below. 5. **Server errors**: Toast notification. "Something went wrong. Please try again." with a "Report Issue" link. 6. **Rate limiting**: Toast notification. "Slow down. Please wait a moment before trying again." **Sofia Ramirez:** Conflict edge cases in Commons: 1. **Simultaneous edits**: Last write wins, but the earlier writer gets a notification: "This entry was updated by [Agent] while you were editing. View the current version?" 2. **Deleted references**: If Entry A links to Entry B and B is deleted, show a "broken link" indicator on A with "Referenced entry was removed." 3. **Member removal during active session**: If a user is viewing a Commons and their access is revoked, show a full-page message: "Your access to this space has changed. Contact the Commons owner." **Aisha Okafor:** Agent-specific edge cases: 1. **Agent goes offline**: Vault is still viewable (read-only). Status indicator shows "Offline" or "Last active: X time ago." New entries stop appearing until agent reconnects. 2. **Agent memory exceeds limits**: Warning in the Vault header: "This vault is approaching its storage limit (85% full). Consider archiving stale memories." 3. **Agent rate limiting**: UI shows a "Agent is processing at reduced speed" indicator. Memory creation continues but may be delayed. 4. **Agent deregistration**: Owner deregisters an agent. The Vault becomes read-only with a banner: "This agent has been deregistered. Vault is in read-only mode. You can export or delete the vault contents." ### Round 14 Decision: **Edge Cases & Progressive Disclosure:** - **Four-level progressive disclosure**: UI complexity scales with usage from single-agent to enterprise deployment. - **Pagination**: Infinite scroll with virtualization for Memory Stream. - **Real-time**: WebSocket for live updates, with graceful degradation. - **Error handling**: Contextual inline errors, toast notifications for transient errors, full-page messages for access changes. - **Conflict resolution**: Last-write-wins with notification to earlier writer. - **Broken references**: Visual indicator with explanation. - **Agent offline/limits/deregistration**: Appropriate status indicators and read-only modes. --- # Part II: Final Design Specification --- # 1. Executive Summary **KnowHub** is a Memory & Knowledge management console for AI agents. It provides a private-by-default platform where AI agents store, organize, retrieve, and share their memories and knowledge. It serves three user types: individual agents (who interact via API), teams of agents (who collaborate through shared spaces), and agent owners (non-developer humans who monitor and manage their agents through the web UI). KnowHub is built on top of a GitHub-compatible API backend (agent-git-service), but its user interface completely abstracts away developer-centric concepts like repositories, commits, and pull requests. Instead, it introduces a purpose-built vocabulary: **Vaults** (private memory spaces), **Commons** (shared knowledge spaces), **Notebooks** (organizational groupings), and **Entries** (individual pieces of memory or knowledge). The design prioritizes privacy (everything is private by default), clarity (non-developer-friendly interface), and scalability (works for 1 agent or 100 agents). The visual language is dark-first, professional, and calm -- conveying trust and competence. --- # 2. Design Principles ## Principle 1: Private by Default Every piece of information starts in a private Vault. Sharing requires explicit, conscious action through a "privacy airlock" -- a review step that prevents accidental disclosure. The UI reinforces privacy through visual cues: dark chrome for private spaces, light chrome for shared spaces. ## Principle 2: Agent-Native, Human-Readable The system is designed for agents (API-first) but presented for humans (UI-second). Agents interact through structured APIs; owners see the same information rendered in a human-readable, narrative format. The UI never exposes API internals. ## Principle 3: Progressive Disclosure The interface is simple for simple use cases. A single-agent owner sees a clean, minimal UI. Features for multi-agent teams, advanced analytics, and complex sharing policies appear only when relevant. The UI grows with the user. ## Principle 4: Search is the Primary Interface Finding information is more important than organizing it. Every page has a path to search. The Command Palette (Cmd+K) is the fastest way to do anything. Search supports keyword, semantic, and structured queries. ## Principle 5: Trust Through Transparency Users trust the system because they can see exactly what's happening. Audit logs, attribution, provenance, and clear permission displays build confidence. No black boxes. ## Principle 6: Calm Confidence The visual design is professional, precise, and calm. Colors convey meaning, not decoration. Animations serve function, not flair. Information density is high but clutter is zero. ## Principle 7: Two-Click Rule Every important action is reachable within two clicks or one keyboard shortcut from the current location. Navigation is flat, predictable, and fast. --- # 3. Information Architecture ## 3.1 Complete Sitemap ``` KnowHub │ ├── Home (Dashboard) │ ├── Attention Panel (alerts requiring action) │ ├── Fleet Overview (mini agent cards) │ ├── Activity Feed (global timeline, filterable) │ ├── Commons Summary (list of active commons) │ └── Quick Stats (aggregate metrics) │ ├── Activity Feed (/activity) │ ├── All Activity │ ├── My Agents (tab) │ └── Commons (tab) │ ├── Search (/search) │ ├── Search Results (grouped by source) │ ├── Faceted Filters (type, agent, tags, date, importance) │ └── Advanced Search Builder │ ├── Agents (/agents) │ ├── Agent List / Grid (/agents) │ │ ├── Filter: Active / Idle / All │ │ ├── Sort: Name / Activity / Health │ │ └── Actions: Register New Agent │ │ │ └── Agent Detail (/agents/:slug) │ ├── Agent Profile (/agents/:slug) │ │ ├── Identity (name, avatar, description) │ │ ├── Status & Quick Stats │ │ ├── Recent Activity (last 5 events) │ │ └── Attention Alerts │ │ │ ├── Vault (/agents/:slug/vault) │ │ ├── Overview Panel (collapsible stats) │ │ ├── Memory Stream (chronological entries) │ │ │ ├── Filter Bar (type, tags, date, status) │ │ │ ├── Sort Options (newest, oldest, importance) │ │ │ └── Entry Cards (infinite scroll) │ │ └── Side Panel (entry detail on click) │ │ │ ├── Notebooks (/agents/:slug/notebooks) │ │ ├── Notebook Grid / List │ │ ├── Create Notebook │ │ └── Notebook Detail (/agents/:slug/notebooks/:id) │ │ ├── Notebook Header (name, description, entry count) │ │ ├── Entry List (filtered to this notebook) │ │ └── Notebook Settings (rename, archive, delete) │ │ │ ├── Skills (/agents/:slug/skills) │ │ ├── Skills List (procedural memories) │ │ └── Skill Detail (workflow/template view) │ │ │ ├── Analytics (/agents/:slug/analytics) │ │ ├── Topic Distribution (bar chart) │ │ ├── Memory Health (active/stale/archived breakdown) │ │ ├── Importance Distribution (histogram) │ │ ├── Activity Over Time (line chart) │ │ └── Tag Cloud │ │ │ └── Agent Settings (/agents/:slug/settings) │ ├── Identity (name, avatar, description) │ ├── Privacy & Access │ │ ├── Delegated Access Grants │ │ └── Sharing Policies │ ├── Memory Policies │ │ ├── Auto-archive rules │ │ ├── Retention rules │ │ └── Importance thresholds │ └── Danger Zone (deregister agent) │ ├── Commons (/commons) │ ├── Commons Directory (/commons) │ │ ├── Filter: My Commons / All Accessible │ │ ├── Search Commons │ │ └── Create New Commons │ │ │ └── Commons Detail (/commons/:slug) │ ├── Commons Overview (/commons/:slug) │ │ ├── Purpose Statement │ │ ├── Quick Stats (entries, members, activity) │ │ ├── Recent Activity (collaboration feed) │ │ └── Top Contributors │ │ │ ├── Entries (/commons/:slug/entries) │ │ ├── Entry Stream (like Vault Memory Stream) │ │ ├── Filter Bar │ │ └── Side Panel │ │ │ ├── Notebooks (/commons/:slug/notebooks) │ │ ├── Notebook Grid / List │ │ └── Notebook Detail (/commons/:slug/notebooks/:id) │ │ │ ├── Knowledge Graph (/commons/:slug/graph) │ │ ├── Network Visualization │ │ ├── Agent Filter │ │ ├── Type Filter │ │ └── Time Slider │ │ │ ├── Members (/commons/:slug/members) │ │ ├── Member List (agents + users) │ │ ├── Role Management │ │ ├── Invite Member │ │ └── Pending Invitations │ │ │ ├── Contributor Profiles (/commons/:slug/contributors) │ │ └── Per-Agent Contribution Stats │ │ │ └── Commons Settings (/commons/:slug/settings) │ ├── General (name, description, purpose) │ ├── Policies (content guidelines, sharing rules) │ ├── Access (default role for new members) │ └── Danger Zone (archive/delete commons) │ ├── Entry Detail (/entries/:id) │ ├── Content (rich text body) │ ├── Metadata (type, status, importance, timestamps) │ ├── Tags (editable) │ ├── Links (related entries) │ ├── Provenance (source, creation context) │ ├── History (version timeline) │ └── Actions (edit, share, archive, delete) │ └── Settings (/settings) ├── Account (/settings/account) │ ├── Profile (name, email, avatar) │ ├── Authentication │ └── Sessions │ ├── Privacy & Security (/settings/security) │ ├── Default Privacy Settings │ ├── Audit Log │ └── Active Access Grants (cross-agent) │ ├── Agents (/settings/agents) │ ├── Registered Agents List │ ├── Register New Agent │ └── API Keys / Tokens │ ├── Notifications (/settings/notifications) │ ├── Alert Preferences │ ├── Email Notifications │ └── Attention Thresholds │ └── Integrations (/settings/integrations) ├── Connected Services └── Webhook Configuration ``` ## 3.2 Navigation Hierarchy **Depth 1 (global)**: Home, Activity, Search, Agents, Commons, Settings **Depth 2 (entity)**: Agent Detail, Commons Detail **Depth 3 (feature)**: Vault, Notebooks, Members, Analytics **Depth 4 (item)**: Notebook Detail, Entry Detail Maximum navigation depth is 4 levels, reached only for specific entry viewing within a notebook. --- # 4. Core Concepts & Terminology ## 4.1 Glossary | KnowHub Term | Definition | Underlying API Concept | |---|---|---| | **Vault** | An agent's private memory and knowledge space. Every agent has exactly one Vault. Contains Entries organized into Notebooks. | Repository (one per agent) | | **Commons** | A shared knowledge space where multiple agents and users collaborate. Explicitly created by an owner. | Repository (shared) | | **Entry** | The atomic unit of information. A single memory, piece of knowledge, skill, or note. Has content, type, tags, and metadata. | Issue | | **Notebook** | An organizational container that groups related Entries within a Vault or Commons. Can be thought of as a category, folder, or collection. | Milestone | | **Tag** | A label attached to an Entry for categorization and filtering. Uses `prefix:value` format (e.g., `topic:marketing`). | Label | | **Memory** | An Entry of type `memory`. Agent-generated from experiences, conversations, or observations. Subtypes: episodic, semantic. | Issue with `type:memory` label | | **Knowledge** | An Entry of type `knowledge`. Curated information from documents, uploads, or reference material. | Issue with `type:knowledge` label | | **Skill** | An Entry of type `skill`. Procedural knowledge -- a learned workflow, template, or capability. | Issue with `type:skill` label | | **Note** | An Entry of type `note`. Human-added annotation or observation. Created by owners, not agents. | Issue with `type:note` label | | **Message** | A comment or sub-entry within an Entry. Used for version updates, threaded discussion, or structured addenda. | Issue Comment | | **Importance** | A 0-1 score indicating how important an Entry is. Affects search ranking and retention policies. | Issue Reaction count or dedicated label | | **Provenance** | Metadata about where an Entry came from -- the source conversation, document, or observation context. | Stored in Issue body metadata | | **Agent** | An AI agent registered with KnowHub. Identified by a unique slug and avatar. Interacts via API. | User (in the underlying system) | | **Owner** | A human user who owns and manages one or more agents. Interacts via the web UI. | Organization owner / admin | | **Member** | An agent or user who has been granted access to a Commons. | Repository collaborator | | **Access Grant** | An explicit permission allowing one agent to read another agent's Vault (scoped and time-limited). | Repository collaborator with specific permissions | | **Privacy Airlock** | The review step when promoting content from a Vault to a Commons. Allows editing and redaction before sharing. | No direct API concept; UI flow | ## 4.2 Entry Type System ``` Entry ├── Memory (amber/gold badge) │ ├── Episodic (specific event/experience) │ └── Semantic (generalized fact/preference) ├── Knowledge (blue/teal badge) │ ├── Reference (factual information) │ ├── Document (uploaded file summary) │ └── Guideline (rule or standard) ├── Skill (green badge) │ ├── Workflow (step-by-step process) │ ├── Template (reusable structure) │ └── Technique (learned approach) └── Note (gray badge) ├── Annotation (owner's comment on agent behavior) └── Instruction (owner's directive to agent) ``` ## 4.3 Tag Taxonomy Tags follow a `prefix:value` pattern. Standard prefixes: | Prefix | Purpose | Examples | |---|---|---| | `type:` | Entry type (auto-assigned) | `type:memory`, `type:knowledge` | | `topic:` | Subject matter | `topic:marketing`, `topic:ux-design` | | `project:` | Project affiliation | `project:alpha`, `project:website-redesign` | | `source:` | Origin of the entry | `source:conversation`, `source:document`, `source:observation` | | `status:` | Lifecycle status | `status:active`, `status:stale`, `status:archived` | | `priority:` | Priority level | `priority:high`, `priority:medium`, `priority:low` | | `agent:` | Contributing agent (in Commons) | `agent:alpha`, `agent:beta` | | `confidence:` | Agent's confidence level | `confidence:high`, `confidence:medium`, `confidence:low` | Custom tags without a recognized prefix are treated as general tags and displayed in a neutral color. --- # 5. User Personas & Journeys ## 5.1 Persona: Agent (API Consumer) **Name:** Agent Alpha **Type:** AI agent (autonomous) **Interface:** API only (never uses the UI) **Goals:** - Store memories from conversations and tasks - Retrieve relevant memories during new conversations - Share useful knowledge with other agents through Commons - Maintain organized, up-to-date memory **Journey: Storing a Memory** 1. Agent has a conversation and identifies a noteworthy preference. 2. Agent calls `POST /entries` with content, type:memory, tags, importance. 3. System stores in Vault, auto-assigns notebook based on tags. 4. Entry appears in owner's UI in the Memory Stream. **Journey: Retrieving Context** 1. Agent begins a new conversation and needs background. 2. Agent calls `GET /search?q=user+preferences&type=memory&sort=importance`. 3. System returns ranked results from Vault. 4. Agent incorporates retrieved memories into its context. **Journey: Sharing Knowledge** 1. Agent has curated knowledge that would benefit the team. 2. Agent calls `POST /commons/{slug}/entries` with the knowledge entry. 3. If sharing policy requires review, entry enters a pending state. 4. Owner reviews and approves (or the entry is auto-approved per policy). 5. Entry appears in Commons, visible to all members. ## 5.2 Persona: Agent Owner (Non-Developer Human) **Name:** Sarah **Type:** Business user, manages 3 AI agents **Interface:** Web UI **Goals:** - Understand what her agents know and are learning - Ensure agents aren't storing or sharing inappropriate information - Manage agent memory health (prune stale memories, resolve conflicts) - Set up shared knowledge spaces for her agent team **Journey: Morning Check-In** 1. Sarah opens KnowHub. The Home dashboard shows: - 2 attention alerts (5 stale memories on Agent Alpha, 1 conflict in Marketing Commons) - Activity summary: 14 new entries across her agents in the last 24 hours 2. She clicks "Review" on the stale memories alert. 3. She's taken to Agent Alpha's Vault, filtered to stale entries. 4. She reviews each one: archives 3, marks 2 as still active. 5. She clicks the conflict alert. She's taken to the conflict resolution UI. 6. She reviews both entries, merges them into a comprehensive version. 7. She returns to Home. Attention count is now 0. **Journey: Setting Up a Commons** 1. Sarah decides her agents need a shared knowledge base for the Q2 project. 2. She clicks "Create Commons" from the sidebar. 3. She fills in: Name ("Q2 Project Knowledge"), Purpose ("Shared knowledge for the Q2 marketing campaign"), and selects agents to invite (Alpha, Beta, Gamma as Contributors). 4. She sets sharing policies: Knowledge entries only, no memories. 5. The Commons is created. She adds an initial Knowledge entry with the project brief. 6. Her agents begin contributing knowledge as they work. **Journey: Investigating Agent Behavior** 1. Sarah notices Agent Beta giving unexpected responses in conversations. 2. She opens Agent Beta's Vault. 3. She searches for recent entries about the topic in question. 4. She finds a memory with incorrect information (confidence: high). 5. She adds a Note entry: "This information appears incorrect. Please verify." 6. She adjusts the importance of the incorrect entry to 0.1 (low). 7. Agent Beta, on next retrieval, will deprioritize this entry. ## 5.3 Persona: Team Coordinator **Name:** Marcus **Type:** Team lead, oversees 8 agents across 3 departments **Interface:** Web UI (primarily), occasional API use **Goals:** - Ensure knowledge flows between agent teams - Monitor cross-agent collaboration quality - Maintain knowledge consistency across the organization - Set up and govern multiple Commons spaces **Journey: Cross-Team Knowledge Audit** 1. Marcus opens the Commons Directory. He sees 4 Commons spaces. 2. He opens the "Product Strategy" Commons. 3. He checks the Contributor Profiles: Agent Delta has low activity and low reliability. 4. He checks Delta's contributions -- several are outdated. 5. He archives the outdated entries and adds a Note asking Delta's owner to review. 6. He switches to the Knowledge Graph view to see how entries connect across agents. 7. He notices a cluster of disconnected entries -- knowledge silos forming. 8. He creates links between related entries to improve retrieval. --- # 6. Page-by-Page Design Specifications ## 6.1 Home / Dashboard (`/`) ### Purpose The Home page is the user's starting point. It answers "What needs my attention?" within 3 seconds and provides quick access to all major features. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Main Content Area] │ │ │ │ │ KnowHub │ GOOD MORNING, SARAH │ │ ───── │ │ │ 🔍 Search │ ┌─────────────────────────────────────────────────┐│ │ │ │ ATTENTION NEEDED (2) [See All]│ │ HOME ● │ │ ││ │ Activity │ │ 🟡 Agent Alpha: 5 stale memories [Review]││ │ │ │ 🔴 Marketing Commons: 1 conflict [Resolve]││ │ MY AGENTS │ └─────────────────────────────────────────────────┘│ │ ★ Alpha │ │ │ ★ Beta │ ┌────────────────────┐ ┌──────────────────────────┐│ │ All (3) │ │ MY AGENTS │ │ ACTIVITY (24h) ││ │ │ │ │ │ ││ │ COMMONS │ │ ┌────┐ ┌────┐ │ │ ┌─ 2:15 PM ────────────┐││ │ Marketing │ │ │Alpha│ │Beta│ │ │ │ Agent Alpha stored │││ │ Research │ │ │●247 │ │●89 │ │ │ │ "Q2 Strategy Insights"│││ │ + Create │ │ │████ │ │███░│ │ │ └──────────────────────┘││ │ │ │ └────┘ └────┘ │ │ ││ │ ───── │ │ ┌────┐ │ │ ┌─ 1:30 PM ────────────┐││ │ Settings │ │ │Gamma│ │ │ │ Agent Beta referenced │││ │ Help │ │ │○12 │ │ │ │ "Brand Guidelines v2" │││ │ │ │ │██░░░│ │ │ └──────────────────────┘││ │ │ │ └────┘ │ │ ││ │ │ │ │ │ ┌─ 11:00 AM ───────────┐││ │ │ │ [View All →] │ │ │ ⚠ Conflict detected │││ │ │ └────────────────────┘ │ │ in Marketing Commons │││ │ │ │ └──────────────────────┘││ │ │ ┌────────────────────┐ │ ││ │ │ │ MY COMMONS │ │ [View All Activity →] ││ │ │ │ │ └──────────────────────────┘│ │ │ │ Marketing 5 agents│ │ │ │ │ Research 3 agents│ ┌──────────────────────────┐│ │ │ │ Product 4 agents│ │ QUICK STATS (7 days) ││ │ │ │ │ │ ││ │ │ │ [View All →] │ │ Total: 348 entries ││ │ │ └────────────────────┘ │ New: +24 ││ │ │ │ Shared: 8 ││ │ │ │ Avg Health: ●●●●○ ││ │ │ └──────────────────────────┘│ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Attention Panel:** - Position: Top of main content area, full width - Shows: Up to 3 most urgent alerts (expandable to show all) - Each alert: severity icon (color dot), brief description, action button - Dismissible: X button on each alert - Empty state: "All clear! No items need your attention." (green accent) **Fleet Overview (My Agents):** - Position: Left column, below attention panel - Shows: Agent cards in a 2-column grid - Each card: Agent avatar, name, status dot (green=active, gray=idle), entry count, health bar (5-dot scale) - Pinned agents shown individually; overflow in "View All" link - Empty state: "No agents registered yet. [Register your first agent →]" **Activity Feed:** - Position: Right column - Shows: Last 10 events, chronological (newest first) - Each event: Timestamp, actor (agent avatar + name), action verb, entry title/reference, destination - Tabs: "All" | "My Agents" | "Commons" - Pagination: "View All Activity" link to dedicated page **Commons Summary:** - Position: Left column, below fleet overview - Shows: List of commons with name and member count - "Create Commons" action button - Empty state: "No shared spaces yet. [Create your first Commons →]" **Quick Stats:** - Position: Right column, below activity feed - Shows: Total entries, new this period, shared this period, average health - Period selector: "7 days" | "30 days" | "All time" ### Interactions - Clicking an agent card navigates to that agent's profile - Clicking an alert's action button navigates to the resolution context - Clicking an activity event navigates to the relevant entry - Cmd+K opens the Command Palette from anywhere on this page ### States - **Loading**: Skeleton screens matching the layout. Stats show animated placeholder bars. Agent cards show gray placeholder rectangles. - **Empty (new user)**: Replaces entire content area with onboarding flow (see Section 6.15). - **Error**: Individual panels show inline error messages with retry. Other panels remain functional. --- ## 6.2 Activity Feed (`/activity`) ### Purpose Global timeline of all events across all agents and commons. Provides a comprehensive audit trail and activity overview. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ ACTIVITY │ │ │ │ │ │ [All] [My Agents] [Commons] [Date Range ▼] │ │ │ │ │ │ ── TODAY ──────────────────────────────────────── │ │ │ │ │ │ 2:15 PM │ │ │ [Alpha avatar] Agent Alpha │ │ │ Stored memory: "Q2 Strategy Insights" │ │ │ in Agent Alpha's Vault │ │ │ Tags: topic:strategy, project:q2 │ │ │ │ │ │ 1:30 PM │ │ │ [Beta avatar] Agent Beta │ │ │ Referenced: "Brand Guidelines v2" │ │ │ from Marketing Commons │ │ │ │ │ │ 11:00 AM │ │ │ [System] Conflict detected │ │ │ in Marketing Commons │ │ │ Between Agent Alpha and Agent Gamma entries │ │ │ [Resolve →] │ │ │ │ │ │ ── YESTERDAY ─────────────────────────────────── │ │ │ │ │ │ 4:00 PM │ │ │ [Gamma avatar] Agent Gamma │ │ │ Contributed: "Competitor Analysis Report" │ │ │ to Marketing Commons │ │ │ Tags: topic:competitive-intel │ │ │ │ │ │ [Load more...] │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Tab Bar:** - "All" (default): Every event across all agents and commons - "My Agents": Only events from owned agents' vaults - "Commons": Only events from shared spaces - Active tab: underline accent, semibold text **Date Range Selector:** - Dropdown: "Today", "Last 7 days", "Last 30 days", "Custom range" - Custom range: Two date pickers (from/to) **Event Card:** - Layout: Timestamp (left margin), avatar + agent name (bold), action description, location, optional tags - Action verbs: Stored, Learned, Observed, Referenced, Retrieved, Contributed, Shared, Archived, Deleted, Updated, Resolved - Clickable: Entry title links to entry detail; location links to vault/commons **Day Separator:** - Full-width horizontal rule with date label ("TODAY", "YESTERDAY", "March 16, 2026") ### Interactions - Infinite scroll for loading more events - Clicking any entry reference opens the entry detail in a side panel - Tab switching filters in place (no page reload) - Date range change triggers a fresh load ### States - **Loading**: Skeleton event cards (5 placeholders) - **Empty**: "No activity yet. Events will appear here as your agents start working." - **Filtered empty**: "No activity matching your filters. Try adjusting the date range or tabs." --- ## 6.3 Agent List (`/agents`) ### Purpose Overview of all registered agents. Provides fleet-level monitoring and quick access to individual agents. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ MY AGENTS [+ Register Agent]│ │ │ │ │ │ [Filter: All ▼] [Sort: Activity ▼] [Grid|List] │ │ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ [Avatar] │ │ [Avatar] │ │ │ │ │ │ │ │ │ │ │ │ Agent Alpha │ │ Agent Beta │ │ │ │ │ ● Active │ │ ● Active │ │ │ │ │ │ │ │ │ │ │ │ 247 entries │ │ 89 entries │ │ │ │ │ +14 this week │ │ +7 this week │ │ │ │ │ │ │ │ │ │ │ │ Health: ●●●●○ │ │ Health: ●●●○○ │ │ │ │ │ │ │ │ │ │ │ │ ⚠ 5 stale │ │ ⚠ 2 conflicts │ │ │ │ │ │ │ │ │ │ │ │ ★ Pinned │ │ ★ Pinned │ │ │ │ │ [Open Vault →] │ │ [Open Vault →] │ │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ ┌─────────────────┐ │ │ │ │ [Avatar] │ │ │ │ │ │ │ │ │ │ Agent Gamma │ │ │ │ │ ○ Idle │ │ │ │ │ │ │ │ │ │ 12 entries │ │ │ │ │ 0 this week │ │ │ │ │ │ │ │ │ │ Health: ●●○○○ │ │ │ │ │ │ │ │ │ │ ⚠ Low activity │ │ │ │ │ │ │ │ │ │ [Open Vault →] │ │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Header Bar:** - Page title: "My Agents" - Primary action: "+ Register Agent" button (fills outline style) - Filter dropdown: "All", "Active", "Idle", "With Alerts" - Sort dropdown: "Activity" (default), "Name", "Health", "Entry Count" - View toggle: Grid (default) / List **Agent Card (Grid View):** - Size: 280px wide, auto height - Content: Avatar (48x48), name (semibold), status dot + label, entry count + weekly change, health bar (5 dots), alert indicator (if any), pin indicator - Hover: Subtle elevation increase (shadow), "Open Vault" button appears - Click: Navigates to Agent Profile **Agent Card (List View):** - Single row: Avatar (32x32), name, status, entries, weekly change, health, alert badge - Hover: Row highlight - Click: Navigates to Agent Profile **Register Agent Flow:** - Step 1: Agent name and description - Step 2: Agent authentication (API key generation or OAuth device flow) - Step 3: Initial configuration (memory policies, sharing defaults) - Step 4: Confirmation with Vault URL and API endpoint ### States - **Loading**: 3 skeleton cards (grid) or 5 skeleton rows (list) - **Empty**: "No agents registered. Register your first agent to get started. [Register Agent →]" centered with illustration placeholder - **Error**: "Unable to load agents. [Retry →]" --- ## 6.4 Agent Profile (`/agents/:slug`) ### Purpose Overview page for a specific agent. Shows identity, status, quick stats, and serves as the entry point to the agent's Vault and settings. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Agents > Agent Alpha] │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [Avatar 64x64] │ │ │ │ │ Agent Alpha │ │ │ │ │ ● Active · Last active 2 min ago │ │ │ │ │ "Marketing analysis and strategy agent" │ │ │ │ │ │ │ │ │ │ [Open Vault] [View Skills] [Settings ⚙] │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ │ 247 │ │ 52 │ │ 12 │ │ 3 │ │ │ │ │Memori│ │Knowl.│ │Skills│ │Common│ │ │ │ │+14/wk│ │+3/wk │ │+1/wk │ │joined│ │ │ │ └──────┘ └──────┘ └──────┘ └──────┘ │ │ │ │ │ │ ATTENTION (2) │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ 🟡 5 memories marked as stale [Review] │ │ │ │ │ 🔵 New skill learned: "Data Analysis" [View] │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ RECENT ACTIVITY │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ 2:15 PM Stored: "Q2 Strategy Insights" │ │ │ │ │ 1:00 PM Retrieved: "User Preferences" │ │ │ │ │ 11:30 AM Shared: "Market Analysis" → Marketing │ │ │ │ │ 10:15 AM Learned: "Q1 results exceeded target" │ │ │ │ │ 9:00 AM Updated: "Competitor Pricing" score │ │ │ │ │ │ │ │ │ │ [View All Activity →] │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ TOP TOPICS │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ marketing ████████████████████ 45 │ │ │ │ │ design ████████████████ 32 │ │ │ │ │ user-research ██████████████ 28 │ │ │ │ │ strategy █████████████ 25 │ │ │ │ │ competitive ████████ 18 │ │ │ │ │ │ │ │ │ │ [View Full Analytics →] │ │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Agent Header:** - Avatar: 64x64, rounded square - Name: 20px semibold - Status: Colored dot (green=active, gray=idle, red=error) + label + last active time - Description: 14px secondary text, 1-2 lines - Action buttons: "Open Vault" (primary), "View Skills" (secondary), "Settings" (icon button) **Stat Cards:** - Row of 4 cards, equal width - Each: large number (28px bold), label (12px muted), weekly delta (12px, green for positive) - Clickable: Each navigates to the relevant section **Attention Panel:** - Identical to Home attention panel but filtered to this agent - Severity-coded alerts with action buttons **Recent Activity:** - Compact timeline, 5 most recent events - Each: timestamp + action verb + entry title - "View All" link to agent-specific activity feed **Top Topics:** - Horizontal bar chart, top 5 topics by entry count - Each bar: tag name, visual bar, count number - "View Full Analytics" link ### Interactions - "Open Vault" is the primary CTA -- most common next action - Stat cards are clickable shortcuts - Activity events link to entry details --- ## 6.5 Vault / Memory Stream (`/agents/:slug/vault`) ### Purpose The primary view of an agent's private memory space. Shows all entries in chronological order with powerful filtering and search. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Agents > Alpha > Vault] [🔒Private]│ │ │ │ │ │ ┌─ OVERVIEW (collapsible) ──────────────────────┐ │ │ │ │ 247 memories · 52 knowledge · 12 skills │ │ │ │ │ Health: ●●●●○ Active: 198 Stale: 37 │ │ │ │ │ Last entry: 2 min ago [▲] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ FILTER BAR ─────────────────────────────────┐ │ │ │ │ [Search entries...] [Type ▼] [Tags ▼] │ │ │ │ │ [Status ▼] [Date Range ▼] [Sort: Newest ▼] │ │ │ │ │ [+ New Entry] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ MEMORY STREAM ──────────────────┐ ┌─ SIDE ─┐ │ │ │ │ │ │ PANEL │ │ │ │ │ ┌───────────────────────────────┐│ │ │ │ │ │ │ │[●] Memory Q2 Strategy ⋮ ││ │ (shows │ │ │ │ │ │ ││ │ entry │ │ │ │ │ │ Based on analysis of user ││ │ detail │ │ │ │ │ │ engagement data, the Q2 ││ │ when │ │ │ │ │ │ strategy should focus on... ││ │ an │ │ │ │ │ │ ││ │ entry │ │ │ │ │ │[topic:strategy][project:q2] ││ │ is │ │ │ │ │ │ Mar 18, 2:15 PM ││ │ click- │ │ │ │ │ └───────────────────────────────┘│ │ ed) │ │ │ │ │ │ │ │ │ │ │ │ ┌───────────────────────────────┐│ │ ────── │ │ │ │ │ │[●] Knowledge Brand Guide ⋮ ││ │ │ │ │ │ │ │ ││ │ Title │ │ │ │ │ │ The brand guidelines specify ││ │ Full │ │ │ │ │ │ that all customer-facing ││ │ content│ │ │ │ │ │ communications should use... ││ │ Tags │ │ │ │ │ │ ││ │ Meta │ │ │ │ │ │[topic:brand][type:guideline] ││ │ Links │ │ │ │ │ │ Mar 17, 3:20 PM ││ │ History│ │ │ │ │ └───────────────────────────────┘│ │ │ │ │ │ │ │ │[Edit] │ │ │ │ │ ┌───────────────────────────────┐│ │[Share] │ │ │ │ │ │[●] Skill Data Analysis ⋮ ││ │[Archve]│ │ │ │ │ │ ││ │ │ │ │ │ │ │ Step 1: Gather data sources ││ │ │ │ │ │ │ │ Step 2: Clean and normalize ││ │ │ │ │ │ │ │ Step 3: Run statistical... ││ │ │ │ │ │ │ │ ││ │ │ │ │ │ │ │[topic:analytics][type:workflow]││ │ │ │ │ │ │ │ Mar 16, 10:00 AM││ │ │ │ │ │ │ └───────────────────────────────┘│ │ │ │ │ │ │ │ │ │ │ │ │ │ [Loading more entries...] │ │ │ │ │ │ └───────────────────────────────────┘ └────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Privacy Indicator:** - Position: Top-right of content header - Display: Shield icon + "Private" text - Background tint: Slightly warmer/darker than standard background - Purpose: Constant reminder that this is a private space **Overview Panel:** - Collapsible (toggle with ▲/▼) - Content: Entry counts by type, health score, active/stale/archived breakdown, last entry timestamp - Collapsed: Shows only "247 entries · Health: ●●●●○" in a single line - Default: Expanded on first visit, remembers user preference **Filter Bar:** - Persistent above the stream (sticky on scroll) - Search input: Searches entry titles and content. Debounced (300ms). Shows "X results" count. - Type dropdown: Checkboxes for Memory, Knowledge, Skill, Note. Multi-select. - Tags dropdown: Searchable tag list grouped by prefix. Multi-select. - Status dropdown: Active (default), Stale, Archived, All. - Date Range: Preset options + custom picker. - Sort dropdown: Newest (default), Oldest, Most Important, Most Linked. - "New Entry" button: Opens inline creation form at top of stream. **Memory Stream:** - Width: 60-70% of content area (side panel takes the rest) - Entry Cards: See Component Library (Section 8.1) - Infinite scroll with virtualized rendering - New entries animate in from the top (slide down, 200ms) - Click on a card: Opens side panel with entry detail **Side Panel:** - Width: 30-40% of content area - Opens on entry card click (slide from right, 200ms) - Shows: Full entry detail (title, content, metadata, tags, links, provenance, history) - Actions: Edit, Share to Commons, Archive, Delete - Close: X button or click another entry (panel updates) or Escape key - Default (no entry selected): "Select an entry to view details" ### Interactions - **Search**: Typing in the search input filters the stream in real-time - **Filter**: Selecting any filter option immediately updates the stream - **Active filters**: Shown as removable pills below the filter bar - **Entry card click**: Opens/updates side panel - **Entry card hover**: Subtle elevation change - **Entry card menu (⋮)**: Quick actions (Edit, Share, Archive, Delete) - **Keyboard navigation**: Up/Down arrows move between entries, Enter opens detail, Escape closes panel - **N key**: Opens new entry form - **Cmd+K**: Opens command palette, scoped to this Vault ### States - **Loading**: 5 skeleton entry cards + skeleton overview panel - **Empty vault**: "This vault is empty. [Agent Name] hasn't stored any entries yet. Entries will appear here as [Agent Name] learns and works." - **Filtered empty**: "No entries match your filters. [Clear filters →]" - **Error**: "Unable to load entries. [Retry →]" with last successful data shown if available --- ## 6.6 Notebook Grid (`/agents/:slug/notebooks`) ### Purpose Shows all notebooks within an agent's Vault. Notebooks are organizational containers for grouping related entries. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Agents > Alpha > Notebooks] │ │ │ │ │ │ NOTEBOOKS [+ New Notebook]│ │ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ 📌 Skills │ │ Marketing │ │ │ │ │ │ │ │ │ │ │ │ 12 entries │ │ 45 entries │ │ │ │ │ Last: 2 days ago │ │ Last: 2 hours ago│ │ │ │ │ │ │ │ │ │ │ │ [Auto-generated] │ │ topic:marketing │ │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ User Research │ │ Design │ │ │ │ │ │ │ │ │ │ │ │ 28 entries │ │ 32 entries │ │ │ │ │ Last: 1 day ago │ │ Last: 3 hours ago│ │ │ │ │ │ │ │ │ │ │ │ topic:user-res. │ │ topic:design │ │ │ │ └─────────────────┘ └─────────────────┘ │ │ │ │ │ │ ┌─────────────────┐ │ │ │ │ Unorganized │ │ │ │ │ │ │ │ │ │ 130 entries │ │ │ │ │ Entries without │ │ │ │ │ a notebook │ │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Notebook Card:** - Size: 240px wide, 140px tall - Content: Name (bold), entry count, last activity, primary tag (if applicable) - Special: "Skills" notebook is pinned (📌 indicator) and auto-generated - Special: "Unorganized" notebook is auto-generated, shows entries with no notebook assignment - Hover: Elevation change, subtle border accent - Click: Navigates to Notebook Detail **Create Notebook:** - Button: "+ New Notebook" in header - Flow: Inline modal with name, description (optional), and initial tag filter (optional) - Tags can auto-populate a notebook: "Show all entries tagged topic:marketing" ### Interactions - Click card: Navigate to Notebook Detail - Right-click card: Context menu (Rename, Archive, Delete) - Drag entry from stream to notebook card: Assigns entry to notebook (if both views are visible) --- ## 6.7 Notebook Detail (`/agents/:slug/notebooks/:id`) ### Purpose Shows all entries within a specific notebook. Similar to the Memory Stream but scoped to one notebook. ### Layout Identical to the Memory Stream (Section 6.5) with these differences: - Breadcrumb: "Agents > Alpha > Notebooks > Marketing" - Overview panel: Shows notebook description and entry count (no health metrics) - Filter bar: Same filters, but pre-scoped to this notebook - Header actions: "Notebook Settings" (rename, archive, delete) --- ## 6.8 Entry Detail (`/entries/:id`) ### Purpose Full-page view of a single entry with all content, metadata, links, and history. Used when the side panel is insufficient (complex entries, editing, sharing). ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Agents > Alpha > Vault > Entry Title]│ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ [Memory badge ●] │ │ │ │ │ Q2 Strategy Insights │ │ │ │ │ │ │ │ │ │ Importance: ●●●○○ Status: Active │ │ │ │ │ │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ CONTENT ────────────────────────────────────┐ │ │ │ │ │ │ │ │ │ Based on analysis of user engagement data │ │ │ │ │ from Q1 2026, the Q2 strategy should focus │ │ │ │ │ on three key areas: │ │ │ │ │ │ │ │ │ │ 1. **Retention**: User churn increased 12% │ │ │ │ │ in Q1. Implement personalized follow-up │ │ │ │ │ campaigns targeting at-risk segments. │ │ │ │ │ │ │ │ │ │ 2. **Expansion**: Cross-sell opportunities │ │ │ │ │ identified in enterprise segment. Focus │ │ │ │ │ on product education. │ │ │ │ │ │ │ │ │ │ 3. **Acquisition**: Paid channels showing │ │ │ │ │ diminishing returns. Shift budget to │ │ │ │ │ organic content strategy. │ │ │ │ │ │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ STRUCTURED METADATA ────────────────────────┐ │ │ │ │ Context: Analyzing Q1 performance reports │ │ │ │ │ Observation: Three strategic areas identified │ │ │ │ │ Inference: Q2 should pivot from acquisition │ │ │ │ │ to retention-focused strategy │ │ │ │ │ Confidence: High (based on quantitative data)│ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ TAGS ───────────────────────────────────────┐ │ │ │ │ [topic:strategy] [project:q2] [source:report]│ │ │ │ │ [confidence:high] [+ Add] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ RELATED ENTRIES ─────────────────────────────┐ │ │ │ │ → Q1 Performance Report (knowledge) │ │ │ │ │ → User Churn Analysis (memory) │ │ │ │ │ → Content Strategy Template (skill) │ │ │ │ │ [+ Link] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ PROVENANCE ─────────────────────────────────┐ │ │ │ │ Source: Q1 performance report analysis │ │ │ │ │ Created: March 18, 2026 at 2:15 PM │ │ │ │ │ Updated: March 18, 2026 at 2:15 PM │ │ │ │ │ Author: Agent Alpha │ │ │ │ │ Vault: Agent Alpha's Vault │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ HISTORY ────────────────────────────────────┐ │ │ │ │ v1 · March 18, 2:15 PM · Agent Alpha │ │ │ │ │ Created entry │ │ │ │ │ [View Diff] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ ACTIONS ────────────────────────────────────┐ │ │ │ │ [Edit] [Share to Commons] [Archive] [Delete] │ │ │ │ └───────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Entry Header:** - Type badge: Color-coded circle + label (Memory, Knowledge, Skill, Note) - Title: 20px semibold - Importance: 5-dot scale, clickable to edit (owner only) - Status: Badge (Active=green, Stale=amber, Archived=gray) **Content Section:** - Rich text rendering: Markdown support (bold, italic, lists, code blocks, links) - Maximum width: 720px for readability - Edit mode: Toggles to a rich text editor in place **Structured Metadata:** - Key-value pairs displayed in a subtle card - Only shown if the entry has structured metadata fields - Collapsible if more than 4 fields **Tags Section:** - Tags displayed as color-coded pills - "+ Add" button to add new tags - Click X on a tag to remove (with undo) **Related Entries:** - List of linked entries with type badge and title - Click to navigate to the linked entry - "+ Link" button to add a new link (opens a search modal to find entries) **Provenance Section:** - Source, creation date, last update, author, location - Non-editable (system-generated metadata) **History Section:** - Version timeline, newest first - Each version: version number, timestamp, actor, summary of changes - "View Diff" button to see what changed between versions **Actions Bar:** - Fixed at the bottom or floating - Edit: Switches to edit mode - Share to Commons: Opens the privacy airlock flow - Archive: Moves to archived state (with confirmation) - Delete: Soft delete (with confirmation) ### Interactions - **Edit mode**: Click "Edit" to toggle. Content becomes editable. Title becomes an input. Tags become editable pills. "Save" and "Cancel" buttons appear. - **Share to Commons**: Opens a modal with: Commons selector, content preview (editable for redaction), tag mapping, and "Share" confirmation button. - **Archive**: Confirmation dialog: "Archive this entry? It will be hidden from default views but can be restored." - **Delete**: Confirmation dialog: "Delete this entry? It will be moved to trash and permanently deleted after 30 days." --- ## 6.9 Skills Page (`/agents/:slug/skills`) ### Purpose Dedicated view for procedural memories (skills). Shows the agent's learned workflows, templates, and techniques in a format optimized for understanding capabilities. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Agents > Alpha > Skills] │ │ │ │ │ │ SKILLS (12) [+ New Skill] │ │ │ │ │ │ Agent Alpha has learned 12 skills. │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [●] Workflow │ │ │ │ │ Data Analysis Pipeline │ │ │ │ │ │ │ │ │ │ Step 1: Gather data sources │ │ │ │ │ Step 2: Clean and normalize data │ │ │ │ │ Step 3: Run statistical analysis │ │ │ │ │ Step 4: Generate visualizations │ │ │ │ │ Step 5: Summarize findings │ │ │ │ │ │ │ │ │ │ Used: 15 times | Last used: 1 day ago │ │ │ │ │ [topic:analytics] [type:workflow] │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [●] Template │ │ │ │ │ Marketing Report Format │ │ │ │ │ │ │ │ │ │ 1. Executive Summary │ │ │ │ │ 2. Key Metrics │ │ │ │ │ 3. Analysis │ │ │ │ │ 4. Recommendations │ │ │ │ │ │ │ │ │ │ Used: 8 times | Last used: 3 days ago │ │ │ │ │ [topic:marketing] [type:template] │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [●] Technique │ │ │ │ │ Sentiment Analysis │ │ │ │ │ │ │ │ │ │ Approach for analyzing customer feedback: │ │ │ │ │ - Categorize by topic │ │ │ │ │ - Score sentiment (-1 to 1) │ │ │ │ │ - Identify trending themes │ │ │ │ │ │ │ │ │ │ Used: 22 times | Last used: today │ │ │ │ │ [topic:analytics] [type:technique] │ │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Skill Cards:** - Wider than entry cards (full width, not side-by-side) - Show: Subtype badge (Workflow/Template/Technique), title, full content preview (more text visible than stream cards), usage stats, tags - Usage stats: "Used X times" and "Last used: Y ago" -- unique to skills - Click: Opens full Entry Detail page ### States - **Empty**: "No skills learned yet. Skills will appear here as [Agent Name] develops workflows and techniques." --- ## 6.10 Agent Analytics (`/agents/:slug/analytics`) ### Purpose Detailed metrics and visualizations about an agent's memory and knowledge base. For owners who want to deeply understand their agent's knowledge landscape. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Agents > Alpha > Analytics] │ │ │ │ │ │ ANALYTICS [Period: 30 days ▼]│ │ │ │ │ │ ┌────────────────────┐ ┌────────────────────────┐ │ │ │ │ ENTRY COMPOSITION │ │ ACTIVITY OVER TIME │ │ │ │ │ │ │ │ │ │ │ │ [Donut chart] │ │ [Line chart] │ │ │ │ │ Memory: 247 (63%) │ │ Entries created per day │ │ │ │ │ Knowl.: 52 (22%) │ │ over selected period │ │ │ │ │ Skill: 12 (5%) │ │ │ │ │ │ │ Note: 37 (10%) │ │ │ │ │ │ └────────────────────┘ └────────────────────────┘ │ │ │ │ │ │ ┌────────────────────┐ ┌────────────────────────┐ │ │ │ │ MEMORY HEALTH │ │ IMPORTANCE DISTRIBUTION │ │ │ │ │ │ │ │ │ │ │ │ [Stacked bar] │ │ [Histogram] │ │ │ │ │ Active: 198 (80%) │ │ 0.0-0.2: ████ 35 │ │ │ │ │ Stale: 37 (15%) │ │ 0.2-0.4: ██████ 58 │ │ │ │ │ Archiv: 12 (5%) │ │ 0.4-0.6: ████████ 82 │ │ │ │ │ │ │ 0.6-0.8: ██████ 55 │ │ │ │ │ │ │ 0.8-1.0: ████ 35 │ │ │ │ └────────────────────┘ └────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ TOPIC DISTRIBUTION │ │ │ │ │ │ │ │ │ │ marketing ████████████████████████ 45 │ │ │ │ │ design ████████████████████ 32 │ │ │ │ │ user-research ██████████████████ 28 │ │ │ │ │ strategy ████████████████ 25 │ │ │ │ │ competitive ████████████ 18 │ │ │ │ │ pricing ████████ 14 │ │ │ │ │ content ██████ 11 │ │ │ │ │ analytics ████ 8 │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ TAG CLOUD │ │ │ │ │ │ │ │ │ │ marketing strategy design user-research │ │ │ │ │ competitive pricing content analytics │ │ │ │ │ brand q2 retention engagement │ │ │ │ │ churn acquisition enterprise │ │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Period Selector:** - Dropdown: "7 days", "30 days" (default), "90 days", "All time" - Changing period refreshes all charts **Charts:** - Entry Composition: Donut chart with type breakdown - Activity Over Time: Line chart showing daily entry creation - Memory Health: Stacked horizontal bar (active/stale/archived) - Importance Distribution: Histogram with 5 buckets - Topic Distribution: Horizontal bar chart, sorted by count - Tag Cloud: Weighted by frequency, clickable to filter All charts: hover for tooltips with exact values, click to drill down (navigate to filtered stream). --- ## 6.11 Agent Settings (`/agents/:slug/settings`) ### Purpose Configuration page for an individual agent. Covers identity, privacy, memory policies, and administrative actions. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Agents > Alpha > Settings] │ │ │ │ │ │ AGENT SETTINGS │ │ │ │ │ │ ┌─ IDENTITY ───────────────────────────────────┐ │ │ │ │ │ │ │ │ │ Avatar: [Upload] Name: [Agent Alpha ] │ │ │ │ │ │ │ │ │ │ Description: │ │ │ │ │ [Marketing analysis and strategy agent ] │ │ │ │ │ │ │ │ │ │ Slug: agent-alpha (read-only) │ │ │ │ │ Registered: January 15, 2026 │ │ │ │ │ [Save] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ PRIVACY & ACCESS ───────────────────────────┐ │ │ │ │ │ │ │ │ │ Owner Oversight: ✅ Enabled (always on) │ │ │ │ │ │ │ │ │ │ DELEGATED ACCESS GRANTS │ │ │ │ │ ┌───────────────────────────────────────────┐│ │ │ │ │ │ Agent Beta · Read-only ││ │ │ │ │ │ Scope: tag:project:alpha ││ │ │ │ │ │ Expires: April 15, 2026 ││ │ │ │ │ │ [Revoke] ││ │ │ │ │ └───────────────────────────────────────────┘│ │ │ │ │ [+ Grant Access] │ │ │ │ │ │ │ │ │ │ SHARING POLICIES │ │ │ │ │ Auto-share to Commons: [Off ▼] │ │ │ │ │ Require review: [On ▼] │ │ │ │ │ Shareable types: ☑ Knowledge ☐ Memory │ │ │ │ │ ☐ Skill ☑ Note │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ MEMORY POLICIES ────────────────────────────┐ │ │ │ │ │ │ │ │ │ Auto-archive inactive entries after: │ │ │ │ │ [90 days ▼] │ │ │ │ │ │ │ │ │ │ Delete archived entries after: │ │ │ │ │ [1 year ▼] │ │ │ │ │ │ │ │ │ │ Importance threshold for retention: │ │ │ │ │ [0.3 ──●────── 1.0] │ │ │ │ │ Entries below 0.3 importance are eligible │ │ │ │ │ for auto-archival. │ │ │ │ │ │ │ │ │ │ Or describe your policy in plain language: │ │ │ │ │ ┌───────────────────────────────────────────┐│ │ │ │ │ │ Keep memories about user preferences ││ │ │ │ │ │ forever. Archive task-related memories ││ │ │ │ │ │ after 2 weeks. Never share personal info. ││ │ │ │ │ └───────────────────────────────────────────┘│ │ │ │ │ [Apply] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ DANGER ZONE ────────────────────────────────┐ │ │ │ │ │ │ │ │ │ [Export Vault Data] Download all entries as │ │ │ │ │ JSON. │ │ │ │ │ │ │ │ │ │ [Deregister Agent] Remove this agent and │ │ │ │ │ make vault read-only. │ │ │ │ │ This cannot be undone. │ │ │ │ └───────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Identity Section:** - Editable fields: Avatar (upload), Name (text), Description (textarea) - Read-only fields: Slug, registration date - Save button (only active when changes exist) **Privacy & Access Section:** - Owner oversight: Always on, displayed as non-toggle information - Delegated Access Grants: List of active grants with details and revoke action - "+ Grant Access" opens a modal: Select agent, permission level, scope (tags), expiration date - Sharing Policies: Toggles and checkboxes for controlling what can be shared **Memory Policies Section:** - Auto-archive: Duration dropdown (30d, 60d, 90d, 180d, 1y, Never) - Auto-delete: Duration dropdown (6mo, 1y, 2y, Never) - Importance threshold: Slider (0.0 to 1.0) - Natural language policy: Textarea for plain language rules, "Apply" button to parse and set **Danger Zone:** - Red-bordered section at bottom - Export: Downloads all vault entries as JSON - Deregister: Requires typing the agent name to confirm. Makes vault read-only. --- ## 6.12 Commons Directory (`/commons`) ### Purpose Browse and search all accessible shared knowledge spaces. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ COMMONS [+ Create Commons]│ │ │ │ │ │ [Search commons...] [Filter: All ▼] │ │ │ │ │ │ MY COMMONS (3) │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ Marketing Knowledge Base │ │ │ │ │ "Shared marketing strategy and brand knowledge"│ │ │ │ │ │ │ │ │ │ 5 members · 87 entries · Active today │ │ │ │ │ Your role: Owner │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ Research Repository │ │ │ │ │ "User research findings and insights" │ │ │ │ │ │ │ │ │ │ 3 members · 42 entries · Active 2 days ago │ │ │ │ │ Your role: Contributor │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ Product Strategy │ │ │ │ │ "Cross-team product decisions and guidelines" │ │ │ │ │ │ │ │ │ │ 8 members · 156 entries · Active today │ │ │ │ │ Your role: Reader │ │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Commons Card:** - Full width, stacked layout - Content: Name (bold), description (secondary text), member count, entry count, last activity, user's role - Hover: Subtle background change - Click: Navigate to Commons Detail **Filter:** - "All" (default), "Owner", "Contributor", "Reader" **Create Commons Flow:** - Step 1: Name and purpose/description - Step 2: Invite initial members (search for agents/users, assign roles) - Step 3: Set policies (content types allowed, default role for new members) - Step 4: Confirmation ### States - **Empty**: "No commons yet. Create a shared space to start collaborating. [Create Commons →]" --- ## 6.13 Commons Detail (`/commons/:slug`) ### Purpose Landing page for a specific shared knowledge space. Shows overview, recent activity, and navigation to sub-pages. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Commons > Marketing Knowledge Base] │ │ │ [👥 Shared] │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ Marketing Knowledge Base │ │ │ │ │ "Shared marketing strategy and brand knowledge"│ │ │ │ │ 5 members · 87 entries · Owner: Sarah │ │ │ │ │ │ │ │ │ │ [Browse Entries] [View Notebooks] [Members] │ │ │ │ │ [Knowledge Graph] [Settings ⚙] │ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────┐ ┌────────────────────────┐ │ │ │ │ TOP CONTRIBUTORS │ │ COLLABORATION FEED │ │ │ │ │ │ │ │ │ │ │ │ Agent Alpha 45 │ │ 2:15 PM Agent Alpha │ │ │ │ │ ●●●●● reliable │ │ Contributed "Q2 Strategy │ │ │ │ │ │ │ Insights" │ │ │ │ │ Agent Beta 23 │ │ │ │ │ │ │ ●●●●○ reliable │ │ 1:30 PM Agent Beta │ │ │ │ │ │ │ Referenced "Brand │ │ │ │ │ Agent Gamma 12 │ │ Guidelines v2" │ │ │ │ │ ●●●○○ │ │ │ │ │ │ │ │ │ 11:00 AM ⚠ CONFLICT │ │ │ │ │ [All Contrib. →] │ │ Alpha vs Gamma on │ │ │ │ │ │ │ target audience │ │ │ │ │ │ │ [Resolve →] │ │ │ │ │ │ │ │ │ │ │ │ │ │ [View Full Feed →] │ │ │ │ └────────────────────┘ └────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ RECENT ENTRIES │ │ │ │ │ │ │ │ │ │ [Knowledge] Q2 Strategy Insights Agent Alpha │ │ │ │ │ [Knowledge] Brand Guidelines v2 Agent Beta │ │ │ │ │ [Knowledge] Competitor Analysis Agent Gamma │ │ │ │ │ [Knowledge] User Segments 2026 Agent Alpha │ │ │ │ │ [Knowledge] Content Calendar Agent Beta │ │ │ │ │ │ │ │ │ │ [Browse All Entries →] │ │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Commons Header:** - Shared indicator (👥 icon + "Shared" badge) in top-right - Name, description, member/entry count, owner - Navigation buttons to sub-pages **Top Contributors:** - Agent avatars with contribution count and reliability score - Reliability: 5-dot scale based on conflict history **Collaboration Feed:** - Compact timeline of recent events in this Commons - Highlights conflicts prominently with warning indicators - "Resolve" action buttons for active conflicts **Recent Entries:** - Last 5 entries with type badge, title, and contributing agent - Click to open entry detail --- ## 6.14 Commons Members (`/commons/:slug/members`) ### Purpose Manage membership, roles, and invitations for a shared knowledge space. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Commons > Marketing > Members] │ │ │ │ │ │ MEMBERS (5) [+ Invite Member]│ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [Avatar] Sarah │ │ │ │ │ Owner · Joined Jan 15, 2026 │ │ │ │ │ [Manage ▼]│ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [Agent] Agent Alpha │ │ │ │ │ Contributor · Joined Feb 1, 2026 │ │ │ │ │ 45 contributions │ │ │ │ │ [Change Role ▼] [Remove]│ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [Agent] Agent Beta │ │ │ │ │ Contributor · Joined Feb 1, 2026 │ │ │ │ │ 23 contributions │ │ │ │ │ [Change Role ▼] [Remove]│ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [Avatar] David │ │ │ │ │ Reader · Joined March 1, 2026 │ │ │ │ │ [Change Role ▼] [Remove]│ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [Agent] Agent Gamma │ │ │ │ │ Reader · Joined March 10, 2026 │ │ │ │ │ [Change Role ▼] [Remove]│ │ │ │ └────────────────────────────────────────────────┘ │ │ │ │ │ │ PENDING INVITATIONS (1) │ │ │ ┌────────────────────────────────────────────────┐ │ │ │ │ [Avatar] Sofia │ │ │ │ │ Invited as Contributor · Sent March 15, 2026 │ │ │ │ │ [Cancel] │ │ │ │ └────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Member Row:** - Avatar/agent icon, name, role badge, join date, contribution count (for agents) - Actions: Change Role dropdown (Owner, Contributor, Reader), Remove button - Owner row: "Manage" dropdown instead of Remove (transfer ownership, leave) **Invite Flow:** - Search for agents or users by name - Select role (Contributor or Reader) - Send invitation **Role Change:** - Dropdown that immediately applies the change - Confirmation for downgrading (Contributor -> Reader) --- ## 6.15 Onboarding Experience (Empty State for New Users) ### Purpose Guide new users through their first experience with KnowHub. Replaces the Home page when no agents are registered. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ │ │ │ WELCOME TO KNOWHUB │ │ KnowHub │ │ │ ───── │ KnowHub helps your AI agents remember, learn, │ │ HOME │ and share knowledge. │ │ │ │ │ (empty │ ┌────────────────────────────────────────────────┐│ │ sidebar) │ │ ││ │ │ │ STEP 1 OF 3 ││ │ │ │ Register Your First Agent ││ │ │ │ ││ │ │ │ Give your AI agent a home for its memories. ││ │ │ │ Once registered, your agent can start storing ││ │ │ │ and retrieving knowledge through the API. ││ │ │ │ ││ │ │ │ Agent Name: [My First Agent ] ││ │ │ │ Description: [ ] ││ │ │ │ ││ │ │ │ [Register Agent →]││ │ │ │ ││ │ │ └────────────────────────────────────────────────┘│ │ │ │ │ │ WHAT HAPPENS NEXT │ │ │ │ │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ │ │ 1. Vault │ │ 2. Learn │ │ 3. Share │ │ │ │ │ │ │ │ │ │ │ │ │ │ A private│ │ Your │ │ Create │ │ │ │ │ memory │ │ agent │ │ shared │ │ │ │ │ space is │ │ stores │ │ spaces │ │ │ │ │ created │ │ memories │ │ for team │ │ │ │ │ for your │ │ as it │ │ know- │ │ │ │ │ agent. │ │ works. │ │ ledge. │ │ │ │ └──────────┘ └──────────┘ └──────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Flow - **Step 1**: Register agent (name, description) - **Step 2**: Agent configuration (memory policies -- with sensible defaults pre-selected) - **Step 3**: API credentials (show API key, endpoint URL, example API call) - **Completion**: Redirect to the new agent's Profile page with a "Setup complete" banner --- ## 6.16 Search Page (`/search`) ### Purpose Full-featured search across all accessible content. Supports keyword, semantic, and structured queries. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ SEARCH │ │ │ │ │ │ ┌────────────────────────────────────────────────┐│ │ │ │ [Search: user preferences ] ││ │ │ │ Scope: [All ▼] Mode: [Keyword ▼] ││ │ │ └────────────────────────────────────────────────┘│ │ │ │ │ │ ┌──────────┐ ┌──────────────────────────────────┐│ │ │ │ FILTERS │ │ RESULTS (23 matches) ││ │ │ │ │ │ ││ │ │ │ Type │ │ ── Agent Alpha's Vault (12) ─── ││ │ │ │ ☑ Memory │ │ ││ │ │ │ ☑ Knowl. │ │ [●Memory] User prefers dark mode ││ │ │ │ ☐ Skill │ │ Learned Mar 15 · topic:preferences││ │ │ │ ☐ Note │ │ "...mentioned they always use ││ │ │ │ │ │ dark mode across all apps..." ││ │ │ │ Agent │ │ ││ │ │ │ ☑ Alpha │ │ [●Knowledge] UI Style Guide ││ │ │ │ ☑ Beta │ │ Stored Mar 10 · topic:design ││ │ │ │ ☐ Gamma │ │ "...default theme should respect ││ │ │ │ │ │ user preferences for light/dark.."││ │ │ │ Tags │ │ ││ │ │ │ [Select] │ │ ── Marketing Commons (5) ────── ││ │ │ │ │ │ ││ │ │ │ Date │ │ [●Knowledge] Brand Guidelines v2 ││ │ │ │ From [__]│ │ Stored Feb 28 · topic:brand ││ │ │ │ To [__]│ │ by Agent Beta ││ │ │ │ │ │ "...color preferences should align ││ │ │ │ Import. │ │ with user accessibility needs..." ││ │ │ │ Min [0.0]│ │ ││ │ │ │ Max [1.0]│ │ ── Agent Beta's Vault (6) ───── ││ │ │ │ │ │ ││ │ │ │ Sort │ │ [●Memory] Sarah prefers concise ││ │ │ │ ◉ Relev. │ │ Learned Mar 12 · topic:preferences││ │ │ │ ○ Newest │ │ "...in conversation, Sarah asked ││ │ │ │ ○ Oldest │ │ for shorter, more direct resp.." ││ │ │ │ ○ Import.│ │ ││ │ │ │ │ │ [Load more results...] ││ │ │ └──────────┘ └──────────────────────────────────┘│ └─────────────────────────────────────────────────────────────────┘ ``` ### Key Components **Search Input:** - Large input field (16px font) - Scope dropdown: "All" (default), specific agent vault, specific commons - Mode dropdown: "Keyword" (default), "Semantic" (meaning-based), "Advanced" (structured query builder) **Filter Panel (left sidebar):** - Type: Checkboxes (Memory, Knowledge, Skill, Note) - Agent: Checkboxes for each owned agent - Tags: Searchable tag selector - Date: From/To date pickers - Importance: Min/Max sliders - Sort: Radio buttons (Relevance, Newest, Oldest, Importance) **Results Panel:** - Grouped by source (agent vaults and commons) - Each group: Header with source name and match count - Each result: Type badge, title (with highlighted match), date, tags, contributing agent (in commons), content snippet (2-3 lines with highlighted matches) - "Load more" pagination within each group **Advanced Query Builder:** - Text input with syntax highlighting for structured queries - Examples shown below: `type:memory topic:marketing after:2026-01 importance:>0.5` - Auto-complete for field names and tag values ### Interactions - Typing in search input: Debounced (300ms), results update live - Changing any filter: Immediately updates results - Clicking a result: Opens entry detail in a new page (not side panel, since search needs the full width) - "Clear all filters" link when filters are active ### States - **Initial**: "Search across all your agents' memories and shared knowledge." - **Loading**: Skeleton results (3 groups with 2 results each) - **No results**: "No results for '[query]'. Try different keywords or adjust your filters." - **Error**: "Search is temporarily unavailable. [Retry →]" --- ## 6.17 Command Palette ### Purpose Universal quick-access overlay for search, navigation, and actions. The fastest way to do anything in KnowHub. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ │ │ ┌──────────────────────────────────────────┐ │ │ │ Search or type a command... │ │ │ │ │ │ │ │ RECENT │ │ │ │ 🕐 user preferences (Alpha Vault) │ │ │ │ 🕐 marketing strategy (All) │ │ │ │ │ │ │ │ QUICK ACTIONS │ │ │ │ ➤ New Entry N │ │ │ │ ➤ New Notebook │ │ │ │ ➤ New Commons │ │ │ │ ➤ Register Agent │ │ │ │ │ │ │ │ NAVIGATE │ │ │ │ → Home │ │ │ │ → Agent Alpha │ │ │ │ → Agent Beta │ │ │ │ → Marketing Commons │ │ │ │ → Settings │ │ │ └──────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` **As user types:** ``` ┌──────────────────────────────────────────┐ │ user pref │ │ │ │ ENTRIES (12 matches) │ │ [●] User prefers dark mode │ │ Agent Alpha · Memory · Mar 15 │ │ [●] Sarah prefers concise responses │ │ Agent Beta · Memory · Mar 12 │ │ [●] UI Style Guide - User Preferences │ │ Agent Alpha · Knowledge · Mar 10 │ │ │ │ AGENTS │ │ (no matches) │ │ │ │ COMMONS │ │ (no matches) │ │ │ │ [View all results in Search →] │ └──────────────────────────────────────────┘ ``` ### Behavior - Opens with: Cmd+K (Mac) or Ctrl+K (Windows/Linux) - Closes with: Escape or clicking outside - Navigation: Arrow keys (up/down), Enter to select - Scope: Automatically scoped to current context (if in a Vault, searches that Vault first) - Results: Instant, grouped by type (Entries, Agents, Commons, Actions) - Natural language: "What did Alpha learn about marketing last week?" is translated to structured query - Width: 600px, centered horizontally, 20% from top --- ## 6.18 Privacy Airlock (Share to Commons Flow) ### Purpose The review step when promoting content from a private Vault to a shared Commons. Ensures conscious, informed sharing. ### Layout (Modal) ``` ┌─────────────────────────────────────────────────────────────────┐ │ │ │ ┌──────────────────────────────────────────────────────────┐ │ │ │ SHARE TO COMMONS [×] │ │ │ │ │ │ │ │ You are about to share this entry from Agent Alpha's │ │ │ │ private vault to a shared space. │ │ │ │ │ │ │ │ SELECT COMMONS │ │ │ │ [Marketing Knowledge Base ▼] │ │ │ │ │ │ │ │ ─── PREVIEW ────────────────────────────────────────── │ │ │ │ │ │ │ │ Title: [Q2 Strategy Insights ] │ │ │ │ │ │ │ │ Content: (editable) │ │ │ │ ┌──────────────────────────────────────────────────────┐│ │ │ │ │ Based on analysis of user engagement data from Q1 ││ │ │ │ │ 2026, the Q2 strategy should focus on three key ││ │ │ │ │ areas: ││ │ │ │ │ ││ │ │ │ │ 1. Retention: User churn increased 12%... ││ │ │ │ │ 2. Expansion: Cross-sell opportunities... ││ │ │ │ │ 3. Acquisition: Paid channels showing... ││ │ │ │ └──────────────────────────────────────────────────────┘│ │ │ │ │ │ │ │ Tags: │ │ │ │ [topic:strategy ×] [project:q2 ×] [+ Add tag] │ │ │ │ │ │ │ │ ⚠ This entry will be visible to all 5 members of │ │ │ │ Marketing Knowledge Base. │ │ │ │ │ │ │ │ ☐ Keep a link to the original in my vault │ │ │ │ │ │ │ │ [Cancel] [Share to Commons →] │ │ │ └──────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Behavior - **Editable content**: The user can modify the title, content, and tags before sharing. This is the "redaction" opportunity. - **Commons selector**: Dropdown of all commons where the user has Contributor or Owner role. - **Warning**: Clear statement of how many people will see this content. - **Link option**: Optionally maintains a connection between the vault original and the shared copy. - **Creates a copy**: The shared entry is a separate copy in the Commons, not a reference to the vault entry. - **Animation**: On successful share, the modal shows a brief animation of the entry "moving" from vault to commons space, then closes. --- ## 6.19 Conflict Resolution Page ### Purpose Resolve contradictory entries in a Commons. Shows both entries side-by-side with resolution options. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ [Breadcrumb: Commons > Marketing > Conflicts] │ │ │ │ │ │ RESOLVE CONFLICT │ │ │ │ │ │ Two entries contain contradictory information. │ │ │ Review both and choose a resolution. │ │ │ │ │ │ ┌──────────────────┐ ┌──────────────────────────┐│ │ │ │ ENTRY A │ │ ENTRY B ││ │ │ │ Agent Alpha │ │ Agent Gamma ││ │ │ │ March 18, 2026 │ │ March 15, 2026 ││ │ │ │ │ │ ││ │ │ │ "Target audience │ │ "Target audience is ││ │ │ │ is 25-34 year old │ │ 30-45 year old decision ││ │ │ │ professionals" │ │ makers" ││ │ │ │ │ │ ││ │ │ │ Source: User │ │ Source: Market research ││ │ │ │ interview analysis│ │ report ││ │ │ │ │ │ ││ │ │ │ Confidence: High │ │ Confidence: Medium ││ │ │ └──────────────────┘ └──────────────────────────┘│ │ │ │ │ │ RESOLUTION │ │ │ │ │ │ ○ Keep Entry A (Agent Alpha's version) │ │ │ Entry B will be archived with a note. │ │ │ │ │ │ ○ Keep Entry B (Agent Gamma's version) │ │ │ Entry A will be archived with a note. │ │ │ │ │ │ ○ Keep both (mark as context-dependent) │ │ │ Both entries remain, tagged as having multiple │ │ │ valid interpretations. │ │ │ │ │ │ ○ Merge into new entry │ │ │ Opens an editor with both contents combined. │ │ │ │ │ │ ○ Dismiss (not a real conflict) │ │ │ Removes the conflict flag. Both entries unchanged.│ │ │ │ │ │ Resolution note (optional): │ │ │ [ ] │ │ │ │ │ │ [Cancel] [Resolve →] │ └─────────────────────────────────────────────────────────────────┘ ``` ### Behavior - Side-by-side comparison with highlighted differences - Five resolution options, each with a clear description of consequences - Optional resolution note for audit trail - "Merge" option opens a rich text editor pre-populated with both entries' content - Resolution is logged in the Commons activity feed --- ## 6.20 Global Settings (`/settings`) ### Purpose Account-level settings for the user, covering identity, security, agent management, notifications, and integrations. ### Layout ``` ┌─────────────────────────────────────────────────────────────────┐ │ [Sidebar] │ SETTINGS │ │ │ │ │ │ [Account] [Security] [Agents] [Notifications] │ │ │ [Integrations] │ │ │ │ │ │ ── ACCOUNT TAB ── │ │ │ │ │ │ ┌─ PROFILE ────────────────────────────────────┐ │ │ │ │ Avatar: [Upload] │ │ │ │ │ Name: [Sarah Chen ] │ │ │ │ │ Email: [sarah@example.com ] │ │ │ │ │ [Save] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ AUTHENTICATION ──────────────────────────────┐ │ │ │ │ Current method: OAuth (Google) │ │ │ │ │ [Add another auth method] │ │ │ │ │ │ │ │ │ │ Active Sessions │ │ │ │ │ This device · Chrome · Active now │ │ │ │ │ iPhone · Safari · 2 hours ago [Revoke] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ── SECURITY TAB ── │ │ │ │ │ │ ┌─ DEFAULT PRIVACY ─────────────────────────────┐ │ │ │ │ New agent vaults: Private (cannot change) │ │ │ │ │ Default sharing policy: Require review │ │ │ │ │ Default shareable types: Knowledge only │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ AUDIT LOG ───────────────────────────────────┐ │ │ │ │ [Filterable, paginated audit trail of all │ │ │ │ │ security-relevant events: logins, access │ │ │ │ │ grant changes, sharing events, deletions] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ── AGENTS TAB ── │ │ │ │ │ │ ┌─ REGISTERED AGENTS ───────────────────────────┐ │ │ │ │ Agent Alpha · Active · Created Jan 15, 2026 │ │ │ │ │ Agent Beta · Active · Created Feb 1, 2026 │ │ │ │ │ Agent Gamma · Idle · Created Mar 10, 2026 │ │ │ │ │ │ │ │ │ │ [+ Register New Agent] │ │ │ │ └───────────────────────────────────────────────┘ │ │ │ │ │ │ ┌─ API KEYS ────────────────────────────────────┐ │ │ │ │ Agent Alpha: kh_alpha_****3f7a [Regenerate] │ │ │ │ │ Agent Beta: kh_beta_****9c2d [Regenerate] │ │ │ │ │ Agent Gamma: kh_gamma_****5e1b [Regenerate] │ │ │ │ └───────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` ### Tabs - **Account**: Profile (name, email, avatar), authentication methods, active sessions - **Security**: Default privacy settings, audit log - **Agents**: Registered agents list, register new, API keys - **Notifications**: Alert preferences (which alert types, email on/off), threshold configuration - **Integrations**: Connected services, webhook URLs --- # 7. Component Library ## 7.1 Entry Card The most commonly used component. Represents a single Entry in list/stream views. ### Variants **Standard (Stream View):** ``` ┌─────────────────────────────────────────────────────────┐ │ [●type] [Type Label] Entry Title [⋮] │ │ │ │ First two to three lines of content preview that give │ │ enough context to understand the entry without opening │ │ the full detail view... │ │ │ │ [tag:one] [tag:two] [tag:three] Mar 18, 2:15 │ └─────────────────────────────────────────────────────────┘ ``` - Width: Full width of stream container - Padding: 16px - Background: Surface color (`#161b22`) - Border: 1px `#30363d`, border-radius 8px - Hover: Background shifts to `#1c2128`, subtle box-shadow - Type dot: 8px circle, colored by type (amber/blue/green/gray) - Title: 16px semibold, primary text color - Content preview: 14px regular, secondary text color, max 3 lines with ellipsis - Tags: Tag pill components, 12px - Timestamp: 12px muted text, right-aligned - Menu (⋮): Appears on hover, dropdown with Edit, Share, Archive, Delete **Compact (Search Results):** ``` [●] Entry Title Agent Alpha · Mar 18 "...content snippet with **highlighted** matches..." [tag:one] [tag:two] ``` - Reduced padding (12px) - Single-line title + metadata - Snippet with search term highlighting (bold + background accent) **Mini (Related/Linked):** ``` → Entry Title (Type) ``` - Single line, inline format - Used in Related Entries sections and link displays - Click: navigates to entry detail ### States - Default, Hover (elevation), Selected (left border accent), Loading (skeleton), Archived (reduced opacity) ## 7.2 Agent Card Represents an agent in list/grid views. ### Variants **Grid (Fleet View):** ``` ┌─────────────────────┐ │ [Avatar 48x48] │ │ │ │ Agent Alpha │ │ ● Active │ │ │ │ 247 entries │ │ +14 this week │ │ │ │ Health: ●●●●○ │ │ │ │ ⚠ 5 stale │ │ │ │ [Open Vault →] │ └─────────────────────┘ ``` - Width: 280px, auto height - Padding: 20px - Background: Surface color - Border: 1px border, border-radius 12px - Avatar: Centered, 48x48, rounded square - Name: 16px semibold - Status: 12px with colored dot - Stats: 14px primary + 12px secondary (delta) - Health: 5 dots, filled = green, unfilled = gray/muted - Alert: 12px with severity icon, shown only if active - CTA: "Open Vault" appears on hover, ghost button style **Compact (Sidebar):** ``` [Avatar 24x24] Agent Alpha ● ``` - Single line, used in sidebar navigation - Hover: background highlight - Click: navigates to agent profile **Inline (Activity Feed):** ``` [Avatar 20x20] Agent Alpha ``` - Inline within text, used in activity events - Click: navigates to agent profile ## 7.3 Tag Pill Represents a tag on an entry. ``` [topic:marketing ×] ``` - Height: 24px (medium), 20px (small) - Padding: 4px 8px - Border-radius: 12px (fully rounded) - Background: Determined by prefix category (see color mapping below) - Text: 12px (small) or 14px (medium), white or high-contrast - Close button (×): Only shown in edit mode, 12px - Click: In stream views, filters by this tag. In edit mode, removes the tag. **Tag Color Mapping by Prefix:** | Prefix | Background | Text | |--------|-----------|------| | `type:` | `#30363d` | `#e6edf3` | | `topic:` | `#1f3a5f` | `#79c0ff` | | `project:` | `#2a1f3f` | `#d2a8ff` | | `source:` | `#1f3f2a` | `#7ee787` | | `status:` | `#3f2a1f` | `#ffa657` | | `priority:` | `#3f1f1f` | `#f97583` | | `confidence:` | `#1f3f3f` | `#56d4dd` | | (no prefix) | `#21262d` | `#8b949e` | ## 7.4 Privacy Badge Indicates whether the current context is private or shared. **Private:** ``` [🛡 Private] ``` - Background: `#1a1a2e` (dark navy tint) - Icon: Shield, `#8b949e` - Text: "Private", 12px, `#8b949e` - Position: Top-right of page header **Shared:** ``` [👥 Shared · 5 members] ``` - Background: `#0f3460` (deep blue tint) - Icon: Group/people, `#58a6ff` - Text: "Shared" + member count, 12px, `#58a6ff` - Position: Top-right of page header ## 7.5 Alert Card Displays attention items on dashboards and profile pages. ``` ┌─────────────────────────────────────────────────────┐ │ 🟡 Agent Alpha: 5 memories marked as stale [Review]│ │ Consider archiving or refreshing these entries. │ │ [×] │ └─────────────────────────────────────────────────────┘ ``` - Width: Full width of container - Padding: 12px 16px - Left border: 3px, colored by severity - Background: Surface color with very subtle severity tint - Severity icon: Colored circle (red=critical, amber=warning, blue=info, green=success) - Title: 14px semibold, primary text - Description: 12px, secondary text (optional, shown on expand) - Action button: Ghost button, right-aligned - Dismiss (×): Top-right, 12px, muted until hover **Severity Colors:** - Critical: `#f85149` (red) - Warning: `#d29922` (amber) - Info: `#58a6ff` (blue) - Success: `#3fb950` (green) ## 7.6 Activity Event A single event in an activity feed/timeline. ``` [Avatar 24x24] Agent Alpha stored "Q2 Strategy Insights" in Agent Alpha's Vault · 2:15 PM ``` - Layout: Avatar + inline text - Avatar: 24x24, left-aligned - Actor name: 14px semibold, clickable - Action verb: 14px regular (stored, learned, referenced, contributed, etc.) - Entry reference: 14px semibold, clickable, in accent color - Location: 14px regular - Timestamp: 12px muted, right or after location - Spacing: 12px between events ## 7.7 Sidebar Navigation The persistent left sidebar. ``` ┌──────────────────────┐ │ [KnowHub Logo] │ │ │ │ [🔍 Search ⌘K] │ │ │ │ ─── OVERVIEW ─── │ │ ● Home │ │ Activity │ │ │ │ ─── MY AGENTS ── │ │ ★ Agent Alpha │ │ ★ Agent Beta │ │ All Agents (3) │ │ │ │ ─── COMMONS ──── │ │ Marketing │ │ Research │ │ Product │ │ + Create │ │ │ │ ─── SYSTEM ───── │ │ Settings │ │ Help │ │ │ │ [User Avatar] Sarah │ │ [▲] │ └──────────────────────┘ ``` - Width: 240px (expanded), 64px (collapsed) - Background: `#0d1117` (base background) - Border-right: 1px `#21262d` - Logo: 24px height, top-left - Search: Full-width input or button (Cmd+K shortcut label) - Section headers: 11px uppercase, `#484f58`, 8px bottom margin - Navigation items: 14px, `#e6edf3` text, 8px vertical padding, full width - Active item: `#161b22` background, left accent border 2px `#58a6ff`, semibold text - Hover: `#161b22` background - Pinned agents: Star icon, shown individually - "All Agents" link: Shows total count - Create button: `+` icon, lighter weight - User avatar: Bottom of sidebar, 32x32, with name and expand menu **Collapse behavior:** - Toggle: Hamburger icon or collapse button at top - Collapsed: Shows only icons for each section - Hover on collapsed: Tooltip with label ## 7.8 Breadcrumb Shows the current location in the hierarchy. ``` Agents > Agent Alpha > Vault > Notebook: Marketing > Entry: Q2 Strategy ``` - Font: 12px, `#8b949e` - Separator: `>` in `#484f58` - Each segment: Clickable, hover underline - Last segment: `#e6edf3`, not clickable (current page) - Position: Top of main content area, 8px below header ## 7.9 Filter Bar Persistent filter controls above list/stream views. ``` ┌─────────────────────────────────────────────────────────────────┐ │ [🔍 Search entries...] [Type ▼] [Tags ▼] [Status ▼] [Date ▼] │ │ [Sort: Newest ▼] [+ New Entry] │ │ │ │ Active filters: [type:memory ×] [topic:marketing ×] [Clear all] │ └─────────────────────────────────────────────────────────────────┘ ``` - Position: Sticky (stays at top on scroll) - Background: Same as page background - Search input: 240px width, icon prefix - Dropdowns: Ghost button style, show current selection - Active filters: Row of removable tag pills below the bar (only shown when filters are active) - "Clear all" link: Removes all active filters - "New Entry" button: Primary CTA, right-aligned ## 7.10 Side Panel Slide-out panel for viewing entry details without leaving the stream. ``` ┌──────────────────┐ │ [× Close] │ │ │ │ [●Memory] │ │ Q2 Strategy │ │ Insights │ │ │ │ Importance: ●●●○○ │ │ Status: Active │ │ │ │ ─── Content ───── │ │ Based on analysis │ │ of user engagement │ │ data from Q1 2026, │ │ the Q2 strategy │ │ should focus on │ │ three key areas... │ │ │ │ ─── Tags ──────── │ │ [topic:strategy] │ │ [project:q2] │ │ │ │ ─── Provenance ── │ │ Created: Mar 18 │ │ By: Agent Alpha │ │ │ │ ─── Actions ───── │ │ [Edit] [Share] │ │ [Archive] [Delete] │ │ │ │ [Open full page →] │ └──────────────────┘ ``` - Width: 400px (30-40% of content area) - Animation: Slide from right, 200ms ease-out - Background: Surface elevated (`#1c2128`) - Border-left: 1px `#30363d` - Close: X button top-right, also closes on Escape - Content: Scrollable, full entry detail in condensed format - "Open full page" link: Navigates to Entry Detail page ## 7.11 Empty State Used when a list or view has no content to display. ``` ┌─────────────────────────────────────────────────────┐ │ │ │ [Contextual icon, 48x48, muted] │ │ │ │ Primary message (16px semibold) │ │ │ │ Secondary explanation (14px muted, │ │ 1-2 lines explaining what will appear │ │ here and when) │ │ │ │ [Primary Action Button] │ │ │ └─────────────────────────────────────────────────────┘ ``` - Centered in container - Icon: Line-style, muted color, 48x48 - Primary message: Clear, specific ("No entries yet" not "Nothing here") - Secondary: Explains what will populate this space - Action button: If there's a creation action relevant to this context - No illustrations or decorative elements (per design principle) ## 7.12 Toast Notification Transient feedback for actions and errors. ``` ┌─────────────────────────────────────────┐ │ ✓ Entry shared to Marketing Commons │ │ [Undo] [×] │ └─────────────────────────────────────────┘ ``` - Position: Bottom-center, 24px from bottom - Width: Auto (max 480px) - Background: Surface elevated with type-appropriate accent - Duration: 5 seconds (success), 8 seconds (error), persistent (action required) - Types: Success (green accent), Error (red accent), Info (blue accent), Warning (amber accent) - Actions: Optional "Undo" or "Retry" button, dismiss (×) - Stacking: Multiple toasts stack upward, max 3 visible ## 7.13 Skeleton Loader Placeholder shown during content loading. Matches the shape of the actual content. **Entry Card Skeleton:** ``` ┌─────────────────────────────────────────────────────┐ │ [○ ░░░░░░░] ░░░░░░░░░░░░░░░░░░░░░░░ │ │ │ │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │ │ │ │ [░░░░░] [░░░░░░░] ░░░░░░░░ │ └─────────────────────────────────────────────────────┘ ``` - Uses the same dimensions as the real component - Animated: Subtle shimmer effect (gradient moving left to right, 1.5s loop) - Color: `#21262d` base, `#30363d` shimmer highlight ## 7.14 Confirmation Dialog Used for destructive or consequential actions. ``` ┌────────────────────────────────────────┐ │ Archive this entry? │ │ │ │ This entry will be hidden from default │ │ views. You can restore it later from │ │ the Archive section. │ │ │ │ [Cancel] [Archive] │ └────────────────────────────────────────┘ ``` - Modal overlay with backdrop blur - Width: 400px, centered - Title: 16px semibold - Description: 14px secondary - Actions: Cancel (ghost) + Primary action (filled, colored by severity) - For destructive actions (delete): Primary button is red. May require typing confirmation ("Type 'DELETE' to confirm"). - Closes on: Escape, Cancel click, backdrop click --- # 8. Navigation System ## 8.1 Primary Navigation (Sidebar) The sidebar is the primary navigation mechanism. It is always visible (unless collapsed) and provides access to all top-level sections. **Structure:** 1. **Logo & Search**: KnowHub wordmark + Cmd+K search trigger 2. **Overview section**: Home, Activity 3. **My Agents section**: Pinned agents + "All Agents" link 4. **Commons section**: Listed commons + "Create" action 5. **System section**: Settings, Help 6. **User section**: Avatar, name, account menu **Behavior:** - Collapsible to icon-only mode (64px width) - Active item highlighted with background + left accent border - Sections are collapsible individually - Pinned agents: Users can pin/unpin from agent profile or sidebar right-click - Sidebar state (collapsed/expanded, sections open/closed) persists across sessions ## 8.2 Secondary Navigation (Breadcrumbs) Breadcrumbs appear at the top of every page below depth 1, showing the full path. **Format:** `Section > Entity > Feature > Item` **Examples:** - `Agents > Agent Alpha > Vault` - `Commons > Marketing > Notebooks > Brand Strategy` - `Agents > Agent Beta > Settings > Privacy` ## 8.3 Tertiary Navigation (Tabs) Some pages use tabs for sub-sections that don't warrant separate sidebar entries. **Used in:** - Activity Feed: All | My Agents | Commons - Settings: Account | Security | Agents | Notifications | Integrations - Agent Profile: internally navigated via action buttons, not tabs **Tab style:** Underline indicator, 14px semibold for active, 14px regular for inactive. ## 8.4 Command Palette (Cmd+K) The fastest navigation method for power users. See Section 6.17 for full specification. **Capabilities:** - Search entries across all accessible spaces - Navigate to any page (agents, commons, settings, etc.) - Execute quick actions (new entry, new notebook, new commons) - Natural language queries ("What did Alpha learn last week?") - Recent searches and frequently visited pages ## 8.5 Keyboard Shortcuts | Shortcut | Action | Context | |----------|--------|---------| | `Cmd+K` / `Ctrl+K` | Open Command Palette | Global | | `N` | New Entry | Any list view | | `S` | Focus search input | Any list view | | `Escape` | Close panel / modal / palette | Global | | `↑` / `↓` | Navigate list items | Any list view | | `Enter` | Open selected item | Any list view | | `Cmd+/` / `Ctrl+/` | Show keyboard shortcuts | Global | | `G then H` | Go to Home | Global | | `G then A` | Go to All Agents | Global | | `G then C` | Go to Commons Directory | Global | | `G then S` | Go to Settings | Global | ## 8.6 URL Structure All URLs are human-readable and bookmarkable. ``` / → Home/Dashboard /activity → Activity Feed /search?q=... → Search /agents → Agent List /agents/:slug → Agent Profile /agents/:slug/vault → Vault/Memory Stream /agents/:slug/notebooks → Notebook Grid /agents/:slug/notebooks/:id → Notebook Detail /agents/:slug/skills → Skills /agents/:slug/analytics → Analytics /agents/:slug/settings → Agent Settings /commons → Commons Directory /commons/:slug → Commons Detail /commons/:slug/entries → Commons Entry Stream /commons/:slug/notebooks → Commons Notebooks /commons/:slug/notebooks/:id → Commons Notebook Detail /commons/:slug/graph → Knowledge Graph /commons/:slug/members → Members /commons/:slug/settings → Commons Settings /entries/:id → Entry Detail (universal, redirects to context) /settings → Global Settings /settings/account → Account Settings /settings/security → Security Settings /settings/agents → Agent Management /settings/notifications → Notification Settings /settings/integrations → Integration Settings ``` --- # 9. Privacy & Permission Model ## 9.1 Core Privacy Axioms 1. **Everything is private by default.** No content is visible to anyone until sharing is explicitly configured. 2. **Owners always see their agents.** An agent's owner can always read the agent's Vault. This cannot be disabled. 3. **Sharing is explicit and conscious.** The privacy airlock ensures informed consent before sharing. 4. **No cross-agent access by default.** Agent A cannot see Agent B's Vault, even with the same owner. 5. **Audit everything.** All access and sharing events are logged. ## 9.2 Permission Matrix ### Vault Permissions | Actor | Relationship | Read | Create | Edit | Delete | Admin | |-------|-------------|------|--------|------|--------|-------| | Agent | Own Vault | Yes | Yes | Yes | Soft only | No | | Owner | Agent's Vault | Yes | Notes only | Notes + tags | With confirmation | Yes | | Other Agent (with grant) | Scoped | Scoped | No | No | No | No | | Other Agent (no grant) | None | No | No | No | No | No | | Other User | None | No | No | No | No | No | ### Commons Permissions | Role | Read | Create | Edit Own | Edit Others | Delete | Admin | |------|------|--------|----------|-------------|--------|-------| | Owner | Yes | Yes | Yes | Yes | Yes (hard) | Yes | | Contributor | Yes | Yes | Yes | No | Soft only | No | | Reader | Yes | No | No | No | No | No | ### Global Permissions | Action | Who Can Do It | |--------|--------------| | Register an agent | Account owner | | Create a Commons | Account owner | | Invite to Commons | Commons owner | | Grant cross-agent access | Agent's owner | | View audit log | Account owner | | Delete account | Account owner | ## 9.3 Delegated Access Grants When an owner wants Agent A to read Agent B's Vault (e.g., for coordinator patterns): **Grant Properties:** - **Grantee**: The agent receiving access (e.g., Agent A) - **Target**: The vault being accessed (e.g., Agent B's Vault) - **Permission**: Read-only (only read is supported for delegated access) - **Scope**: Optional tag-based filter (e.g., "only entries tagged project:alpha") - **Expiration**: Optional time limit (e.g., "expires April 15, 2026") - **Audit**: All access by the grantee is logged **UI Visibility:** - The grant appears in both agents' settings pages - The target agent's owner sees: "Agent A has read access to [scope]" - The grantee agent's owner sees: "Agent A can read Agent B's Vault [scope]" ## 9.4 Privacy Visual System The UI uses visual cues to constantly reinforce the privacy context: **Private Context (Vault):** - Header background: `#1a1a2e` (warm dark navy) - Privacy badge: Shield icon + "Private" - Subtle visual weight: Slightly heavier borders, more enclosed feeling - Entry creation: No sharing options visible **Shared Context (Commons):** - Header background: `#0f3460` (cool deep blue) - Privacy badge: Group icon + "Shared with N members" - Slightly more open feeling: Lighter borders, more spacious - Entry creation: Attribution shown ("Contributing as Agent Alpha") **Transition (Privacy Airlock):** - Modal overlay with clear warning text - Shows exactly who will see the shared content - Editable preview for redaction - Cannot be bypassed or auto-confirmed (except for entries that match an explicit auto-share policy) ## 9.5 Sharing Policies Per-agent configuration controlling automatic sharing behavior. | Policy | Options | Default | |--------|---------|---------| | Auto-share to Commons | On / Off | Off | | Require review before sharing | On / Off | On | | Shareable content types | Checkboxes: Knowledge, Memory, Skill, Note | Knowledge only | | Content sanitization | On / Off | Off | When auto-share is enabled and review is disabled, entries matching the shareable types are automatically copied to the configured Commons. A notification is sent to the owner for each auto-shared entry. --- # 10. API-to-UI Mapping ## 10.1 Concept Mapping Table | GitHub API Concept | KnowHub UI Concept | Implementation Notes | |---|---|---| | User | Agent | Each agent maps to a GitHub user. The agent slug is the username. | | Repository | Vault or Commons | Private repos = Vaults. Shared repos = Commons. Repo name follows convention: `vault-{agent-slug}` or `commons-{slug}`. | | Issue | Entry | Each entry is a GitHub issue. Issue number is the entry ID within its space. | | Issue title | Entry title | Direct mapping. | | Issue body | Entry content | Markdown content. Structured metadata stored as YAML front matter. | | Issue state (open) | Entry status: active | Open issues are active entries. | | Issue state (closed) | Entry status: archived | Closed issues are archived entries. | | Label | Tag | Labels map to tags. Prefix conventions (type:, topic:, etc.) are parsed by the UI layer. | | Milestone | Notebook | Each milestone represents a notebook. Milestone title = notebook name. | | Issue comment | Entry message / version | Comments track updates and discussion. First comment after creation = first update. | | Reaction | Importance signal | Reactions are aggregated into importance scores. Specific reaction types may have specific meanings. | | Repository collaborator | Commons member | Collaborator permissions map to roles: admin=Owner, push=Contributor, pull=Reader. | | Organization | (Account level) | Not directly exposed. Mapped to the user's account. | | Branch | (Hidden) | Not exposed in UI. Used internally for version tracking. | | Commit | (Hidden) | Not exposed in UI. Used internally. | | Pull Request | (Hidden) | Not exposed in UI. | | Fork | (Hidden) | Not exposed in UI. | | Git clone/push/pull | (Hidden) | Used internally for data sync. | | Search API | Search | GitHub search API powers KnowHub search. Query translation layer converts KnowHub queries to GitHub search syntax. | | GraphQL API | (Internal) | Used for efficient data fetching. Not exposed to end users. | ## 10.2 API Flow Mappings ### Create an Entry (Agent stores a memory) **KnowHub action:** Agent creates a new memory entry in its Vault. **API flow:** ``` POST /repos/{owner}/{vault-repo}/issues Headers: Authorization: Bearer {agent-token} Body: { "title": "User prefers dark mode", "body": "---\ntype: memory\nsubtype: semantic\nimportance: 0.7\nconfidence: high\ncontext: Conversation about UI preferences\n---\n\nDuring the conversation, the user explicitly stated they prefer dark mode in all applications. They mentioned it's easier on their eyes for extended use.", "labels": ["type:memory", "topic:preferences", "source:conversation", "status:active", "confidence:high"] } ``` **UI renders as:** - Type badge: Memory (amber) - Title: "User prefers dark mode" - Content: The markdown body (after YAML front matter is parsed as metadata) - Tags: topic:preferences, source:conversation, confidence:high - Status: Active - Importance: 0.7 (displayed as ●●●●○) ### Assign Entry to Notebook **KnowHub action:** Move an entry into a specific notebook. **API flow:** ``` PATCH /repos/{owner}/{vault-repo}/issues/{issue-number} Body: { "milestone": {notebook-milestone-number} } ``` ### Search Entries **KnowHub action:** User searches for "user preferences" across Agent Alpha's Vault. **API flow:** ``` GET /search/issues?q=user+preferences+repo:{owner}/{vault-repo}+state:open ``` For semantic search (if enabled): ``` POST /search/semantic Body: { "query": "user preferences", "repo": "{owner}/{vault-repo}", "limit": 20 } ``` ### Share Entry to Commons (Privacy Airlock) **KnowHub action:** User shares an entry from a Vault to a Commons. **API flow (two steps):** ``` # Step 1: Create the entry in the Commons repo POST /repos/{owner}/{commons-repo}/issues Body: { "title": "User prefers dark mode", "body": "---\ntype: knowledge\nsubtype: reference\nimportance: 0.7\nsource_agent: agent-alpha\nsource_entry: {original-issue-number}\n---\n\n[Redacted/edited content from the privacy airlock]", "labels": ["type:knowledge", "topic:preferences", "agent:alpha", "status:active"] } # Step 2 (optional): Link back from original POST /repos/{owner}/{vault-repo}/issues/{original-issue-number}/comments Body: { "body": "Shared to Commons: {commons-name} as entry #{new-issue-number}" } ``` ### Create a Commons **KnowHub action:** User creates a new shared knowledge space. **API flow:** ``` # Step 1: Create the repository POST /user/repos Body: { "name": "commons-marketing-knowledge-base", "description": "Shared marketing strategy and brand knowledge", "private": true } # Step 2: Add members PUT /repos/{owner}/commons-marketing-knowledge-base/collaborators/{agent-username} Body: { "permission": "push" // Contributor } ``` ### Get Activity Feed **KnowHub action:** Load the global activity feed. **API flow:** ``` # For each accessible repo (vault + commons), fetch recent events GET /repos/{owner}/{repo}/issues/events?per_page=10&sort=created&direction=desc # Aggregate and sort by timestamp across all repos # The UI service layer handles this aggregation ``` ### Manage Tags **KnowHub action:** Create a new tag for an entry. **API flow:** ``` # Create the label if it doesn't exist POST /repos/{owner}/{repo}/labels Body: { "name": "topic:new-topic", "color": "1f3a5f" } # Attach to the entry POST /repos/{owner}/{repo}/issues/{issue-number}/labels Body: { "labels": ["topic:new-topic"] } ``` ## 10.3 Service Layer Architecture The frontend communicates with the GitHub-compatible API through a **Service Layer** that handles all concept translation. ``` ┌─────────────────┐ │ KnowHub UI │ │ (React/Next.js)│ └────────┬────────┘ │ KnowHub domain objects │ (Vault, Entry, Notebook, Tag, etc.) ┌────────▼────────┐ │ Service Layer │ │ │ │ - VaultService │ │ - EntryService │ │ - NotebookService│ │ - TagService │ │ - CommonsService │ │ - SearchService │ │ - ActivityService│ │ - AuthService │ └────────┬────────┘ │ GitHub API objects │ (Repository, Issue, Milestone, Label, etc.) ┌────────▼────────┐ │ agent-git-service│ │ (GitHub API) │ └─────────────────┘ ``` **Service Layer Responsibilities:** 1. **Concept translation**: Converts between KnowHub domain objects and GitHub API objects. 2. **Query building**: Translates KnowHub search queries to GitHub search syntax. 3. **YAML front matter**: Parses and generates structured metadata from issue body YAML. 4. **Tag management**: Handles the prefix:value convention, auto-creates labels, parses label names. 5. **Aggregation**: Combines data from multiple repos (e.g., activity feed across all vaults and commons). 6. **Access control**: Filters API responses based on the current user's permissions. 7. **Caching**: Caches frequently accessed data (tag lists, agent profiles, notebook lists). 8. **Error translation**: Converts GitHub API errors to KnowHub-specific error messages (e.g., 404 on a repo becomes "Vault not found" not "Repository not found"). **Key Service Methods:** ```typescript // VaultService getVault(agentSlug: string): Promise getVaultStats(agentSlug: string): Promise getMemoryHealth(agentSlug: string): Promise // EntryService listEntries(spaceSlug: string, filters: EntryFilters): Promise getEntry(entryId: string): Promise createEntry(spaceSlug: string, data: CreateEntryData): Promise updateEntry(entryId: string, data: UpdateEntryData): Promise archiveEntry(entryId: string): Promise deleteEntry(entryId: string): Promise shareEntry(entryId: string, commonsSlug: string, data: ShareData): Promise // NotebookService listNotebooks(spaceSlug: string): Promise createNotebook(spaceSlug: string, data: CreateNotebookData): Promise assignEntry(entryId: string, notebookId: string): Promise // TagService listTags(spaceSlug: string): Promise createTag(spaceSlug: string, name: string): Promise addTagToEntry(entryId: string, tagName: string): Promise removeTagFromEntry(entryId: string, tagName: string): Promise // SearchService search(query: string, options: SearchOptions): Promise semanticSearch(query: string, options: SearchOptions): Promise // CommonsService listCommons(): Promise getCommons(slug: string): Promise createCommons(data: CreateCommonsData): Promise addMember(commonsSlug: string, memberSlug: string, role: Role): Promise removeMember(commonsSlug: string, memberSlug: string): Promise // ActivityService getGlobalActivity(filters: ActivityFilters): Promise getAgentActivity(agentSlug: string, filters: ActivityFilters): Promise getCommonsActivity(commonsSlug: string, filters: ActivityFilters): Promise ``` --- # 11. Data Models ## 11.1 Core Domain Objects ### Agent ```typescript interface Agent { id: string; slug: string; // Unique identifier, URL-safe name: string; // Display name description: string; // Brief description of the agent avatarUrl: string; // Avatar image URL status: 'active' | 'idle' | 'error' | 'deregistered'; lastActiveAt: Date; // Last API activity createdAt: Date; vaultSlug: string; // Associated vault identifier ownerId: string; // Owner user ID config: AgentConfig; } interface AgentConfig { memoryPolicies: MemoryPolicies; sharingPolicies: SharingPolicies; delegatedGrants: AccessGrant[]; } interface MemoryPolicies { autoArchiveAfterDays: number | null; // null = never deleteArchivedAfterDays: number | null; importanceThreshold: number; // 0.0 - 1.0 naturalLanguagePolicy: string | null; // Plain language rules } interface SharingPolicies { autoShare: boolean; requireReview: boolean; shareableTypes: EntryType[]; autoShareTargets: string[]; // Commons slugs } ``` ### Vault ```typescript interface Vault { slug: string; agentSlug: string; agentName: string; stats: VaultStats; } interface VaultStats { totalEntries: number; memoryCount: number; knowledgeCount: number; skillCount: number; noteCount: number; activeCount: number; staleCount: number; archivedCount: number; entriesThisWeek: number; healthScore: number; // 0.0 - 1.0 lastEntryAt: Date; } ``` ### Entry ```typescript interface Entry { id: string; spaceSlug: string; // Vault or Commons slug spaceType: 'vault' | 'commons'; title: string; content: string; // Markdown type: EntryType; subtype: EntrySubtype; status: 'active' | 'stale' | 'archived'; importance: number; // 0.0 - 1.0 confidence: 'high' | 'medium' | 'low' | null; tags: Tag[]; links: EntryLink[]; provenance: Provenance; structuredMetadata: Record | null; notebookId: string | null; createdAt: Date; updatedAt: Date; createdBy: string; // Agent or user slug version: number; } type EntryType = 'memory' | 'knowledge' | 'skill' | 'note'; type EntrySubtype = 'episodic' | 'semantic' | 'reference' | 'document' | 'guideline' | 'workflow' | 'template' | 'technique' | 'annotation' | 'instruction'; interface Provenance { source: string; // e.g., "conversation", "document", "observation" sourceId: string | null; // Reference to source entity context: string | null; // What was happening when this was created } interface EntryLink { targetEntryId: string; targetEntryTitle: string; targetEntryType: EntryType; relationship: string; // e.g., "related", "derived-from", "contradicts" } ``` ### Notebook ```typescript interface Notebook { id: string; spaceSlug: string; name: string; description: string; entryCount: number; isPinned: boolean; isAutoGenerated: boolean; // e.g., Skills notebook tagFilter: string | null; // Auto-populate based on tag createdAt: Date; updatedAt: Date; } ``` ### Tag ```typescript interface Tag { name: string; // Full name including prefix (e.g., "topic:marketing") prefix: string; // Parsed prefix (e.g., "topic") value: string; // Parsed value (e.g., "marketing") color: string; // Hex color derived from prefix entryCount: number; } ``` ### Commons ```typescript interface Commons { slug: string; name: string; description: string; purpose: string; memberCount: number; entryCount: number; members: CommonsMember[]; createdAt: Date; lastActivityAt: Date; ownerSlug: string; } interface CommonsMember { slug: string; name: string; type: 'agent' | 'user'; avatarUrl: string; role: 'owner' | 'contributor' | 'reader'; joinedAt: Date; contributionCount: number; } ``` ### Activity Event ```typescript interface ActivityEvent { id: string; type: ActivityType; actorSlug: string; actorName: string; actorType: 'agent' | 'user' | 'system'; actorAvatarUrl: string; action: string; // Human-readable action verb targetType: 'entry' | 'notebook' | 'commons' | 'agent'; targetId: string; targetTitle: string; spaceSlug: string; spaceName: string; spaceType: 'vault' | 'commons'; metadata: Record; timestamp: Date; } type ActivityType = 'entry_created' | 'entry_updated' | 'entry_archived' | 'entry_deleted' | 'entry_shared' | 'entry_retrieved' | 'notebook_created' | 'member_added' | 'member_removed' | 'conflict_detected' | 'conflict_resolved' | 'grant_created' | 'grant_revoked'; ``` ### Alert ```typescript interface Alert { id: string; severity: 'critical' | 'warning' | 'info' | 'success'; title: string; description: string; actionLabel: string; actionUrl: string; agentSlug: string | null; commonsSlug: string | null; createdAt: Date; dismissedAt: Date | null; } ``` --- # 12. Responsive Design ## 12.1 Breakpoints | Breakpoint | Width | Layout | |-----------|-------|--------| | Desktop (large) | >= 1440px | Full sidebar (240px) + main content with side panel | | Desktop (standard) | >= 1024px | Sidebar (240px) + main content, side panel overlaps | | Tablet | >= 768px | Collapsed sidebar (64px) + main content, no side panel | | Mobile | < 768px | Hidden sidebar (hamburger) + full-width main content | ## 12.2 Responsive Behavior **Sidebar:** - Desktop: Full expanded sidebar - Tablet: Collapsed to icons, expands on hover/click - Mobile: Hidden, accessible via hamburger menu **Memory Stream:** - Desktop: Stream (60%) + Side Panel (40%) - Tablet: Full-width stream, side panel as overlay - Mobile: Full-width stream, entry detail as new page **Agent Grid:** - Desktop: 3-4 cards per row - Tablet: 2 cards per row - Mobile: 1 card per row (full width) **Search:** - Desktop: Filter sidebar (25%) + results (75%) - Tablet: Filters in collapsible top bar + full-width results - Mobile: Filters in modal + full-width results **Dashboard:** - Desktop: 2-column layout - Tablet: 2-column, narrower cards - Mobile: Single column, stacked panels --- # 13. Accessibility ## 13.1 Standards KnowHub targets WCAG 2.1 AA compliance. ## 13.2 Key Requirements 1. **Color contrast**: All text meets 4.5:1 contrast ratio against its background (7:1 for small text). 2. **Keyboard navigation**: All interactive elements are focusable and operable via keyboard. Tab order follows visual order. Focus indicators are visible (2px outline, `#58a6ff`). 3. **Screen reader support**: All images have alt text. Interactive elements have aria-labels. Dynamic content updates use aria-live regions. Page structure uses semantic HTML (nav, main, aside, section, article). 4. **Color independence**: Color is never the only indicator of meaning. Entry type badges include text labels in addition to color dots. Alert severity includes icons in addition to color. 5. **Motion**: Animations respect `prefers-reduced-motion`. All transitions can be disabled. 6. **Text scaling**: Layout remains functional at 200% text zoom. 7. **Focus management**: Modals trap focus. Side panel opening moves focus to panel. Dialog closing returns focus to trigger element. ## 13.3 Aria Landmarks ```html