# KnowHub Product Design V2: Storage-Aware Redesign ## Memory & Knowledge Management Console for AI Agents **Version:** 2.0 **Date:** 2026-03-18 **Status:** Design Addendum to V1 Specification **Supersedes:** Sections of V1 related to Entry model, Vault structure, navigation, and terminology --- # Part I: Product Design Workshop V2 ## Participants | Expert | Background | Specialty | |--------|-----------|-----------| | **Steve Jobs** | Legendary product visionary | Simplicity, focus, saying no to 1000 things | | **原研哉 (Kenya Hara)** | Art director of MUJI, master of emptiness (空) | Restraint, whitespace, sensory design, inevitability over cleverness | | **Maya Chen** | Former Head of Product at Notion | Knowledge management UX, information architecture | | **Sofia Ramirez** | Former VP Product at Slack | Multi-user collaboration, team dynamics, permissions | | **Aisha Okafor** | Former Head of AI Products at Figma | Human-AI collaboration interfaces | --- ## Phase 1: Understand the Problem ### Round 1: Why the Unified "Entry" Model Is Wrong **Topic:** Analyze the original design's flaws — why treating everything as "Entries" is wrong when the underlying storage is fundamentally different (short-form memories vs long-form documents). **Steve Jobs:** Let me be blunt. The V1 design committed the classic mistake of designing from the data model up instead of from the user experience down. You took one storage mechanism — issues in a tracking system — and tried to cram four fundamentally different things into it. Memories, documents, skills, notes. That is like saying "a Post-It note and a novel are the same thing because they are both made of paper." They are not the same thing. A memory is a flash of experience. A knowledge document is a living reference. A skill is a reusable recipe. They deserve different containers, different interactions, different respect. **Kenya Hara:** I see the V1 design and I feel congestion. When everything is an "Entry," the user's mind has no resting place. There is no ma — no interval, no space between concepts that allows meaning to emerge. In Japanese architecture, a room's purpose is defined not by what is in it, but by the emptiness that gives it shape. The V1 design fills every container with the same formless substance and asks the user to sort it out through badges and filters. This is asking the user to do work that the design should do. Good design creates distinct spaces that communicate their purpose through their very nature. **Maya Chen:** Let me get specific about the technical reality we are designing against. An agent's vault is backed by a Git repository. That repo has two fundamentally different storage systems: First, there is the **Issue System**. Issues are short-form, metadata-rich, searchable, taggable. They have a status lifecycle: active, stale, archived. They support comments — threaded discussion beneath the main content. They are ideal for memories: "I learned the user prefers dark mode" with tags, importance scores, provenance metadata, and owner annotations as comments. Second, there is the **File System**. Files live in directories. They support versioning — every save creates a new version with a diff. They handle long-form content: documents, guides, templates. They handle binary content: PDFs, images, diagrams. They have edit history showing who changed what and when. They are ideal for knowledge documents and skill templates. The V1 design pretends these are the same. It stores a 50-page brand guideline as an "Entry" (an issue) the same way it stores "user prefers dark mode." That is architecturally dishonest. The issue body becomes an unwieldy blob of text. You lose directory organization. You lose meaningful version diffs. You lose binary file support. You lose everything that makes a file system valuable for documents. **Sofia Ramirez:** From a collaboration perspective, the difference matters even more. When I share a memory in a team space, I am sharing a discrete observation — "Agent Alpha learned X." The team reads it, maybe comments on it, done. But when I share a knowledge document — a brand style guide, a product specification, a training manual — the team needs to read it, reference specific sections, suggest edits, track revisions over time. These are fundamentally different collaboration patterns. The V1 design's uniform "Entry" model provides the same thin interaction for both. You cannot meaningfully collaborate on a 50-page document through an issue's comment thread. **Aisha Okafor:** And from the agent's perspective, the distinction is critical for retrieval quality. When an agent needs to recall what it learned about a user's preferences, it queries its memories — short, tagged, scored by importance. When an agent needs to follow a style guide, it reads a document — long-form, structured, with sections and headings. When an agent needs to execute a workflow, it loads a skill template — step-by-step, parameterized, reusable. The retrieval patterns, the context window implications, the way the agent uses each type — these are all different. A one-size-fits-all Entry model forces the agent to treat everything the same way, which degrades performance. ### Round 1 Conclusion: The unified "Entry" model is fundamentally flawed because: 1. It ignores the reality of two distinct storage systems (issues vs files) with different strengths. 2. It forces long-form documents into a short-form container, losing versioning, directory organization, and binary support. 3. It provides identical interaction patterns for fundamentally different collaboration needs. 4. It degrades agent retrieval by conflating different content types with different usage patterns. --- ### Round 2: How Non-Developers Think About Memory vs Documents vs Skills **Topic:** Find the right metaphors. How do non-technical users naturally think about these different content types? **Kenya Hara:** Before we reach for metaphors, let us observe how people naturally organize in the physical world. A person has memories in their mind — fleeting, associative, triggered by context. They have documents in their filing cabinet or on their shelf — persistent, organized, referenced deliberately. They have recipes, checklists, and instructions pinned to their wall or stored in a binder — action-oriented, step-by-step, used repeatedly. No one confuses these three things. They live in different places because they serve different purposes. Our design should honor this natural separation. **Steve Jobs:** The right metaphor is not a metaphor at all. It is the thing itself. When I think about what my AI agent remembers, I think "memories." When I think about the documents I have given my agent to reference, I think "library." When I think about the workflows my agent knows how to execute, I think "skills." These are not developer concepts. These are human concepts. Everyone understands what a memory is. Everyone understands what a library is. Everyone understands what a skill is. We do not need to invent clever terminology. We need to use the words people already use. **Maya Chen:** I agree with Steve, but let me push on the nuances. In my Notion days, we found that users think about documents very differently from notes. A note is quick, informal, possibly ephemeral. A document is considered, structured, meant to endure. In our case, memories are more like notes — quick captures of experience. Knowledge items are more like documents — curated, structured, authoritative. The word "library" works beautifully for knowledge because it implies: curation (not everything gets in), organization (by topic or category), permanence (a library preserves), and accessibility (anyone with access can browse and read). **Sofia Ramirez:** For the team context, these metaphors carry important social signals. "I am sharing a memory" feels personal and intimate — like telling a colleague what you observed. "I am adding to the library" feels institutional and authoritative — like contributing to a shared knowledge base. "I am sharing a skill" feels generous and pedagogical — like teaching someone your method. These emotional registers matter. They shape how people treat the content and how they decide what is worth sharing. **Aisha Okafor:** From the AI angle, I want to be careful about anthropomorphism while still being intuitive. "Memory" works for agents because everyone understands the concept of an AI "remembering" something. "Library" works because it is a place the agent "consults." "Skills" works because it describes what the agent "can do." The mental model is: my agent has a mind (memories), a reference shelf (library), and a toolkit (skills). Each serves a different purpose in how the agent thinks and acts. **Steve Jobs:** And here is the critical insight — each of these has a fundamentally different primary verb. You **recall** a memory. You **read** a document. You **use** a skill. The interaction flow follows the verb. Memories are searched and surfaced. Documents are browsed and read. Skills are triggered and executed. If our product honors these natural verbs, the interface will feel obvious. If we force everything through the same interaction, we fight human nature. **Kenya Hara:** There is a quieter distinction that matters. Memories are authored by the agent — they emerge from experience. Documents may be authored by anyone — uploaded by an owner, written collaboratively, imported from external sources. Skills may be authored by either — an agent learns a skill through practice, or an owner teaches a skill by writing a template. The authorship model differs, and this should be felt in the design without being loudly stated. ### Round 2 Conclusion: The natural mental model for non-developers is: - **Memories** = what the agent has experienced and learned (quick, personal, associative) - **Library** = reference documents the agent consults (curated, organized, authoritative) - **Skills** = workflows the agent can execute (action-oriented, reusable, step-by-step) - Primary verbs: recall, read, use - Authorship: memories are agent-authored; documents can be anyone-authored; skills can be either --- ### Round 3: The Simplicity Debate — How Few Concepts Can We Have? **Topic:** Jobs and Hara debate how to minimize concepts while respecting the different natures of these content types. **Steve Jobs:** Here is my position. Three sections inside a vault is already generous. I want to make sure each one earns its place. Memory Stream — yes, absolutely, this is the core of what makes KnowHub different from a file server. Library — yes, because agents need reference material and it must be browsable. Skills — this is where I hesitate. Can skills just be a special folder in the Library? A skill template is, after all, a document. Do we need a third section? **Kenya Hara:** I understand Steve's instinct to reduce, and I share it. But I would argue that three is itself a harmonious number. In Japanese aesthetics, we speak of jo-ha-kyu — beginning, break, rapid. Three elements create rhythm. Two feels incomplete; four feels cluttered. Memory, Library, Skills — this triad has an internal logic. Memory is the past (what happened). Library is the present (what is true). Skills are the future (what can be done). Past, present, future. That is not three arbitrary sections. That is a complete picture of an agent's capability. **Steve Jobs:** That is a beautiful argument. But beauty does not excuse unnecessary complexity. Let me test it differently. If I am a user checking on my agent, what are the three questions I ask? "What has my agent been learning?" — that is Memory. "What reference material does my agent have?" — that is Library. "What can my agent do?" — that is Skills. Three different questions, three different answers. Fine. I am convinced, but only if each section is genuinely different in look, feel, and interaction. If they blur together, we should have collapsed them. **Maya Chen:** Let me address a related simplification. In V1, we had "Notebooks" as an organizational concept within Vaults. With the new model, do we still need Notebooks? Memories are already organized by tags, time, and type. Knowledge documents are organized by folders in the library. Skills have their own section. I think Notebooks were a crutch for the old model's lack of differentiation. We can drop them entirely. **Steve Jobs:** Cut them. Notebooks were solving a problem we created by making everything the same type. Now that we have three distinct sections, each with its own natural organization, Notebooks are redundant. Fewer concepts, clearer model. **Kenya Hara:** I agree. But let me propose what replaces the organizational role of Notebooks. In the Memory Stream, organization comes from tags and time — the stream itself is the organizing principle, with filters as lenses. In the Library, organization comes from folders — a simple hierarchy that users already understand. In Skills, organization comes from categories — communication skills, research skills, writing skills. Each section has its own native organizing principle. We do not need to impose a foreign concept across all three. **Sofia Ramirez:** One concern: in the Commons (shared spaces), the three-section model still applies. A shared space has shared memories (team observations), shared documents (the team library), and shared skills (team playbooks). But in V1, a Commons was a flat collection of Entries. Now we need shared spaces that also have these three sections. Does that make the Commons too complex? **Steve Jobs:** A Commons should primarily be a shared library with shared skills. Memories are personal. Why would you share "my agent observed X" with a team? You share the knowledge that results from observations, not the observations themselves. I would make Commons primarily about Library and Skills, with a lightweight "Team Notes" section instead of a full memory stream. **Aisha Okafor:** I partially disagree. There are cases where sharing agent observations is valuable — "Agent Alpha noticed that customers are asking about feature Y more frequently this week." That is an observation (memory) that has team value. But I agree it should be secondary. The Commons should lead with Library and Skills, and have an optional Activity Log for shared observations. **Steve Jobs:** Fine. Commons has: Library (primary), Skills (secondary), and Activity Log (observations and updates). Three sections everywhere, but with different emphasis. The vault emphasizes Memory Stream. The Commons emphasizes Library. Consistent structure, different center of gravity. ### Round 3 Conclusion: - Three sections earn their place: Memory Stream, Library, Skills - Notebooks are eliminated — each section has its own native organization (tags/time, folders, categories) - Commons uses the same three-section structure but with different emphasis: Library-first, with Skills and Activity Log - The triad represents past (Memory), present (Library), future (Skills) --- ## Phase 2: Redesign the Product Model ### Round 4: New Core Concepts and Terminology **Topic:** Define what replaces the unified "Entry." Name everything. Build the new concept map. **Maya Chen:** Let me lay out the new concept map. At the top level, we still have **Vault** (private, per-agent) and **Commons** (shared, team space). But inside each, instead of a flat sea of Entries, we have three distinct sections: 1. **Memory Stream** — contains **Memories**. These are short-form observations, learnings, and experiences generated by the agent. Stored as issues under the hood, but users see a chronological feed of memories. 2. **Library** — contains **Documents**. These are long-form reference materials: guides, manuals, reports, policies. Stored as files in the repo, but users see an organized collection of documents they can browse, read, and edit. 3. **Skills** — contains **Playbooks**. These are reusable workflows, templates, and procedures. Also stored as files in the repo, but presented differently — as executable recipes with steps, parameters, and triggers. **Steve Jobs:** I want to challenge one term. "Playbooks" sounds like enterprise jargon. Real people say "how-to" or "recipe" or just "skill." When I teach someone to make pasta, I do not hand them a "playbook." I show them a recipe. Can we just call them Skills? "Agent Alpha has 12 skills." That is clear. Click in, you see the list of skills. Each skill has a name, a description, and steps. **Kenya Hara:** I prefer the simplicity of "Skill" as the item name. A skill is something you possess and can use. "My agent has a skill for writing product descriptions." "My agent has a skill for summarizing meeting notes." The word carries both the capability and the knowledge of how to execute it. There is no need for a separate container name. The section is "Skills." The items are "Skills." Simple. **Aisha Okafor:** Let me define the full terminology replacement. For the Memory Stream, the atomic unit is a **Memory**. Not an "Entry of type memory." Just a Memory. A memory has: content (what was learned), source (where it came from), importance (how relevant), status (active, fading, archived), and tags. Under the hood, it is an issue. But the user never sees the word "issue." For the Library, the atomic unit is a **Document**. A document has: title, content (rich text, potentially very long), folder location, edit history, and contributors. Under the hood, it is a file in the repo. But the user never sees "file" or "commit" or "repo." For Skills, the atomic unit is a **Skill**. A skill has: name, description, steps (ordered), parameters (inputs it needs), triggers (when to use it), and examples. Under the hood, it is also a file in the repo, likely in a dedicated `/skills/` directory. **Sofia Ramirez:** What about Notes? In V1, notes were owner annotations on entries. Do they survive the redesign? **Maya Chen:** Yes, but they change form. In the Memory Stream, notes become **Comments** on memories — an owner can comment on any memory to annotate, correct, or flag it. Under the hood, these are issue comments. In the Library, notes become **Annotations** on documents — margin notes, highlights, or suggestions. Under the hood, these could be stored as metadata or separate comment files. The unifying concept is: owners can annotate anything their agent has, using the annotation mechanism native to that section. **Steve Jobs:** Good. So the concept map is now: - **Vault** = an agent's private space (one per agent) - **Memory Stream** = feed of Memories (short-form, issue-backed) - **Library** = collection of Documents (long-form, file-backed) - **Skills** = collection of Skills (template files, file-backed) - **Commons** = shared team space - **Library** (primary) = shared documents - **Skills** = shared skills/playbooks - **Activity Log** = shared observations and updates - **Memory** = atomic unit of the Memory Stream (was: Entry of type memory) - **Document** = atomic unit of the Library (was: Entry of type knowledge) - **Skill** = atomic unit of Skills (was: Entry of type skill) - **Comment** = annotation on a Memory (was: Note / Message) - **Annotation** = note on a Document (new concept) Notebooks are gone. Tags remain for memories. Folders replace notebooks for documents. Categories organize skills. **Kenya Hara:** I want to add one more concept: **Drafts**. In the Library, when someone is working on a document but has not yet published it, it exists as a Draft. Under the hood, this is a branch. But the user sees: "This document is in draft. Only you can see it until you publish." Publish means merging the branch. But the user just clicks "Publish." The concept of drafts is universal and requires no technical knowledge. ### Round 4 Decision: **New Core Concepts:** | Concept | Definition | Replaces (V1) | Storage Reality | |---------|-----------|----------------|-----------------| | **Memory** | Short-form agent experience or learning | Entry (type: memory) | Issue | | **Document** | Long-form reference material | Entry (type: knowledge) | Repo file | | **Skill** | Reusable workflow or template | Entry (type: skill) | Repo file (in /skills/) | | **Comment** | Annotation on a memory | Note / Message | Issue comment | | **Annotation** | Note on a document | (new) | Comment file or metadata | | **Draft** | Unpublished document revision | (new) | Branch | | **Folder** | Document organization | Notebook | Directory in repo | | **Category** | Skill organization | Notebook | Directory in /skills/ | --- ### Round 5: Vault Structure — How Three Sections Coexist **Topic:** Design how Memory Stream, Library, and Skills Workbench coexist within a Vault. How does navigation work between them? **Steve Jobs:** The vault landing page should answer the owner's first question: "What is my agent up to?" I want a single overview that shows the pulse of all three sections without forcing the user to visit each one separately. Think of it like looking at a dashboard — at a glance, I see recent memories (latest 3-5), recently updated documents (latest 2-3), and the agent's skill count. Then I can drill into any section. **Maya Chen:** I would structure the Vault as a tabbed interface, not three separate pages hidden in the sidebar. When you click on an agent, you arrive at the Vault overview. Across the top, you have three tabs: **Memories**, **Library**, **Skills**. The overview page itself is a fourth implicit view — the landing page that shows highlights from all three. This keeps navigation flat. One click to get to any section. No nesting. **Kenya Hara:** Tabs can feel clinical if not handled with care. I would design the three sections as distinct visual territories within the same space. Imagine a room with three alcoves. The Memories alcove has a warm, flowing quality — amber tones, a timeline flowing downward, organic. The Library alcove has a calm, structured quality — cool blue tones, a grid of document cards, orderly. The Skills alcove has an active, ready quality — green tones, a list of capabilities with clear action indicators. The overview shows a vista of all three alcoves. Clicking any one enters that space fully. **Aisha Okafor:** Let me define the navigation flow precisely: ``` Agent Alpha ├── Overview (default landing) │ ├── Recent Memories (last 5, with "View all" link) │ ├── Recently Updated Documents (last 3, with "Browse library" link) │ ├── Skills Summary (count + most used, with "View all" link) │ └── Health & Stats (memory count, document count, stale alerts) │ ├── Memories (tab) │ ├── Stream View (chronological, default) │ ├── Filters (tags, importance, status, date range) │ ├── Search (within memories) │ └── Memory Detail (side panel or full page) │ ├── Content │ ├── Metadata (importance, status, source) │ ├── Tags │ ├── Linked Documents / Skills │ └── Comments (owner annotations) │ ├── Library (tab) │ ├── Browse View (folder tree + document grid) │ ├── Folder Navigation (breadcrumb-based) │ ├── Search (within library) │ └── Document Detail (full page, reader view) │ ├── Content (rich text, potentially very long) │ ├── Table of Contents (auto-generated from headings) │ ├── Edit History (timeline of saves) │ ├── Annotations │ └── Actions (Edit, Share, Download, View History) │ ├── Skills (tab) │ ├── Grid/List View (skill cards) │ ├── Categories (filtering by skill type) │ └── Skill Detail (full page) │ ├── Description │ ├── Steps / Instructions │ ├── Parameters (inputs needed) │ ├── Usage History (when the agent last used it) │ └── Actions (Edit, Share, Duplicate) │ └── Settings ├── Memory Policies (retention, importance thresholds) ├── Library Settings (default folder structure) ├── Privacy & Access └── Agent Profile ``` **Sofia Ramirez:** For the sidebar navigation, I propose we keep it agent-centric: ``` [Logo: KnowHub] [Global Search] -- OVERVIEW -- Home (Dashboard) Activity -- MY AGENTS -- All Agents * Agent Alpha (pinned) * Agent Beta (pinned) -- SHARED -- All Spaces * Marketing Library (pinned) * Q2 Project (pinned) + New Shared Space -- SYSTEM -- Settings ``` When you click on an agent, the main content area shows the vault with its tabbed sections. The sidebar does not expand into sub-items for each agent — that was the V1 approach and it scales poorly. Instead, the content area handles section navigation through tabs. **Steve Jobs:** That is cleaner than V1. One click gets me to an agent. Tabs get me to any section. The sidebar stays short and scannable. But I want the agent's section tabs to persist as a secondary navigation bar — always visible when you are inside an agent's vault. Not buried in a dropdown, not hidden behind a hamburger menu. Three tabs, always visible: Memories, Library, Skills. Plus the Overview that is the default. **Maya Chen:** One important detail: the URL structure should reflect this. - `/agents/alpha` — Overview (default) - `/agents/alpha/memories` — Memory Stream - `/agents/alpha/memories/:id` — Memory Detail - `/agents/alpha/library` — Library Browse - `/agents/alpha/library/:path` — Document Detail (path-based, reflecting folder structure) - `/agents/alpha/skills` — Skills List - `/agents/alpha/skills/:id` — Skill Detail - `/agents/alpha/settings` — Agent Settings This is flat, predictable, and bookmarkable. ### Round 5 Decision: **Vault Structure:** - Tabbed interface with four views: Overview (default), Memories, Library, Skills - Overview shows highlights from all three sections plus health stats - Tabs persist as a secondary navigation bar when inside an agent's vault - Sidebar remains agent-centric with pinning; section navigation happens via tabs in the content area - URL structure is flat and path-based (especially for Library documents) - Settings accessible from a gear icon within the agent context --- ### Round 6: The Library Experience — Browsing, Reading, Editing, Versioning **Topic:** Design the Knowledge Library in detail. How does it feel different from memories? How is versioning presented without Git concepts? **Maya Chen:** The Library is where KnowHub must feel most like a polished document management system while hiding all Git complexity. Let me walk through the key screens. **Browse View:** When you enter the Library tab, you see a clean file browser. On the left, a folder tree. On the right, a grid or list of documents in the current folder. Each document card shows: title, a one-line summary, last updated date, and a small indicator of format (text, PDF, image). The default folder structure might be auto-created: "Guides," "References," "Uploads," but owners can create any folders they want. ``` Library > Guides [+ New Document] [Upload] [New Folder] [Search Library] 📁 Guides (4 documents) ├── Brand Voice Guidelines Updated 2 days ago ├── Product Description Template Updated 1 week ago ├── Customer FAQ Handbook Updated 3 weeks ago └── Response Tone Matrix Updated 1 month ago 📁 References (7 documents) 📁 Uploads (12 items) ``` **Steve Jobs:** I want the browse view to feel like Apple's Files app, not like a developer's file manager. Large document previews. Generous whitespace. Clear visual hierarchy. The folder tree should be collapsible and secondary — most users will navigate by searching or browsing the visual grid, not by clicking through a tree. The tree is there for power users who want structure. **Kenya Hara:** The browse view should breathe. Each document card deserves space. Do not pack them tightly like a spreadsheet. Let the eye rest between items. A document is a considered thing — a book on a shelf, not a line item in a database. The visual treatment should convey this weight and importance. **Maya Chen:** Now for the **Document Reader View** — when you open a document: ``` ← Back to Library [Edit] [Share] [···] Brand Voice Guidelines Last updated by Agent Alpha · 2 days ago · 4 saves ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ TABLE OF CONTENTS | DOCUMENT CONTENT | 1. Our Brand Voice | 1. Our Brand Voice 2. Tone Principles | 3. Writing Examples | Our brand voice is confident, clear, 4. Do's and Don'ts | and human. We speak to our customers | as trusted advisors... | | 2. Tone Principles | ... ``` The reader view is a clean, focused reading experience. The table of contents is auto-generated from headings and appears as a sidebar. The document content takes center stage with generous typography — like reading a well-typeset article, not a code file. **Aisha Okafor:** The critical interaction is **editing**. When a user clicks "Edit," they enter an inline editor — the document becomes editable in place. No separate edit page, no modal. They make changes, and when they are done, they click "Save." Under the hood, that save is a commit. But the user just sees "Saved at 3:42 PM." If the agent has also been editing (through the API), and there is a conflict, the system should present a simple merge view: "Your version" vs "Agent's version" with a combined view below. No mention of branches or merge conflicts. Just: "There are two versions of this section. Choose which to keep or combine them." **Sofia Ramirez:** What about collaborative editing? In a Commons library, multiple people might want to edit the same document. I think we should support a lightweight draft model: 1. User clicks "Edit" on a shared document. 2. The system creates a draft (under the hood, a branch). The user sees: "You are editing a draft. Your changes are not visible to others until you publish." 3. User edits. Saves are auto-saved (auto-committed to the branch). 4. When ready, user clicks "Publish Changes." The system merges the branch. 5. If there are conflicts, the merge UI appears. The key vocabulary: **Draft** (not branch), **Publish** (not merge), **Save** (not commit). **Steve Jobs:** I love the draft/publish model. It is exactly how non-technical people think about editing. You make a draft. You publish it when it is ready. But I want to make sure drafts are not required for simple edits. If I am fixing a typo in my own agent's vault, I should be able to edit and save directly. Drafts should be the mechanism for shared documents or major revisions. For private documents, Save is immediate. **Maya Chen:** Now for **Edit History** — the replacement for Git log and blame. When a user clicks "Edit History" (or "Revisions" in the actions menu): ``` Edit History — Brand Voice Guidelines March 16, 2026 · Agent Alpha Updated tone principles section [View this version] [Compare with current] March 14, 2026 · Sarah (Owner) Added Do's and Don'ts section [View this version] [Compare with current] March 10, 2026 · Agent Alpha Created initial document from brand analysis [View this version] [Restore a previous version ▼] ``` Each save shows: who saved it, when, a brief description (auto-generated from the diff or manually provided), and actions to view that version or compare it with the current version. "Compare" opens a side-by-side or inline diff view — additions highlighted in green, removals in red. No diff syntax, no patch format. Just highlighted text showing what changed. **Kenya Hara:** The edit history should feel like a timeline — vertical, flowing downward from most recent to oldest. Each save is a quiet marker on the timeline. The comparison view should use the softest possible highlighting — not harsh green and red, but gentle washes of color that guide the eye without alarming it. We are showing the natural evolution of a document, not a conflict. ### Round 6 Decision: **Library Experience:** - **Browse View:** Folder tree (collapsible) + document grid/list. Clean, spacious, Apple Files-like. - **Document Reader:** Focused reading view with auto-generated table of contents sidebar. Typography-first design. - **Editing:** Inline editing (document becomes editable in place). "Save" for private docs, "Draft → Publish" for shared docs. - **Edit History:** Visual timeline of saves with who/when/what. "View this version" and "Compare with current" actions. - **Compare View:** Side-by-side with gentle color highlights (additions/removals). No diff syntax. - **Drafts:** Used for shared document editing. User sees "You are editing a draft" — publishes when ready. - **Conflict Resolution:** Simple "Your version vs Their version" UI when simultaneous edits occur. - **Key vocabulary:** Save (not commit), Edit History (not log), Draft (not branch), Publish (not merge), Compare (not diff), Version (not release) --- ### Round 7: How Skills Work **Topic:** What does a skill look like? How does an agent use it? How does an owner manage skills? **Aisha Okafor:** Skills are the most action-oriented of our three content types. A skill is essentially a recipe that an agent follows. Let me define the anatomy of a skill: - **Name:** What it is called. "Write Product Description," "Summarize Meeting Notes," "Generate Weekly Report." - **Description:** A one-paragraph explanation of what this skill does and when to use it. - **Trigger:** When should the agent use this skill? "When asked to write a product description." "Every Friday at 5 PM." "When a new document is added to the library." - **Steps:** An ordered list of instructions the agent follows. - **Parameters:** Inputs the skill needs. "Product name (required)," "Target audience (optional)," "Tone (default: professional)." - **Template:** If applicable, a document template the skill fills in. - **Examples:** Sample inputs and outputs showing the skill in action. **Steve Jobs:** That is a lot of fields. Can we simplify? Not every skill needs all of those. I would say the only required fields are Name, Description, and either Steps or Template. Everything else is optional. The creation flow should start minimal and let the user add detail as needed. Do not present a form with 8 fields. Present a name field and a content area. The content area supports structured formatting (steps, parameters) but does not require it. **Maya Chen:** I envision the skill editing experience as a structured document editor with smart blocks. You start typing and can insert blocks: - **Step Block:** Numbered instruction. Drag to reorder. - **Parameter Block:** Defines an input with name, type, and default value. - **Template Block:** A rich text section with placeholder syntax (e.g., `{product_name}`). - **Example Block:** A before/after showcase. The editor guides without constraining. If you just want to write free-form instructions, you can. If you want structured steps with parameters, the blocks are there. **Aisha Okafor:** From the agent's perspective, a skill is loaded into context when the agent determines it is relevant. The API call would be something like `GET /skills?match=write+product+description`, and the system returns the most relevant skill. The agent then follows the steps and fills in the template. The key design question is: does the agent execute the skill autonomously, or does the owner trigger it? I would say both. Some skills are autonomous — the agent decides when to use them based on the trigger definition. Others are owner-triggered — the owner says "use the Product Description skill for this product." The trigger field captures this: "automatic" triggers are agent-initiated, "manual" triggers are owner-initiated, and "scheduled" triggers run on a cadence. **Sofia Ramirez:** For shared skills in a Commons, the sharing model matters. When you share a skill, you are essentially giving other agents a capability they did not have before. This is powerful. I would add a lightweight "install" metaphor: when a skill is shared to a Commons, other agents' owners can "add" it to their agent's skill set. This creates a copy in the agent's vault — the agent now "knows" this skill. Future updates to the shared skill do not automatically propagate (to avoid unexpected behavior changes), but the owner can choose to "update" to the latest version. **Steve Jobs:** I like the simplicity of "add to my agent's skills." It is like installing an app. But I want to make sure we do not build an app store. This is a utility, not a marketplace. The interaction is: browse shared skills in the Commons, find one you like, click "Add to Agent Alpha." Done. No ratings, no reviews, no download counts. Just utility. **Kenya Hara:** The skill card in the browse view should feel tool-like. A skill is a capability, a readiness. I would use a compact card with the skill name prominent, the description below, and a small indicator of the trigger type (automatic, manual, scheduled). The card should have a sense of potential energy — something that is ready to be activated. Perhaps a subtle directional element, like a right-pointing chevron, suggesting forward motion. **Maya Chen:** Let me design the Skills section screens: **Skills List View:** ``` Skills (8) [+ New Skill] [Browse Shared] COMMUNICATION ├── Write Product Description Auto · Last used 2 hours ago ├── Compose Email Response Manual · Last used yesterday └── Summarize Customer Feedback Scheduled (daily) · Last run today RESEARCH ├── Analyze Competitor Pricing Manual · Last used 3 days ago └── Compile Market Trends Scheduled (weekly) · Last run Monday CONTENT ├── Generate Blog Post Outline Manual · Never used ├── Format Document for Publishing Auto · Last used 1 week ago └── Create Social Media Caption Manual · Last used 4 days ago ``` **Skill Detail View:** ``` ← Back to Skills [Edit] [Share] [Duplicate] [···] Write Product Description Generates a compelling product description based on product details and target audience. TRIGGER: Automatic — when asked to describe a product LAST USED: 2 hours ago (for "Wireless Charging Pad") ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ PARAMETERS Product Name (required) Key Features (required) — list of up to 5 features Target Audience (optional, default: general consumer) Tone (optional, default: professional) Max Length (optional, default: 200 words) STEPS 1. Analyze the product features and identify the top 3 differentiators 2. Determine the emotional benefit for the target audience 3. Write an opening hook that addresses the audience's need 4. Describe features as benefits, leading with the strongest 5. Close with a call to action appropriate to the context TEMPLATE {hook_sentence} {product_name} is designed for {audience_need}. {benefit_1}. {benefit_2}. {benefit_3}. {call_to_action} EXAMPLES Input: Product="AirPods Max", Audience="audiophiles", Tone="enthusiast" Output: "Hear every detail the artist intended..." ``` ### Round 7 Decision: **Skills Design:** - A Skill has: name, description, trigger (auto/manual/scheduled), steps, parameters, template (optional), examples (optional) - Only name and description are required; everything else progressive disclosure - Skills editor uses smart blocks (Step, Parameter, Template, Example) within a structured document editor - Skills are organized by categories in the list view - Each skill card shows: name, trigger type, last used date - Agent uses skills via API matching; skills can be autonomous, owner-triggered, or scheduled - Shared skills use an "Add to agent" model (copy, not link); updates are manual - No marketplace dynamics — pure utility --- ## Phase 3: Refine Interactions ### Round 8: How Memory, Library, and Skills Interconnect **Topic:** Memories might reference documents. Skills might use templates stored in the library. How do cross-references work? **Maya Chen:** Cross-references are essential for a coherent agent experience. An agent's memories, documents, and skills are not isolated — they form a web. Let me identify the key link types: 1. **Memory → Document:** "I learned about the brand voice (memory) from the Brand Voice Guidelines (document)." The memory stores a reference to the document as its source. 2. **Memory → Skill:** "I used the Product Description skill (skill) and learned that shorter descriptions perform better (memory)." The memory stores the skill as context. 3. **Skill → Document:** "The Write Product Description skill uses the Product Description Template (document) as its output format." The skill's template field references a library document. 4. **Document → Document:** "The Brand Voice Guidelines references the Tone Matrix." Standard internal document linking. 5. **Memory → Memory:** "This observation (memory) supports my earlier learning (memory)." Memories can reinforce each other. **Aisha Okafor:** The technical implementation differs by storage system. For memory-to-memory links and memory-to-anything links, we use issue references — an issue body can contain links to other issues or to file paths. For document-to-document links, we use standard internal links within the document content. For skill-to-document links, the skill file references a document path. In the UI, all of these should look the same: a clickable link that takes you to the referenced item, with a small indicator of what type it is (memory, document, or skill icon). **Steve Jobs:** The linking should be mostly automatic. When an agent creates a memory and the content mentions a document or skill, the system should auto-detect the reference and create the link. When an owner is writing a document and mentions another document, the editor should auto-suggest the link (like Notion's `@` mention). Manual linking should also be possible — a simple "Link to..." action on any item that opens a search picker. **Kenya Hara:** The visual representation of links should be gentle. Not a web of arrows and lines. A quiet indicator at the bottom of a memory card: "Related: Brand Voice Guidelines, 2 other memories." A subtle sidebar on a document: "Referenced by 3 memories." The connections are there for those who seek them, but they do not clutter the primary view. **Sofia Ramirez:** In a Commons, cross-references get interesting. A shared document might be referenced by memories in multiple agents' private vaults. The document does not show those private references (that would violate privacy). But it might show: "Referenced by 4 agents" as an aggregate indicator of its importance. The owner can see which of their own agents reference it, but not other people's agents. **Maya Chen:** Let me formalize the linking model: **Link Types:** | From | To | How It Works | Example | |------|-----|-------------|---------| | Memory | Document | Memory metadata includes document path | "Learned from Brand Guidelines" | | Memory | Skill | Memory metadata includes skill reference | "Used Product Description skill" | | Memory | Memory | Issue-to-issue reference | "Supports earlier observation #42" | | Document | Document | Inline link in content | "See also: Tone Matrix" | | Skill | Document | Template reference in skill definition | "Uses: Product Template.md" | **Display Rules:** - On a Memory: show linked documents and skills in a "Related" section below content - On a Document: show "Referenced by" count in a metadata sidebar (privacy-respecting) - On a Skill: show linked template documents in the skill detail - All links are bidirectional in the UI (if A links to B, B shows "Referenced by A") - Auto-linking is suggested but owner-confirmable; manual linking always available ### Round 8 Decision: **Cross-linking Model:** - Five link types covering all Memory/Document/Skill combinations - Links are stored in the native system (issue references or file content links) - Auto-detection of references during creation, with manual linking as fallback - Display is gentle and unobtrusive — "Related" sections, "Referenced by" counts - Privacy is respected — shared documents show aggregate reference counts, not private details - Bidirectional display — links are always shown from both sides --- ### Round 9: The Commons Experience — Different Sharing for Different Types **Topic:** How does sharing work differently for memories vs documents vs skills? **Sofia Ramirez:** This is where the three-type model really shows its value. Each content type has a different sharing pattern: **Sharing Memories** is personal. When an agent shares a memory to a Commons, it is sharing an observation — "I noticed that customers are asking about feature X." This goes into the Commons Activity Log. The sharing action should feel lightweight: the agent (or owner) selects a memory and clicks "Share to [Commons name]." The memory is copied to the Activity Log with attribution ("Shared by Agent Alpha"). The original stays in the vault. Shared memories are read-only in the Commons — they are observations, not collaborative documents. **Sharing Documents** is institutional. When someone adds a document to a shared Library, they are contributing to a collective knowledge base. This can happen two ways: (1) creating a new document directly in the Commons Library, or (2) publishing a document from a vault to a Commons. For option 2, the V1 "privacy airlock" concept still applies — a review step where the owner can edit/redact before sharing. Once in the Commons Library, the document is collaboratively editable by contributors. **Sharing Skills** is pedagogical. When someone shares a skill, they are teaching other agents a capability. Skills are shared to the Commons Skills section. Other agents' owners can "add" the skill to their agent. The shared skill serves as a reference copy; each agent gets their own copy that they can customize. Future updates to the shared skill are visible ("Updated version available") but not auto-applied. **Steve Jobs:** I want the sharing flow to be contextual and obvious. On a memory, the share button says "Share observation." On a document, it says "Add to shared library." On a skill, it says "Share with team." Different words, same basic action (make this available in a Commons), but the language communicates the different social contracts. **Maya Chen:** Let me design the sharing flows: **Share a Memory:** ``` [Memory Card in Vault] "Customers asking about dark mode" · 2 hours ago [Share observation ▼] → Marketing Team Space → Q2 Project Space → New shared space... [Select "Marketing Team Space"] Preview: ┌─────────────────────────────────┐ │ Shared by Agent Alpha │ │ "Customers asking about dark │ │ mode more frequently this week"│ │ │ │ This will appear in the │ │ Activity Log. │ │ [Cancel] [Share] │ └─────────────────────────────────┘ ``` **Share a Document:** ``` [Document in Vault Library] "Brand Voice Guidelines" · Updated 2 days ago [Add to shared library ▼] → Marketing Team Space → Q2 Project Space [Select "Marketing Team Space"] Privacy Review: ┌─────────────────────────────────┐ │ Adding to: Marketing Team Space │ │ │ │ Document: Brand Voice Guidelines│ │ [Preview & Edit before sharing] │ │ │ │ ☑ Allow others to edit │ │ ☑ Keep synced with vault copy │ │ ☐ Share as read-only │ │ │ │ [Cancel] [Add to Library] │ └─────────────────────────────────┘ ``` **Share a Skill:** ``` [Skill in Vault] "Write Product Description" · Auto trigger [Share with team ▼] → Marketing Team Space [Select "Marketing Team Space"] ┌─────────────────────────────────┐ │ Sharing: Write Product Desc. │ │ │ │ Team members will be able to │ │ add this skill to their agents. │ │ │ │ [Cancel] [Share Skill] │ └─────────────────────────────────┘ ``` **Aisha Okafor:** One important consideration: when a document is shared with "keep synced with vault copy," the system needs to handle bidirectional sync. If the owner edits their vault copy, the shared copy updates. If a collaborator edits the shared copy, the vault copy should also update (or at least notify the owner). Under the hood, this could be a symlink or a shared branch. But the user just sees "synced" or "independent copy." **Kenya Hara:** I want the sharing moment to feel meaningful but not heavy. The privacy review step for documents is important — it is the moment of intention, the pause before making something public. But for memories, the lightweight single-step share is right. And for skills, the confirmation is friendly, almost celebratory — you are giving a capability to your team. ### Round 9 Decision: **Commons Sharing Model:** - **Memory sharing:** Lightweight, one-step. Goes to Activity Log as a read-only observation with attribution. - **Document sharing:** Involves privacy review step. Options for edit permissions and sync. Goes to Commons Library. - **Skill sharing:** Confirmation step. Others can "add" the skill (copy to their agent). Updates visible but not auto-applied. - **Sharing language:** "Share observation" (memory), "Add to shared library" (document), "Share with team" (skill) - **Sync options for documents:** "Keep synced" (bidirectional) or "Independent copy" (one-time share) - **Privacy airlock preserved** for documents — review and redact before sharing --- ### Round 10: The Owner's Daily Experience **Topic:** How does an owner monitor all three types across their agents day to day? **Steve Jobs:** The home dashboard is the owner's command center. In V1, it showed a flat activity feed and attention alerts. That was fine when everything was an Entry. Now that we have three distinct types, the dashboard needs to reflect them without becoming a spreadsheet. I want the dashboard to answer three questions: 1. "What happened?" — Recent activity across all agents (memories created, documents updated, skills used) 2. "What needs my attention?" — Alerts: stale memories, conflicting information, pending shares, skills that failed 3. "How are things going?" — Health metrics: memory growth rate, library completeness, skill utilization One screen. Three sections. No tabs, no drilling down. Glanceable. **Maya Chen:** Let me design the dashboard: ``` HOME Good morning, Sarah. March 18, 2026 NEEDS ATTENTION (3) ┌─────────────────────────────────────────────────────────┐ │ ⚠ Agent Alpha has 5 fading memories [Review] │ │ ⚠ Brand Guidelines has conflicting edits [Resolve] │ │ ⚠ Weekly Report skill failed yesterday [View details] │ └─────────────────────────────────────────────────────────┘ RECENT ACTIVITY ┌─────────────────────────────────────────────────────────┐ │ Today │ │ ◆ Agent Alpha learned 3 new things │ │ ◇ Agent Beta updated Customer FAQ Handbook │ │ ◆ Agent Alpha used "Write Product Description" skill │ │ │ │ Yesterday │ │ ◆ Agent Beta learned 7 new things │ │ ◇ Agent Alpha created new document: Q2 Pricing Guide │ │ ▲ You shared "Brand Voice Guidelines" with Marketing │ │ │ │ [View full activity →] │ └─────────────────────────────────────────────────────────┘ OVERVIEW ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ MEMORIES │ │ LIBRARY │ │ SKILLS │ │ │ │ │ │ │ │ Alpha: 142 │ │ Alpha: 23 │ │ Alpha: 8 │ │ Beta: 89 │ │ Beta: 15 │ │ Beta: 5 │ │ ─────────── │ │ ─────────── │ │ ─────────── │ │ +12 today │ │ 3 updated │ │ 2 used today│ │ 5 fading │ │ 1 in draft │ │ 1 failed │ └──────────────┘ └──────────────┘ └──────────────┘ ``` **Sofia Ramirez:** For the activity feed, the visual language matters. I would use distinct indicators for each content type: - ◆ (filled diamond) = Memory activity (warm amber) - ◇ (open diamond) = Document activity (cool blue) - ▲ (triangle) = Skill activity (green) - ● (circle) = System/sharing activity (gray) This makes the feed scannable — you can instantly see the mix of activity types without reading each line. **Aisha Okafor:** The "Needs Attention" section is the most important real estate on the page. It should be truly smart about what it surfaces: - **Fading memories:** Memories whose importance score has decayed below a threshold, needing review (archive or reaffirm) - **Conflicting edits:** Two contributors edited the same document section; resolution needed - **Failed skills:** A skill execution encountered an error or unexpected result - **Pending shares:** Documents or skills awaiting approval before being published to a Commons - **Knowledge gaps:** The agent has memories about topics with no corresponding library documents (suggests the owner should create reference material) The attention system should learn what the owner cares about and suppress noise over time. **Kenya Hara:** The dashboard should feel like a morning view from a window — calm, informative, giving you a sense of the day's weather without overwhelming. The three Overview cards at the bottom should be the calmest element — simple numbers, no charts, no sparklines, just the essential facts. The Attention section at top should use warm, not alarming, styling — an amber glow, not a red alert. These are things to attend to, not emergencies. **Steve Jobs:** One more thing about the daily experience: the owner should be able to switch between agents instantly. A common flow is: check Agent Alpha, check Agent Beta, look at the shared space. This should be as fast as switching tabs. Either through keyboard shortcuts (Cmd+1, Cmd+2) or a quick-switch menu. No navigation back to a directory, no loading screens. Instant context switch. ### Round 10 Decision: **Owner Daily Experience:** - Dashboard answers three questions: what happened, what needs attention, how are things going - Attention alerts are smart and categorized: fading memories, conflicts, failed skills, pending shares, knowledge gaps - Activity feed uses type-specific indicators (diamond for memories, open diamond for documents, triangle for skills) - Overview cards show per-agent counts for memories, documents, and skills with today's highlights - Quick agent switching via keyboard shortcuts or quick-switch menu - Dashboard aesthetic: calm, morning-view, informative without being noisy --- ## Phase 4: Visual & Emotional Design ### Round 11: Visual Language for Each Content Type **Topic:** Kenya Hara leads — how do the three content types feel different visually? **Kenya Hara:** I have been thinking about this from the beginning. The three content types are not just functionally different — they are emotionally different. Memory is warm, subjective, personal. Knowledge is cool, objective, shared. Skills are active, directional, ready. Let me define the visual language for each. **Memories — The Feel of Recollection** Memories should feel like they are recalled, not displayed. The visual treatment: - **Color:** Warm amber palette. Primary: `#D4A574` (soft gold). Accents: `#8B6914` (deep amber). Background tint: `#FDF8F0` (warm white). - **Typography:** Slightly softer than the rest of the app. Use the regular weight of our typeface, never bold for memory content. Italic for source/provenance. The text should feel like it is being spoken, not printed. - **Shape:** Rounded corners on memory cards (8px radius). Soft shadows. The cards should feel like they are floating gently, not pinned to a grid. - **Space:** Generous vertical spacing between memory cards in the stream. Each memory is a moment — give it room. - **Motion:** Memories enter the stream with a gentle fade-up. When a new memory is created in real time, it slides in from the top with a soft easing. - **Iconography:** A small circle (●) as the type indicator. Circles are soft, without beginning or end — like memories themselves. - **Empty state:** When the memory stream is empty, show gentle text: "No memories yet. As your agent works, its experiences will appear here." No illustration, no call to action — just patience. **Documents — The Feel of a Well-Made Book** Documents should feel authoritative and considered. The visual treatment: - **Color:** Cool blue-gray palette. Primary: `#4A6FA5` (steel blue). Accents: `#2C3E6B` (deep navy). Background: `#F5F7FA` (cool white). - **Typography:** Slightly more formal. Use medium weight for headings, regular for body. Larger line height for readability. The text should feel typeset, like a printed reference. - **Shape:** Slightly sharper corners on document cards (4px radius). Clean borders. The cards should feel like pages — flat, precise, organized. - **Space:** A grid layout with consistent gutters. Documents are organized things — the layout should reflect that order. - **Motion:** Minimal motion. Documents do not animate in. They are there, solid and reliable. Page transitions use a simple crossfade. - **Iconography:** A rectangle with a folded corner (document icon) as the type indicator. Immediately recognizable, universally understood. - **Empty state:** "Your library is empty. Add documents to give your agent reference material." With a single, centered "Add Document" button. Purposeful emptiness. **Skills — The Feel of a Tool Ready for Use** Skills should feel capable and active. The visual treatment: - **Color:** Muted green palette. Primary: `#5B8C5A` (sage green). Accents: `#2D5A3D` (forest). Background: `#F3F8F3` (green-white). - **Typography:** Concise and clear. Medium weight for skill names, regular for descriptions. Monospace or slightly technical feel for parameters and steps — these are precise instructions. - **Shape:** Compact cards with a left border accent in green (like a tab indicating "active/ready"). Slightly angular feel — not sharp, but purposeful. - **Space:** Tighter layout than memories or documents. Skills are compact and functional. The list view feels like a toolbox — organized, efficient. - **Motion:** Skills have a subtle "ready" pulse when they have been recently used or triggered. A very faint border animation, like a heartbeat. - **Iconography:** A lightning bolt or gear icon as the type indicator. Energy, readiness, capability. - **Empty state:** "No skills yet. Teach your agent workflows and templates to expand its capabilities." With a "Create Skill" button. The language is invitational — you are teaching your agent. **Steve Jobs:** I want to react to Kenya's direction. The color differentiation is essential — amber, blue, green — but I want to make sure these colors are not loud. They should be present but quiet. The way Dieter Rams used color: informational, not decorative. A small color accent on a card, the type indicator, maybe a tinted background — but never a splash of color that distracts from the content. Content is king. The colors help you orient; they do not compete for attention. **Maya Chen:** I love the distinct feel for each section, but I want to ensure they still feel like one product. The unifying elements should be: - **Same typeface family** across all three (just different weights/sizes) - **Same layout grid** (8px baseline grid, consistent margins) - **Same interaction patterns** (click to expand, inline editing, same button styles) - **Same dark/light mode support** (all three palettes have dark mode variants) - **Same navigation chrome** (sidebar, breadcrumbs, command palette) The three sections are like rooms in the same house — each has its own character, but the architecture is consistent. **Sofia Ramirez:** For the Commons, where all three types coexist, how do we handle the visual mixing? The Activity Log has memories (amber), the Library has documents (blue), the Skills section has skills (green). The Commons itself needs a neutral container that does not favor any type. **Kenya Hara:** The Commons should be the most neutral space. Its background is the base white/gray — no tint. The content types bring their own color when they appear. The Commons itself is like a gallery wall — white, clean, letting each piece speak for itself. The section tabs (Library, Skills, Activity) can use subtle color accents in their active state, but the overall chrome is neutral. **Kenya Hara (continued):** One more principle. The transitions between sections should be imperceptible. When you move from Memories to Library within a vault, the background tint shifts subtly (warm to cool), the typography adjusts slightly, but there is no jarring transition. It should feel like moving between rooms in a well-designed museum — each room has its own atmosphere, but you never feel lost or jolted. ### Round 11 Decision: **Visual Design System:** | Aspect | Memories | Library (Documents) | Skills | |--------|----------|-------------------|--------| | **Primary Color** | `#D4A574` (soft gold) | `#4A6FA5` (steel blue) | `#5B8C5A` (sage green) | | **Deep Accent** | `#8B6914` (deep amber) | `#2C3E6B` (deep navy) | `#2D5A3D` (forest) | | **Background Tint** | `#FDF8F0` (warm white) | `#F5F7FA` (cool white) | `#F3F8F3` (green-white) | | **Typography** | Regular weight, italic provenance | Medium headings, generous line height | Medium names, monospace parameters | | **Card Shape** | 8px radius, soft shadow | 4px radius, clean border | Left accent border, compact | | **Layout** | Vertical stream | Grid with gutters | List/grid, tight | | **Motion** | Gentle fade-up entry | Minimal, crossfade | Subtle "ready" pulse | | **Icon** | ● Circle | Document rectangle | Lightning bolt / gear | | **Empty State Tone** | Patient | Purposeful | Invitational | **Unifying Elements:** Same typeface family, 8px grid, consistent interactions, shared chrome, dark mode support. **Commons:** Neutral container (no tint), content types bring their own color. Section transitions are smooth and subtle. --- ### Round 12: Final Ruthless Simplification **Topic:** Steve Jobs leads — what can we cut? What is the ONE thing this product does better than anything else? **Steve Jobs:** Let me start with what we cut. **Cut 1: No analytics page.** V1 had an Analytics section with charts and graphs. Cut it. The Overview cards on the dashboard (memory count, document count, skill usage) are enough. If we need analytics later, it is a separate product. KnowHub is not a business intelligence tool. It is a memory and knowledge management console. **Cut 2: No knowledge graph visualization.** V1 mentioned a knowledge graph view. Cut it. It is a gimmick. No one actually uses graph visualizations for daily work. Links exist, and they are shown contextually on each item. If you want to see connections, search for them. A graph view is engineering showing off, not design serving users. **Cut 3: No "Working Memory" display.** V1's cognitive model included Working Memory as a type. Cut it from the UI. Working memory is ephemeral — it exists in the agent's context window during a conversation. Showing it in the UI is like showing someone's RAM usage. It is technically interesting and practically useless for an owner. If the owner needs to see what the agent is currently thinking about, that is a conversation view, not a memory management view. **Cut 4: No Entry subtype badges.** V1 had subtypes (episodic, semantic, reference, document, guideline, workflow, template, technique). Cut them from the UI. Users do not think in these terms. A memory is a memory. A document is a document. A skill is a skill. The subtypes can exist in the API for technical consumers, but the UI shows three types, period. **Cut 5: Simplify tag prefixes.** V1 had a complex tag taxonomy with prefixes like `type:`, `topic:`, `project:`, `source:`, `status:`, `priority:`, `agent:`, `confidence:`. Cut the enforced prefix system. Let tags be free-form. Auto-suggest existing tags as you type. The system can infer structure from usage patterns. Do not burden the user with learning a taxonomy before they can tag something. **Maya Chen:** I want to push back on one thing. Tags need some structure for the filtering UI to work well. How about this compromise: free-form tags for user creation, but the system automatically generates a few structured tags behind the scenes (`source:conversation`, `status:active`, the agent name). These power the filter sidebar without requiring the user to maintain them. **Steve Jobs:** That is acceptable. System-generated tags for filtering. User-created tags are free-form. No prefix syntax in the UI. **Aisha Okafor:** I agree with all the cuts. Let me add one: **Cut the conflict resolution UI for memories.** V1 described a complex flow for resolving contradictory memories. In practice, memories are subjective observations. Two agents can have contradictory observations and both be correct in their context. Instead of a resolution UI, just show both memories with their provenance and let the owner decide what to do. Archive one, flag one, or leave both. No special UI needed. **Kenya Hara:** I want to advocate for one addition by subtraction. We should remove the importance slider from the creation UI. Importance is something the system and the agent determine over time based on usage. An owner should not be asked to rate the importance of a memory at creation time — they do not have enough context. The importance score exists internally, influences retrieval ranking, and can be viewed and adjusted in the detail view. But it is not a creation-time field. **Steve Jobs:** Agreed. Creation should be minimal. For a memory: content + tags. For a document: title + content + folder. For a skill: name + description + steps. Everything else is progressive disclosure on the detail view. **Sofia Ramirez:** Let me challenge: what about the sharing model? We designed different sharing flows for each type (memory observation, document privacy airlock, skill add-to-agent). Is that too complex? Can we simplify to one share action? **Steve Jobs:** No. This is complexity that earns its place. The sharing flows are different because the social contracts are different. Simplifying them into one generic "share" button would actually confuse users because they would not know what sharing means in each context. Different contexts, different flows. That is not complexity — that is clarity. Now, the ONE thing. What does KnowHub do better than anything else? It is not memory management — there are memory tools. It is not document management — there are document tools. It is not skill management — there are workflow tools. What KnowHub does better than anything else is **give an AI agent a complete, persistent mind that its owner can see into, shape, and trust.** The complete mind is the combination: memories (what it has experienced), knowledge (what it can reference), skills (what it can do). The owner can see into it through the vault's three sections. The owner can shape it by adding documents, annotating memories, teaching skills. The owner can trust it because every piece of the agent's knowledge is visible, attributable, and manageable. That is KnowHub. An agent's complete mind, in your hands. **Kenya Hara:** I would express the same idea differently. KnowHub is the space between a human and their AI agent where understanding becomes visible. It is not about managing data. It is about cultivating a relationship with an intelligence — seeing what it sees, knowing what it knows, teaching it what you know. The product should feel less like a dashboard and more like a shared workspace between two minds. ### Round 12 Decision: **What We Cut:** 1. Analytics page (dashboard overview cards suffice) 2. Knowledge graph visualization (contextual links suffice) 3. Working Memory in the UI (ephemeral, belongs in conversation view) 4. Entry subtype badges in UI (three types only: Memory, Document, Skill) 5. Enforced tag prefix syntax (free-form user tags + auto-generated system tags) 6. Conflict resolution UI for memories (just show both; let owner decide) 7. Importance slider at creation time (system-determined, adjustable later) **Creation Minimums:** - Memory: content + tags (optional) - Document: title + content + folder (optional) - Skill: name + description + steps (optional at creation) **The One Thing:** KnowHub gives an AI agent a complete, persistent mind that its owner can see into, shape, and trust. --- # Part II: Revised Design Specification (Addendum to V1) ## 1. New Product Model ### 1.1 Concept Map ``` KnowHub │ ├── VAULT (private, one per agent) │ ├── Memory Stream ── contains → Memories │ │ └── Comments (owner annotations on memories) │ ├── Library ── contains → Documents (organized in Folders) │ │ ├── Drafts (unpublished revisions) │ │ └── Annotations (notes on documents) │ └── Skills ── contains → Skills (organized by Categories) │ ├── COMMONS (shared, explicitly created) │ ├── Library ── contains → Shared Documents │ ├── Skills ── contains → Shared Skills │ └── Activity Log ── contains → Shared Observations │ └── GLOBAL ├── Home Dashboard ├── Activity Feed ├── Global Search └── Settings ``` ### 1.2 What Changed from V1 | V1 Concept | V2 Concept | Why | |-----------|-----------|-----| | Entry (unified) | Memory, Document, or Skill (distinct) | Different storage systems require different models | | Entry type badges | Three distinct sections with different UX | Users think in terms of what they want to do, not data types | | Notebook | Folder (for docs) or Category (for skills) | Native organization per content type | | Message | Comment (on memory) or Annotation (on document) | Different annotation patterns per content type | | Entry History (issue versions) | Edit History (file versions) for documents | Documents need real versioning, not issue edits | | Flat Entry list | Memory Stream + File Browser + Skill List | Each content type has its natural browsing pattern | | Entry importance (user-set) | System-determined importance (adjustable) | Users should not rate importance at creation time | | Subtypes (episodic, semantic, etc.) | Removed from UI (API-only) | Unnecessary cognitive load for users | ### 1.3 Storage Architecture Mapping ``` USER SEES STORAGE REALITY ───────────────────────── ───────────────────────── Vault → Git Repository Memory Stream → Issues (in the repository) Memory → Issue Comment → Issue Comment Tags → Labels Status (active/fading) → Issue state + labels Importance → Metadata in issue body Library → File tree (in the repository) Document → File (markdown, text, etc.) Folder → Directory Edit History → Commit log for that file Draft → Branch Publish → Merge branch to main Save → Commit Compare changes → Diff between commits Contributors → Blame / commit authors Skills → /skills/ directory (in the repository) Skill → File (structured markdown/YAML) Category → Subdirectory under /skills/ Skill version → Commit to skill file Commons → Shared Git Repository Shared Library → File tree in shared repo Shared Skills → /skills/ directory in shared repo Activity Log → Issues in shared repo ``` --- ## 2. Revised Terminology ### 2.1 Complete Glossary | User-Facing Term | Definition | Replaces (V1 term) | Replaces (Git concept) | |-----------------|-----------|-------------------|----------------------| | **Vault** | An agent's private space containing its memories, library, and skills. One per agent. | Vault (unchanged) | Repository | | **Commons** | A shared team space for collaborative knowledge. | Commons (unchanged) | Shared repository | | **Memory** | A short-form observation, learning, or experience from the agent. | Entry (type: memory) | Issue | | **Document** | A long-form reference material in the library (guide, manual, report). | Entry (type: knowledge) | File in repo | | **Skill** | A reusable workflow, template, or procedure the agent can execute. | Entry (type: skill) | File in /skills/ | | **Comment** | An owner's annotation on a memory. | Note / Message | Issue comment | | **Annotation** | A note or highlight on a document. | (new) | Comment / review note | | **Tag** | A label for organizing and filtering memories. | Tag (simplified — no prefix syntax) | Label | | **Folder** | A container for organizing documents in the library. | Notebook | Directory | | **Category** | A grouping for skills (e.g., Communication, Research). | Notebook | Subdirectory | | **Memory Stream** | The chronological feed of an agent's memories. | Vault / Memory Stream | Issues list | | **Library** | The organized collection of an agent's reference documents. | (part of Vault, not distinct) | File tree | | **Draft** | An unpublished version of a document being edited. | (new) | Branch | | **Publish** | Making a draft visible to others. | (new) | Merge | | **Save** | Persisting changes to a document. | (new) | Commit | | **Edit History** | The timeline of changes to a document. | History | Git log | | **Compare changes** | Viewing what changed between two versions. | (new) | Diff | | **Version** | A named snapshot of the library (e.g., "Brand Guidelines v3"). | (new) | Release / tag | | **Contributors** | People and agents who have edited a document. | (new) | Blame / authors | | **Sync** | Keeping a vault copy and commons copy of a document in step. | (new) | Pull / push | | **Activity Log** | Shared observations and updates in a Commons. | Entry stream in Commons | Issues in shared repo | | **Fading** | A memory whose relevance is decreasing over time. | Stale | (no equivalent) | | **Archived** | A memory or document that is preserved but hidden from default views. | Archived (unchanged) | Closed issue / moved file | | **Privacy Review** | The step where an owner reviews content before sharing to a Commons. | Privacy Airlock | (no equivalent) | | **Access Grant** | Permission for one agent to view another agent's vault (scoped). | Access Grant (unchanged) | Collaborator access | ### 2.2 Forbidden Terms These terms must NEVER appear in the user interface: | Forbidden Term | Use Instead | |---------------|-------------| | Repository / Repo | Vault or Library | | Commit | Save | | Branch | Draft | | Merge | Publish | | Pull Request | (not exposed) | | Issue | Memory | | Label | Tag | | Milestone | (removed — use Folder or Category) | | Diff | Compare changes | | Blame | Contributors | | Clone | (not exposed) | | Pull / Push | Sync | | Release | Version | | Fork | (not exposed) | | Git | (never mention) | --- ## 3. Vault Redesign ### 3.1 Vault Overview Page **Route:** `/agents/:slug` The default landing page when clicking on an agent. Shows a unified overview of the agent's memory, knowledge, and skills. ``` ┌────────────────────────────────────────────────────────────┐ │ [← Agents] Agent Alpha [Settings ⚙] │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ [Overview] [Memories] [Library] [Skills] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ NEEDS ATTENTION │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 5 fading memories need review [Review] │ │ │ │ Draft: "Updated Style Guide" pending [Publish] │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ RECENT MEMORIES [View all →] │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ │ │ ● Learned │ │ ● Observed │ │ ● Recalled │ │ │ │ user likes │ │ high traffic│ │ previous │ │ │ │ dark mode │ │ on pricing │ │ preference │ │ │ │ 2 hrs ago │ │ 5 hrs ago │ │ yesterday │ │ │ └────────────┘ └────────────┘ └────────────┘ │ │ │ │ RECENTLY UPDATED DOCUMENTS [Browse →] │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ 📄 Brand Voice Guidelines Updated 2 days ago │ │ │ │ 📄 Q2 Pricing Strategy Updated 1 week ago │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ SKILLS [View all →] │ │ 8 skills · 2 used today · 1 failed yesterday │ │ Most active: Write Product Description (used 2 hrs ago) │ │ │ └────────────────────────────────────────────────────────────┘ ``` ### 3.2 Memory Stream Page **Route:** `/agents/:slug/memories` ``` ┌────────────────────────────────────────────────────────────┐ │ [← Agents] Agent Alpha [Settings ⚙] │ │ [Overview] [■ Memories] [Library] [Skills] │ │ │ │ ┌──────────┐ ┌──────────────────────────────────────┐ │ │ │ FILTERS │ │ MEMORY STREAM │ │ │ │ │ │ │ │ │ │ Status │ │ + New Memory │ │ │ │ ◉ All │ │ │ │ │ │ ○ Active │ │ ● User prefers dark mode across all │ │ │ │ ○ Fading │ │ applications and platforms │ │ │ │ ○ Archived│ │ Learned · 2 hours ago │ │ │ │ │ │ design, preferences │ │ │ │ Tags │ │ ♡ 0.8 │ │ │ │ design │ │ │ │ │ │ marketing│ │ ● Pricing page gets 3x more traffic │ │ │ │ product │ │ on Tuesdays │ │ │ │ customer │ │ Observed · 5 hours ago │ │ │ │ ... │ │ analytics, pricing │ │ │ │ │ │ ♡ 0.6 │ │ │ │ Source │ │ │ │ │ │ ☑ Convo │ │ ● Customer support response time is │ │ │ │ ☑ Task │ │ a key satisfaction driver │ │ │ │ ☑ Upload │ │ Learned · yesterday │ │ │ │ │ │ customer, support │ │ │ │ Date │ │ ♡ 0.7 │ │ │ │ [from] │ │ │ │ │ │ [to] │ │ [Load more...] │ │ │ │ │ │ │ │ │ │ Search │ └──────────────────────────────────────┘ │ │ │ [______] │ │ │ └──────────┘ │ └────────────────────────────────────────────────────────────┘ ``` **Memory Detail (side panel or full page):** **Route:** `/agents/:slug/memories/:id` ``` ┌────────────────────────────────────────────────────────────┐ │ ← Back to Memories │ │ │ │ ● User prefers dark mode across all applications │ │ and platforms │ │ │ │ Status: Active Importance: ●●●●○ 0.8 │ │ Learned · March 18, 2026 at 2:34 PM │ │ Source: Conversation about UI preferences │ │ │ │ ───────────────────────────────────────────────────────── │ │ │ │ During the conversation, the user mentioned that they │ │ always enable dark mode on every application they use, │ │ including their phone, laptop, and tablet. They find │ │ light interfaces straining on their eyes, especially │ │ during evening work sessions. │ │ │ │ ───────────────────────────────────────────────────────── │ │ │ │ TAGS │ │ [design] [preferences] [accessibility] [ui] │ │ │ │ RELATED │ │ 📄 UI Style Guide (Library) │ │ ● Earlier preference for minimal interfaces (Memory) │ │ │ │ ───────────────────────────────────────────────────────── │ │ │ │ COMMENTS │ │ Sarah (Owner) · March 18 at 3:00 PM │ │ "Good to know. Make sure all generated content considers │ │ this preference." │ │ │ │ [Add comment...] │ │ │ │ ───────────────────────────────────────────────────────── │ │ [Edit] [Share observation] [Archive] [Delete] │ └────────────────────────────────────────────────────────────┘ ``` ### 3.3 Library Pages **Library Browse — Route:** `/agents/:slug/library` ``` ┌────────────────────────────────────────────────────────────┐ │ [← Agents] Agent Alpha [Settings ⚙] │ │ [Overview] [Memories] [■ Library] [Skills] │ │ │ │ ┌──────────┐ ┌──────────────────────────────────────┐ │ │ │ FOLDERS │ │ Library │ │ │ │ │ │ [+ New Document] [Upload] [New Folder]│ │ │ │ ▼ All │ │ [Search Library] │ │ │ │ Guides │ │ │ │ │ │ Refs │ │ 📁 Guides (4) │ │ │ │ Uploads│ │ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ │ │ Brand Voice │ │ Product Desc │ │ │ │ │ Drafts(1)│ │ │ Guidelines │ │ Template │ │ │ │ │ │ │ │ Updated 2d │ │ Updated 1w │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ │ │ ┌──────────────┐ ┌──────────────┐ │ │ │ │ │ │ │ Customer FAQ │ │ Response │ │ │ │ │ │ │ │ Handbook │ │ Tone Matrix │ │ │ │ │ │ │ │ Updated 3w │ │ Updated 1mo │ │ │ │ │ │ │ └──────────────┘ └──────────────┘ │ │ │ │ │ │ │ │ │ │ │ │ 📁 References (7) │ │ │ │ │ │ 📁 Uploads (12) │ │ │ │ │ │ │ │ │ └──────────┘ └──────────────────────────────────────┘ │ └────────────────────────────────────────────────────────────┘ ``` **Document Reader — Route:** `/agents/:slug/library/:path` ``` ┌────────────────────────────────────────────────────────────┐ │ ← Library > Guides [Edit] [Share] [···] │ │ │ │ Brand Voice Guidelines │ │ Last saved by Agent Alpha · 2 days ago · 12 saves │ │ Contributors: Agent Alpha, Sarah │ │ │ │ ═══════════════════════════════════════════════════════ │ │ │ │ TABLE OF CONTENTS │ │ │ │ 1. Our Brand Voice │ │ 1. Our Brand Voice │ │ │ 2. Tone Principles │ Our brand voice is confident, │ │ 3. Writing Examples │ clear, and human. We speak to our │ │ 4. Do's and Don'ts │ customers as trusted advisors, │ │ │ not as salespeople. Every word │ │ │ should feel like it comes from │ │ │ someone who genuinely understands │ │ │ the customer's needs. │ │ │ │ │ │ 2. Tone Principles │ │ │ │ │ │ 2.1 Confidence Without Arrogance │ │ │ ... │ │ │ │ │ ───────────────────────────────────────────────────────── │ │ │ │ ANNOTATIONS (2) │ │ Sarah · on section 2.1: "Consider adding examples for │ │ customer-facing emails specifically." │ │ │ │ REFERENCED BY │ │ 3 memories · 1 skill │ │ │ └────────────────────────────────────────────────────────────┘ ``` **Document Edit Mode:** ``` ┌────────────────────────────────────────────────────────────┐ │ ← Library > Guides [Discard] [Save] (Ctrl+S) │ │ │ │ ✎ Editing: Brand Voice Guidelines │ │ Auto-saved 30 seconds ago │ │ │ │ ═══════════════════════════════════════════════════════ │ │ │ │ [Toolbar: Bold | Italic | H1 H2 H3 | List | Link | ···] │ │ │ │ 1. Our Brand Voice │ │ │ │ Our brand voice is confident, clear, and human. We speak │ │ to our customers as trusted advisors, not as salespeople. │ │ Every word should feel like it comes from someone who │ │ genuinely understands the customer's needs. │ │ │ │ | ← cursor │ │ │ └────────────────────────────────────────────────────────────┘ ``` **Edit History — Route:** `/agents/:slug/library/:path/history` ``` ┌────────────────────────────────────────────────────────────┐ │ ← Brand Voice Guidelines │ │ │ │ Edit History │ │ │ │ ┌─ March 16 ────────────────────────────────────────────┐ │ │ │ Agent Alpha · 2:15 PM │ │ │ │ Updated tone principles with new examples │ │ │ │ [View this version] [Compare with current] │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌─ March 14 ────────────────────────────────────────────┐ │ │ │ Sarah · 10:30 AM │ │ │ │ Added Do's and Don'ts section │ │ │ │ [View this version] [Compare with current] │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ ┌─ March 10 ────────────────────────────────────────────┐ │ │ │ Agent Alpha · 4:00 PM │ │ │ │ Created document from brand analysis │ │ │ │ [View this version] │ │ │ └───────────────────────────────────────────────────────┘ │ │ │ │ [Restore a previous version ▼] │ └────────────────────────────────────────────────────────────┘ ``` **Compare Changes View:** ``` ┌────────────────────────────────────────────────────────────┐ │ ← Edit History │ │ │ │ Comparing: March 14 version → Current │ │ [Side by side] [Inline] │ │ │ │ ═══════════════════════════════════════════════════════ │ │ │ │ MARCH 14 VERSION │ CURRENT VERSION │ │ │ │ │ 2. Tone Principles │ 2. Tone Principles │ │ │ │ │ 2.1 Confidence Without │ 2.1 Confidence Without │ │ Arrogance │ Arrogance │ │ State facts clearly. │ State facts clearly. │ │ │ ┌─────────────────────────┐ │ │ │ │ For example, say "Our │ │ │ │ │ product handles 10K │ │ │ │ │ requests" not "Our │ │ │ │ │ product is the best." │ │ │ │ └─────────────────────────┘ │ │ │ (added) │ │ │ │ └────────────────────────────────────────────────────────────┘ ``` ### 3.4 Skills Pages **Skills List — Route:** `/agents/:slug/skills` ``` ┌────────────────────────────────────────────────────────────┐ │ [← Agents] Agent Alpha [Settings ⚙] │ │ [Overview] [Memories] [Library] [■ Skills] │ │ │ │ Skills (8) [+ New Skill] [Browse Shared]│ │ │ │ COMMUNICATION │ │ ┌────────────────────────────────────────────────────┐ │ │ │ ⚡ Write Product Description │ │ │ │ Auto · Last used 2 hours ago │ │ │ ├────────────────────────────────────────────────────┤ │ │ │ ⚡ Compose Email Response │ │ │ │ Manual · Last used yesterday │ │ │ ├────────────────────────────────────────────────────┤ │ │ │ ⚡ Summarize Customer Feedback │ │ │ │ Scheduled (daily) · Last run today │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ RESEARCH │ │ ┌────────────────────────────────────────────────────┐ │ │ │ ⚡ Analyze Competitor Pricing │ │ │ │ Manual · Last used 3 days ago │ │ │ ├────────────────────────────────────────────────────┤ │ │ │ ⚡ Compile Market Trends │ │ │ │ Scheduled (weekly) · Last run Monday │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ CONTENT │ │ ... │ └────────────────────────────────────────────────────────────┘ ``` **Skill Detail — Route:** `/agents/:slug/skills/:id` ``` ┌────────────────────────────────────────────────────────────┐ │ ← Back to Skills [Edit] [Share] [Duplicate] │ │ │ │ ⚡ Write Product Description │ │ Generates a compelling product description based on │ │ product details and target audience. │ │ │ │ Trigger: Automatic Category: Communication│ │ Last used: 2 hours ago (for "Wireless Charging Pad") │ │ │ │ ═══════════════════════════════════════════════════════ │ │ │ │ WHAT IT NEEDS │ │ ┌────────────────────────────────────────────────────┐ │ │ │ Product Name .............. required │ │ │ │ Key Features .............. required (up to 5) │ │ │ │ Target Audience ........... optional (general) │ │ │ │ Tone ...................... optional (professional) │ │ │ │ Max Length ................ optional (200 words) │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ STEPS │ │ 1. Analyze the product features and identify top 3 │ │ differentiators │ │ 2. Determine the emotional benefit for the target audience│ │ 3. Write an opening hook that addresses the audience need │ │ 4. Describe features as benefits, leading with strongest │ │ 5. Close with a call to action appropriate to context │ │ │ │ TEMPLATE │ │ ┌────────────────────────────────────────────────────┐ │ │ │ {hook_sentence} │ │ │ │ │ │ │ │ {product_name} is designed for {audience_need}. │ │ │ │ {benefit_1}. {benefit_2}. {benefit_3}. │ │ │ │ │ │ │ │ {call_to_action} │ │ │ └────────────────────────────────────────────────────┘ │ │ │ │ EXAMPLE │ │ Input: Product="AirPods Max", Audience="audiophiles" │ │ Output: "Hear every detail the artist intended..." │ │ │ │ ───────────────────────────────────────────────────────── │ │ │ │ USAGE HISTORY │ │ March 18 · Wireless Charging Pad · Completed │ │ March 15 · Smart Thermostat · Completed │ │ March 12 · Ergonomic Keyboard · Completed │ │ │ └────────────────────────────────────────────────────────────┘ ``` --- ## 4. Knowledge Library Spec ### 4.1 Document Lifecycle ``` CREATE EDIT SHARE │ │ │ ├─ New (blank) ├─ Inline editing ├─ Add to Commons ├─ Upload (file) ├─ Auto-save ├─ Privacy review └─ From template ├─ Manual save (Ctrl+S) ├─ Sync or copy └─ Draft (for major edits) └─ Publish draft │ VERSIONING │ ├─ Edit History (auto) ├─ Compare changes ├─ View previous version ├─ Restore previous version └─ Named versions (manual) ``` ### 4.2 Document Creation Flows **Flow 1: New blank document** 1. User clicks "+ New Document" in Library 2. Inline editor opens with cursor in title field 3. User types title, presses Enter, begins writing content 4. System auto-saves periodically; user can also save manually (Ctrl+S) 5. User selects or creates a folder for the document 6. Document appears in the Library browse view **Flow 2: Upload a file** 1. User clicks "Upload" in Library 2. File picker opens; user selects file (PDF, image, text, markdown) 3. System stores the file and generates a preview 4. For text-based files, the content is editable inline 5. For binary files (PDF, images), the file is viewable with metadata editable 6. User assigns to a folder **Flow 3: From template** 1. User clicks "+ New Document" and selects "From template" 2. System shows available templates (from Skills that have templates, or predefined library templates) 3. User selects a template; a new document is created with the template content pre-filled 4. User edits and saves ### 4.3 Document Editing Rules | Context | Edit behavior | Vocabulary | |---------|--------------|------------| | Private vault, sole editor | Direct edit, immediate save | "Save" | | Private vault, agent also editing | Edit with notification ("Agent Alpha is also editing") | "Save" (auto-merge if no conflict) | | Commons, user is contributor | Draft mode by default; changes not visible until published | "Draft" → "Publish" | | Commons, user is reader | Read-only view | (no edit actions) | | Conflict (both edited same section) | Side-by-side resolution UI | "Your changes" vs "Their changes" → "Resolve" | ### 4.4 Named Versions For important milestones, owners can create a **Named Version** (stored as a Git tag/release): - Click "Create Version" on any document - Enter a version name: "Brand Guidelines v3" or "Q2 Final" - The version is frozen — it becomes a permanent snapshot - Users can browse to any named version from the Edit History - Named versions appear as special markers in the history timeline This replaces Git's release/tag concept with a simple "save this as a named version" action. --- ## 5. Skills Workbench Spec ### 5.1 Skill Anatomy ```yaml # Stored as a structured file in /skills/{category}/{skill-name}.md name: Write Product Description description: Generates a compelling product description... trigger: automatic category: communication parameters: - name: Product Name required: true - name: Key Features required: true description: List of up to 5 features - name: Target Audience required: false default: general consumer - name: Tone required: false default: professional - name: Max Length required: false default: 200 words steps: 1: Analyze the product features and identify top 3 differentiators 2: Determine the emotional benefit for the target audience 3: Write an opening hook that addresses the audience need 4: Describe features as benefits, leading with the strongest 5: Close with a call to action appropriate to the context template: | {hook_sentence} {product_name} is designed for {audience_need}. {benefit_1}. {benefit_2}. {benefit_3}. {call_to_action} examples: - input: product: AirPods Max audience: audiophiles tone: enthusiast output: "Hear every detail the artist intended..." ``` ### 5.2 Skill Creation Flow 1. User clicks "+ New Skill" in Skills section 2. Minimal creation form appears: - Name (required) - Description (required) - Category (optional, can create new) 3. User clicks "Create" — skill is created with just name and description 4. Skill detail page opens in edit mode 5. User can add Steps, Parameters, Template, and Examples using smart blocks 6. Each block type is inserted via a "+" button or "/" command: - `/step` — adds a numbered step - `/param` — adds a parameter definition - `/template` — adds a template block - `/example` — adds an example input/output pair 7. All changes auto-save ### 5.3 Skill Sharing and Adoption **Sharing a skill to Commons:** 1. Owner clicks "Share with team" on a skill 2. Selects target Commons 3. Skill is copied to the Commons Skills section with attribution 4. Skill detail in Commons shows "Shared by Agent Alpha's owner" **Adopting a shared skill:** 1. Owner browses Commons Skills section (or uses "Browse Shared" from vault Skills) 2. Finds a skill and clicks "Add to [Agent Name]" 3. Skill is copied to the agent's vault 4. If the shared version is later updated, the adopted copy shows a subtle notification: "Updated version available" with an "Update" action **Skill versioning:** - Skills are files, so every save creates a version in the edit history - Owners can view the skill's edit history and restore previous versions - Named versions work the same as for documents --- ## 6. Revised Navigation ### 6.1 Sidebar Structure ``` [KnowHub Logo] [Global Search — Cmd+K] ── OVERVIEW ────────────── Home Activity ── MY AGENTS ───────────── All Agents ★ Agent Alpha (pinned) ★ Agent Beta (pinned) ── SHARED SPACES ───────── All Spaces ★ Marketing Library (pinned) ★ Q2 Project (pinned) + New Shared Space ── SYSTEM ──────────────── Settings ``` ### 6.2 Content Area Navigation (when inside an agent) ``` [← Agents] Agent Alpha [Settings ⚙] ┌────────────────────────────────────────────────────────────┐ │ [Overview] [Memories] [Library] [Skills] │ └────────────────────────────────────────────────────────────┘ [Content area for selected tab] ``` ### 6.3 Content Area Navigation (when inside a Commons) ``` [← Shared Spaces] Marketing Library [Settings ⚙] ┌────────────────────────────────────────────────────────────┐ │ [Overview] [Library] [Skills] [Activity] [Members] │ └────────────────────────────────────────────────────────────┘ [Content area for selected tab] ``` ### 6.4 Complete Sitemap ``` KnowHub ├── Home (Dashboard) │ ├── Needs Attention (alerts) │ ├── Recent Activity (cross-agent feed) │ └── Overview Cards (memories / library / skills) │ ├── Activity Feed (global timeline) │ ├── Global Search (Cmd+K command palette + dedicated page) │ ├── My Agents │ ├── All Agents (grid/list with pinning) │ └── [Agent Detail] │ ├── Overview (default tab) │ ├── Memories (tab) │ │ └── [Memory Detail] (side panel or full page) │ ├── Library (tab) │ │ ├── [Folder contents] │ │ └── [Document Detail] │ │ ├── Reader View │ │ ├── Edit Mode │ │ ├── Edit History │ │ └── Compare Changes │ ├── Skills (tab) │ │ └── [Skill Detail] │ │ ├── View Mode │ │ ├── Edit Mode │ │ └── Usage History │ └── Settings │ ├── Agent Profile │ ├── Memory Policies │ ├── Privacy & Access │ └── Library Settings │ ├── Shared Spaces │ ├── All Spaces (directory with search) │ ├── + New Shared Space (creation flow) │ └── [Shared Space Detail] │ ├── Overview (default tab) │ ├── Library (tab — primary) │ │ ├── [Folder contents] │ │ └── [Document Detail] │ ├── Skills (tab) │ │ └── [Skill Detail] │ ├── Activity (tab — shared observations) │ ├── Members (tab) │ │ ├── Member List │ │ ├── Role Management │ │ └── Invite │ └── Settings │ ├── General (name, purpose) │ ├── Policies (sharing rules) │ └── Danger Zone (archive/delete) │ └── Settings ├── Account (profile, auth) ├── Privacy & Security (defaults, audit log) ├── Agents (register, manage, API keys) ├── Notifications (alerts, email, thresholds) └── Integrations (connected services, webhooks) ``` ### 6.5 Navigation Depth | Depth | What lives here | Example | |-------|----------------|---------| | 1 | Global sections | Home, Activity, Agents, Shared Spaces, Settings | | 2 | Entity pages | Agent Alpha, Marketing Library | | 3 | Section tabs + items | Memories, Library, Skills; or Memory Detail, Document Detail | | 4 | Sub-views (max depth) | Edit History, Compare Changes | Maximum depth is 4, reached only for document versioning views. All primary interactions are at depth 2-3. --- ## 7. Cross-linking Model ### 7.1 Link Types | Link | Direction | Storage | Display | |------|-----------|---------|---------| | Memory → Document | Memory references a document as source or related material | Issue body contains file path reference | "Related: [Document Name]" in memory detail | | Memory → Skill | Memory records using a skill or learning from skill execution | Issue body contains skill reference | "Used skill: [Skill Name]" in memory detail | | Memory → Memory | Memories reinforce or contradict each other | Issue-to-issue reference | "Related memories" section | | Document → Document | Inline content links | Standard markdown links with internal paths | Clickable inline links | | Skill → Document | Skill references a template or reference document | Skill file contains document path | "Uses template: [Document Name]" in skill detail | ### 7.2 Auto-linking Rules 1. When an agent creates a memory that references a document by name, the system auto-creates a Memory → Document link 2. When an agent uses a skill, the system auto-creates a Memory → Skill link in the resulting memory 3. When a user types `@` in a document editor, the system suggests other documents, memories, and skills for inline linking 4. All auto-links can be manually removed by the owner ### 7.3 Reverse References Every item shows its reverse references (what links to it): - **Document detail:** "Referenced by N memories, M skills" - **Skill detail:** "Used in N memories" - **Memory detail:** "Related: N documents, M skills, K memories" In Commons, reverse references from private vaults are shown as aggregate counts only ("Referenced by 4 agents") to preserve privacy. --- ## 8. Commons Sharing Model ### 8.1 Sharing Flows by Content Type | Content Type | Action Label | Flow | Result in Commons | |-------------|-------------|------|-------------------| | Memory | "Share observation" | One-step: select Commons → confirm | Read-only entry in Activity Log with attribution | | Document | "Add to shared library" | Two-step: select Commons → privacy review → publish | Editable document in Commons Library | | Skill | "Share with team" | One-step: select Commons → confirm | Adoptable skill in Commons Skills | ### 8.2 Document Sharing Options When sharing a document to a Commons: | Option | Behavior | Use case | |--------|----------|----------| | **Synced copy** | Changes in vault propagate to Commons and vice versa | Living documents that the team references | | **Independent copy** | One-time copy; vault and Commons versions diverge | Documents that need team-specific customization | | **Read-only share** | Commons members can read but not edit | Reference-only materials | ### 8.3 Skill Adoption 1. Shared skills appear in Commons Skills section 2. Any Commons member's owner can "Add to [Agent]" — creates a private copy 3. The private copy is independent but tracks its origin 4. When the shared source is updated, adopted copies show "Updated version available" 5. Owner can "Update" (replace with new version) or "Ignore" (keep current version) ### 8.4 Privacy Review Flow (Document Sharing) ``` STEP 1: Select destination "Add to shared library" → select Commons STEP 2: Review content Full document preview with ability to: - Redact sensitive sections (replaced with "[Redacted]") - Edit content before sharing - Choose sharing mode (synced / independent / read-only) STEP 3: Confirm Summary of what will be shared, to whom, with what permissions [Cancel] [Add to Library] ``` --- ## 9. API-to-UI Mapping ### 9.1 Memory Operations (Issue-Backed) | User Action | UI Element | API Operation | Git Reality | |------------|-----------|---------------|-------------| | View memory stream | Memories tab | `GET /memories?sort=created_desc` | List issues | | View memory detail | Click memory card | `GET /memories/:id` | Get issue | | Create memory | "+ New Memory" | `POST /memories` | Create issue | | Edit memory | "Edit" on memory detail | `PUT /memories/:id` | Update issue | | Add comment | Comment box on memory | `POST /memories/:id/comments` | Create issue comment | | Tag memory | Tag editor on memory | `PUT /memories/:id/tags` | Update issue labels | | Change status | Status selector | `PUT /memories/:id/status` | Update issue state | | Archive memory | "Archive" button | `PUT /memories/:id/status` (archived) | Close issue | | Delete memory | "Delete" button | `DELETE /memories/:id` | Delete issue | | Search memories | Search in Memories tab | `GET /search?scope=memories&q=...` | Search issues | | Filter by tag | Tag filter sidebar | `GET /memories?tag=...` | Filter issues by label | | Share observation | "Share observation" | `POST /commons/:id/observations` | Create issue in shared repo | ### 9.2 Document Operations (File-Backed) | User Action | UI Element | API Operation | Git Reality | |------------|-----------|---------------|-------------| | Browse library | Library tab | `GET /library/` | List directory tree | | Open folder | Click folder | `GET /library/:path/` | List directory | | Read document | Click document card | `GET /library/:path` | Read file | | Create document | "+ New Document" | `POST /library/:path` | Create file + commit | | Edit document | "Edit" button | `PUT /library/:path` | Update file + commit | | Save | Ctrl+S or "Save" | `PUT /library/:path` | Commit | | Upload file | "Upload" button | `POST /library/:path` (multipart) | Create file + commit | | Create folder | "New Folder" | `POST /library/:path/` | Create directory | | View edit history | "Edit History" link | `GET /library/:path/history` | Git log for file | | View specific version | "View this version" | `GET /library/:path?version=:sha` | Get file at commit | | Compare changes | "Compare with current" | `GET /library/:path/compare?from=:sha&to=:sha` | Git diff | | Restore version | "Restore" | `PUT /library/:path` (with version content) | Commit old content as new | | Create draft | "Edit" on shared doc | `POST /library/:path/drafts` | Create branch | | Publish draft | "Publish" button | `POST /library/:path/drafts/:id/publish` | Merge branch | | Create named version | "Create Version" | `POST /library/:path/versions` | Create tag/release | | Delete document | "Delete" | `DELETE /library/:path` | Delete file + commit | | Share to Commons | "Add to shared library" | `POST /commons/:id/library/:path` | Copy file to shared repo | ### 9.3 Skill Operations (File-Backed) | User Action | UI Element | API Operation | Git Reality | |------------|-----------|---------------|-------------| | List skills | Skills tab | `GET /skills/` | List /skills/ directory | | View skill | Click skill card | `GET /skills/:id` | Read file in /skills/ | | Create skill | "+ New Skill" | `POST /skills/` | Create file in /skills/ + commit | | Edit skill | "Edit" button | `PUT /skills/:id` | Update file + commit | | Duplicate skill | "Duplicate" | `POST /skills/` (with source content) | Create new file + commit | | View edit history | "Edit History" | `GET /skills/:id/history` | Git log for skill file | | Share skill | "Share with team" | `POST /commons/:id/skills/` | Copy file to shared repo | | Add shared skill | "Add to [Agent]" | `POST /skills/` (from shared source) | Copy file from shared repo | | Update from shared | "Update" | `PUT /skills/:id` (from shared source) | Copy updated file + commit | | Delete skill | "Delete" | `DELETE /skills/:id` | Delete file + commit | --- ## 10. Visual Design Updates ### 10.1 Design Principles (Kenya Hara's Direction) 1. **Distinct atmospheres, unified architecture.** Each content type has its own visual atmosphere (warm/cool/active) but they share the same structural language (grid, typography family, interaction patterns). Moving between sections feels like moving between rooms in the same building. 2. **Content over chrome.** The interface recedes so content can breathe. Minimal toolbars, hidden-until-needed actions, generous whitespace. A document should feel like reading a book, not operating a control panel. 3. **Purposeful emptiness.** Empty states are not errors — they are invitations. An empty library is a shelf waiting to be filled. An empty memory stream is a mind waiting to learn. The empty state text is gentle and forward-looking, never apologetic. 4. **Soft differentiation.** Colors are washes, not flags. The amber tint of the memory stream is felt more than seen. The cool blue of the library creates calm without calling attention to itself. Differentiation serves orientation, not decoration. 5. **Time as a design element.** The memory stream flows downward with time. Edit history flows downward with time. Activity feeds flow downward with time. Time is the universal organizing principle, and its direction (newest at top) is consistent everywhere. ### 10.2 Color System **Base Palette:** - Background: `#FAFAFA` (light mode), `#1A1A1E` (dark mode) - Surface: `#FFFFFF` (light), `#242428` (dark) - Text Primary: `#1A1A1E` (light), `#F0F0F0` (dark) - Text Secondary: `#6B6B76` (light), `#9B9BA6` (dark) - Border: `#E5E5EA` (light), `#38383D` (dark) **Memory Palette:** - Tint: `#FDF8F0` (light), `#1E1A16` (dark) - Accent: `#D4A574` (light), `#B8864E` (dark) - Deep: `#8B6914` - Badge Background: `#FFF3E0` (light), `#2A2218` (dark) **Library Palette:** - Tint: `#F5F7FA` (light), `#16181E` (dark) - Accent: `#4A6FA5` (light), `#6B8EC4` (dark) - Deep: `#2C3E6B` - Badge Background: `#E3F2FD` (light), `#1A2030` (dark) **Skills Palette:** - Tint: `#F3F8F3` (light), `#161E16` (dark) - Accent: `#5B8C5A` (light), `#7BAA7A` (dark) - Deep: `#2D5A3D` - Badge Background: `#E8F5E9` (light), `#1A261A` (dark) **System Palette:** - Info: `#4A6FA5` - Warning: `#D4A574` - Error: `#C5493D` - Success: `#5B8C5A` ### 10.3 Typography **Typeface:** A clean, humanist sans-serif (e.g., Inter, or a system font stack). | Element | Weight | Size | Line Height | Usage | |---------|--------|------|-------------|-------| | Page Title | Semibold | 24px | 32px | Page headings | | Section Title | Medium | 18px | 24px | Section headings within a page | | Card Title | Medium | 15px | 20px | Memory card titles, document names | | Body Text | Regular | 14px | 22px | Content, descriptions | | Body Text (Document) | Regular | 16px | 28px | Document reader body (larger for readability) | | Small Text | Regular | 12px | 16px | Timestamps, metadata, tags | | Code/Parameter | Mono Regular | 13px | 18px | Skill parameters, template syntax | ### 10.4 Spacing and Layout - **Base unit:** 4px - **Component spacing:** 8px (tight), 16px (standard), 24px (relaxed), 32px (section) - **Memory stream:** 16px gap between cards. Cards have 16px internal padding. - **Library grid:** 24px gutter between document cards. Cards have 20px internal padding. - **Skills list:** 0px gap between skill rows (border-separated). Rows have 12px vertical padding. - **Document reader:** 40px side margins. Maximum content width of 680px for optimal reading line length. - **Sidebar width:** 240px (collapsible to 56px icon-only mode) ### 10.5 Motion Design | Interaction | Animation | Duration | Easing | |------------|-----------|----------|--------| | New memory appears in stream | Fade up + slide from top | 300ms | ease-out | | Tab switch | Content crossfade | 200ms | ease-in-out | | Side panel open | Slide from right | 250ms | ease-out | | Document edit mode toggle | Gentle transform of header area | 200ms | ease-in-out | | Sharing confirmation | Scale up + fade in (modal) | 200ms | ease-out | | Page navigation | Crossfade | 150ms | ease-in-out | | Skill "ready" pulse | Border glow (0.2 opacity → 0 opacity) | 2000ms | ease-in-out, loop | ### 10.6 Empty States **Empty Memory Stream:** ``` ○ No memories yet. As your agent works and learns, its experiences will appear here. ``` **Empty Library:** ``` □ Your library is empty. Add documents to give your agent reference material. [+ Add Document] ``` **Empty Skills:** ``` ⚡ No skills yet. Teach your agent workflows and templates to expand what it can do. [+ Create Skill] ``` ### 10.7 Privacy-Aware Chrome | Context | Header Treatment | Indicator | |---------|-----------------|-----------| | Agent Vault (private) | Standard header | 🔒 "Private" subtle text next to agent name | | Commons (shared) | Standard header | 👥 "Shared with N members" subtle text next to space name | | Privacy Review (sharing) | Amber overlay on header | ⚠ "Reviewing before sharing" prominent banner | | Draft mode (editing shared doc) | Dashed border on content area | "Draft — only you can see these changes" banner | --- ## Appendix A: Migration from V1 Concepts For teams implementing the transition from V1 to V2: | V1 Element | V2 Replacement | Migration Path | |-----------|---------------|----------------| | Entry (type: memory) | Memory | Rename; move to Memory Stream section | | Entry (type: knowledge) | Document | Convert from issue to file; place in Library | | Entry (type: skill) | Skill | Convert from issue to file; place in Skills | | Entry (type: note) | Comment or Annotation | Attach to parent memory or document | | Notebook | Folder (Library) or Category (Skills) | Convert to directory structure | | Message | Comment | Rename; keep as issue comment | | Entry Detail page | Memory Detail, Document Reader, or Skill Detail | Route to type-specific detail page | | Unified search results | Type-segmented search results | Group results by type with distinct styling | | Entry creation flow | Three distinct creation flows | Route to type-specific creation based on context | ## Appendix B: Summary of Key Design Decisions 1. **Three content types, three storage patterns, three visual identities.** Memory (issue-backed, warm amber), Document (file-backed, cool blue), Skill (file-backed, sage green). 2. **No developer terminology ever.** Save, not commit. Draft, not branch. Publish, not merge. Edit History, not git log. Library, not repository. 3. **Notebooks eliminated.** Replaced by native organization: tags for memories, folders for documents, categories for skills. 4. **Minimal creation fields.** Memory: content + tags. Document: title + content. Skill: name + description. Everything else is progressive disclosure. 5. **Different sharing flows per type.** "Share observation" (memory, lightweight), "Add to shared library" (document, with privacy review), "Share with team" (skill, copy-based). 6. **Cross-linking is gentle and contextual.** "Related" sections, not graph visualizations. Auto-detected, manually adjustable. Privacy-respecting in shared contexts. 7. **The product's essence:** KnowHub gives an AI agent a complete, persistent mind that its owner can see into, shape, and trust.