docs: add agent-specific knowledge base documentation

- Document isolated knowledge storage per agent
- Add folder structure diagram showing agent separation
- Explain agent isolation benefits and switching workflow
- Fix command syntax for agent usage and knowledge commands

Author: kennvene-aws

docs/knowledge-management.md

@@ -166,6 +166,66 @@ Configure knowledge base behavior:
 `q settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.md"]'` # Default include patterns
 `q settings knowledge.defaultExcludePatterns '["target/**", "node_modules/**"]'` # Default exclude patterns
 
+## Agent-Specific Knowledge Bases
+
+### Isolated Knowledge Storage
+
+Each agent maintains its own isolated knowledge base, ensuring that knowledge contexts are scoped to the specific agent you're working with. This provides better organization and prevents knowledge conflicts between different agents.
+
+### Folder Structure
+
+Knowledge bases are stored in the following directory structure:
+
+```
+~/.q/knowledge_bases/
+├── q_cli_default/          # Default agent knowledge base
+│   ├── contexts.json       # Metadata for all contexts
+│   ├── context-id-1/       # Individual context storage
+│   │   ├── data.json       # Semantic search data
+│   │   └── bm25_data.json  # BM25 search data (if using Fast index)
+│   └── context-id-2/
+│       ├── data.json
+│       └── bm25_data.json
+├── my-custom-agent/        # Custom agent knowledge base
+│   ├── contexts.json
+│   ├── context-id-3/
+│   │   └── data.json
+│   └── context-id-4/
+│       └── data.json
+└── another-agent/          # Another agent's knowledge base
+    ├── contexts.json
+    └── context-id-5/
+        └── data.json
+```
+
+### How Agent Isolation Works
+
+- **Automatic Scoping**: When you use `/knowledge` commands, they automatically operate on the current agent's knowledge base
+- **No Cross-Agent Access**: Agent A cannot access or search knowledge contexts created by Agent B
+- **Independent Configuration**: Each agent can have different knowledge base settings and contexts
+- **Migration Support**: Legacy knowledge bases are automatically migrated to the default agent on first use
+
+### Agent Switching
+
+When you switch between agents, your knowledge commands will automatically work with that agent's specific knowledge base:
+
+```bash
+# Working with default agent
+/knowledge add /path/to/docs
+
+# Switch to custom agent
+q chat --agent my-custom-agent
+
+# This creates a separate knowledge base for my-custom-agent
+/knowledge add /path/to/agent/docs
+
+# Switch back to default
+q chat
+
+# Only sees the original project-docs, not agent-specific-docs
+/knowledge show
+```
+
 ## How It Works
 
 #### Indexing Process