iron-edge 1.0.0

package/squads/squad-claude/knowledge-base/knowledge-architecture-reference.md

@@ -0,0 +1,403 @@
+# Knowledge Architecture Reference
+
+> GraphRAG, temporal knowledge graphs, ontologies, taxonomies, and PKM frameworks. Based on MS-009 Agentic Second Brain research (April 2026).
+
+---
+
+## Knowledge Architecture Fundamentals
+
+Knowledge architecture is the formal design of how knowledge is structured, classified, and related within a system. It determines:
+
+- **Findability:** How agents and humans locate relevant information
+- **Connectivity:** How ideas relate and form meaning networks
+- **Evolution:** How new knowledge integrates without fragmenting existing knowledge
+- **Reasoning:** How agents make inferences over stored knowledge
+
+**Without architecture:** A vault becomes a "knowledge cemetery" — information accumulated but inaccessible.
+
+---
+
+## Knowledge Organization Frameworks
+
+### Zettelkasten
+
+**Origin:** Niklas Luhmann, 1960-1990. Produced 70 books from ~90,000 interlinked notes.
+
+**Principles:**
+- **Atomicity:** One idea = one note
+- **Permanent notes:** Write in your own words, not copy-paste
+- **Links:** Every note connected to related notes
+- **Emergence:** Knowledge emerges from the network, not the hierarchy
+
+**For agents:** A-Mem (NeurIPS 2025) formally proved Zettelkasten-inspired memory outperforms flat storage in agentic contexts.
+
+```
+note-001.md: "Context windows limit agent working memory"
+  links_to: [note-042, note-007]
+  
+note-042.md: "Compaction preserves user requests but loses reasoning"
+  links_to: [note-001, note-089]
+  
+note-007.md: "CLAUDE.md content survives compaction"
+  links_to: [note-001, note-042]
+```
+
+### PARA Method
+
+**Origin:** Tiago Forte, Building a Second Brain (2022).
+
+| Folder | Contains | Lifespan |
+|--------|---------|---------|
+| **P**rojects | Active work with end date | Weeks-Months |
+| **A**reas | Ongoing responsibilities | Indefinite |
+| **R**esources | Reference material | Long-term |
+| **A**rchives | Completed/inactive items | Permanent |
+
+**For vaults:**
+```
+vault/
+├── Projects/    → Active sprints, current epics
+├── Areas/       → Squad capabilities, client relationships
+├── Resources/   → KB files, research, frameworks
+└── Archives/    → Completed stories, old research
+```
+
+### Evergreen Notes
+
+**Origin:** Andy Matuschak, 2019+.
+
+**Core principle:** Notes are "evergreen" when they:
+- Are written for future you (not just today)
+- Use concepts, not just references
+- Get updated as understanding deepens
+- Link to related evergreen notes
+
+**Difference from zettelkasten:** Evergreen emphasizes **continuous refinement**; zettelkasten emphasizes **density of connections**.
+
+### Maps of Content (MOC)
+
+Index notes that aggregate related topics. Not content themselves — navigation aids.
+
+```markdown
+# MOC: Claude Code Architecture
+
+## Core Systems
+- [[agent-loop]] — The fundamental while(true) loop
+- [[tool-system]] — 184 tools, 40 registered, ~20 enabled
+- [[memory-architecture]] — 3-layer: MEMORY.md + topics + transcripts
+
+## Context Management
+- [[compaction-system]] — 5-layer pipeline
+- [[prompt-caching]] — 14 cache-break vectors
+- [[deferred-tools]] — 93% token reduction
+
+## Multi-Agent
+- [[coordinator-mode]] — 4-phase orchestration
+- [[fork-model]] — Cache-sharing for parallelism
+- [[worktree-isolation]] — Git-based blast radius control
+```
+
+### Knowledge Graph
+
+Formal graph structure with nodes (entities) and edges (relationships).
+
+```
+Entities: Person, Concept, Project, Decision, Insight, Source
+Relations: relates-to, depends-on, contradicts, evolved-from, authored-by
+```
+
+**Best for:** Agentic systems where agents need to reason over structured knowledge.
+
+---
+
+## Ontology Design
+
+### What is an Ontology?
+
+A formal specification of concepts and relationships in a domain. The difference between a taxonomy (hierarchy) and an ontology (full semantic web of relationships).
+
+### Base Ontology for Second Brains
+
+```yaml
+entity_types:
+  - Person
+  - Organization
+  - Concept
+  - Project
+  - Decision
+  - Insight
+  - Source
+  - Tool
+  - Pattern
+
+relationship_types:
+  - relates-to        # bidirectional, general
+  - depends-on        # A cannot exist without B
+  - contradicts       # A and B are in tension
+  - evolved-from      # A is a refinement of B
+  - authored-by       # A was created by B
+  - applies-to        # A is applicable in context B
+  - invalidates       # A makes B obsolete
+  - supports          # A provides evidence for B
+  - implements        # A is a concrete realization of B
+```
+
+### Hybrid Ontology (Prescrita + Aprendida)
+
+**Prescrita:** Defined upfront — stable entity types, core relationships.
+
+**Aprendida:** LLMs extract new categories and relationships from usage patterns over time.
+
+**Graphiti implementation:**
+- Fixed ontology: defines core entity types and relationship types
+- Learned ontology: agent adds new relationship types as patterns emerge
+- Version tracking: ontology changes are versioned with timestamps
+
+### Over-Engineering Risks
+
+- Complex ontologies that neither humans nor agents can maintain
+- Rigid taxonomies that don't accommodate emergent knowledge
+- Tool-specific architectures that create lock-in
+- Inconsistency: outdated facts polluting the graph without invalidation mechanism
+
+---
+
+## GraphRAG Architecture
+
+### What is GraphRAG?
+
+Evolution of standard RAG (Retrieval-Augmented Generation) that incorporates a knowledge graph in the retrieval process.
+
+**Standard RAG:** Query → Vector similarity → Top-K chunks → Generate
+
+**GraphRAG:**
+```
+Query
+  → Vector similarity → Top-K chunks (semantic coverage)
+  → Entity extraction from query
+  → Graph traversal → Related entities and relations (structural precision)
+  → RRF fusion → Merged, ranked context
+  → Cross-encoder reranking → Final top-N
+  → LLM Generation
+```
+
+### Why GraphRAG Wins
+
+| Approach | Strength | Weakness |
+|----------|---------|----------|
+| Vector-only | Semantic nuance, edge cases | Misses exact matches, acronyms |
+| BM25-only | Exact matches, terminology | Misses semantic similarity |
+| Graph-only | Structural reasoning | Misses unstructured content |
+| GraphRAG (hybrid) | Best of all three | More complex to maintain |
+
+**Hybrid search reduces errors by 35-60% vs pure semantic retrieval.**
+
+### LazyGraphRAG (Microsoft, 2026)
+
+Index at the cost of vector RAG (0.1% of full GraphRAG cost) with comparable quality for global queries. Defers expensive graph analysis to query time.
+
+---
+
+## Temporal Knowledge Graphs
+
+### The Problem with Static Graphs
+
+Facts change over time. Without temporal modeling:
+- "X works at Company A" might be outdated
+- "Framework Y is the best choice" may no longer be true
+- Project statuses, team structures, technology choices all evolve
+
+### Bi-Temporal Model (Graphiti/Zep)
+
+Two time dimensions tracked per fact:
+
+```
+Fact edge:
+  content: "User prefers TypeScript over Python"
+  event_time: "2025-03-15"     ← When this was true in the world
+  ingestion_time: "2025-03-16" ← When we learned about it
+  valid_from: "2025-03-15"     ← Start of validity
+  valid_to: null               ← Still valid (null = current)
+  source: "user_statement_session_42"
+```
+
+**When conflict arises:**
+```
+Old fact: valid_to = new_fact.valid_from  (invalidated, not deleted)
+New fact: created with new valid_from
+```
+
+This preserves history while ensuring current queries return current state.
+
+### Temporal Query Patterns
+
+```python
+# Current facts only
+graph.query("preferences", temporal="current")
+
+# Historical view
+graph.query("preferences", temporal={"at": "2025-01-01"})
+
+# Change history
+graph.query("preferences", temporal="all_versions")
+
+# What changed this week
+graph.query("*", temporal={"since": "2025-03-10"})
+```
+
+---
+
+## Knowledge Quality Framework
+
+### Quality Score Formula
+
+```
+Quality Score = 
+  0.25 × accuracy +      # Verifiable facts? Sources cited?
+  0.20 × completeness +  # All sections filled? Links present?
+  0.20 × freshness +     # Time since last review
+  0.20 × utility +       # Retrieval frequency, user feedback
+  0.15 × connectivity    # Number and quality of links
+```
+
+**Score thresholds:**
+- >= 80: Evergreen (high confidence)
+- 60-79: Healthy (periodic review)
+- 40-59: Needs Attention
+- < 40: At Risk (candidate for archival)
+
+### Content Decay Types
+
+| Type | Example | Detection |
+|------|---------|-----------|
+| **Factual decay** | Framework version changed | Compare with external sources |
+| **Contextual decay** | Project was cancelled | Status field tracking |
+| **Relevance decay** | Topic no longer a priority | Usage analytics |
+| **Structural decay** | Broken links, obsolete tags | Graph validation |
+| **Temporal decay** | Note has date but no review deadline | Metadata check |
+
+### Knowledge Lifecycle
+
+```
+[DRAFT] 
+  → [REVIEWED] (validated by agent or human)
+  → [PUBLISHED] (stable, referenced by others)
+  → [EVERGREEN] (proven, highly connected)
+     |
+     ↓ (decay detected)
+  [NEEDS UPDATE]
+     |
+     ↓ (updated) or (abandoned)
+  [UPDATED] or [DEPRECATED]
+     |              |
+     ↓              ↓
+  [PUBLISHED]   [ARCHIVED]
+```
+
+---
+
+## Vector Database Decision Guide
+
+### Selection Criteria
+
+| Criterion | Consideration |
+|-----------|--------------|
+| Scale | How many vectors? (millions vs billions) |
+| Latency | P95 acceptable? (<50ms vs <100ms) |
+| Hybrid search | Native BM25 + vector support? |
+| Compliance | SOC 2, HIPAA required? |
+| Cost | Cloud managed vs self-hosted |
+| Ecosystem | Integration with existing tools |
+
+### Decision Matrix (2026)
+
+| Database | Best For | Scale | P95 | SOC 2 |
+|----------|---------|-------|-----|-------|
+| Pinecone | Enterprise, managed | Billions | <50ms | Yes |
+| Weaviate | Hybrid search native | 100s M | <100ms | Yes |
+| Qdrant | Performance/cost | 100s M | <100ms | Yes |
+| Chroma | Prototyping | Millions | Variable | No |
+| pgvector | PostgreSQL users | 5-100M | Variable | Inherits |
+| Milvus | Cost at scale | Billions | <50ms | No |
+
+**Strategy:** pgvector → Qdrant → Weaviate (as scale/requirements grow).
+
+---
+
+## Obsidian as Second Brain Infrastructure
+
+### Why Obsidian
+
+- **Local-first:** Files are plain markdown on your filesystem
+- **Plugin ecosystem:** 1,000+ community plugins
+- **Graph view:** Visual knowledge network
+- **Claude Code integration:** Vault can be working directory for agents
+- **No vendor lock-in:** Standard markdown, portable forever
+
+### Optimal Vault Structure
+
+```
+vault/
+├── 00-inbox/              # Quick capture, unprocessed
+├── 01-daily/              # Daily notes, session logs
+├── 02-projects/           # Active project notes
+├── 03-areas/              # Ongoing responsibilities
+├── 04-resources/          # Reference material
+├── 05-archive/            # Completed/inactive
+├── 06-templates/          # Note templates
+├── 07-agents/             # Agent configurations + memory
+├── 08-analytics/          # Vault health metrics
+├── _attachments/          # Images, PDFs, media
+├── _data/                 # Structured data (JSON, YAML)
+└── .obsidian/             # Config (theme, plugins, etc.)
+```
+
+### Claudian Integration (2026)
+
+Plugin embedding Claude Code as collaborator inside Obsidian:
+- Vault as agent working directory
+- Inline edit with diff preview
+- Slash commands/skills
+- @mentions for subagents and MCP servers
+- ~4K GitHub stars (April 2026)
+
+### obsidian-skills Starter Kit
+
+Official [obsidian-skills](https://github.com/kepano/obsidian-skills) (by Obsidian CEO Steph Ango):
+- Teaches agents to correctly handle wikilinks, frontmatter, Bases databases, JSON Canvas
+- Obsidian 1.12 CLI natively supports agent integration
+
+---
+
+## SINAPSE Knowledge Architecture
+
+### Current State
+
+SINAPSE uses a document-first approach:
+- Stories in `docs/stories/`
+- Architecture in `docs/architecture/`
+- KB files in `squads/{squad}/knowledge-base/`
+
+### Recommended Enhancements
+
+1. **MOC files** — Create index notes for each major domain in KB
+2. **Frontmatter standards** — Add `created_date`, `updated_date`, `review_by`, `status`, `links_to` to KB files
+3. **Quality scoring** — Periodic audit of KB files using quality formula
+4. **Decay detection** — Flag KB files not updated in 90+ days
+5. **Graph visualization** — Use `sinapse graph` to visualize knowledge connections
+
+### KB File Template
+
+```yaml
+---
+title: {Title}
+type: reference|guide|pattern|architecture
+status: draft|reviewed|published|evergreen|deprecated
+created: {date}
+updated: {date}
+review_by: {date}
+quality_score: {number}
+tags: [tag1, tag2]
+links_to: [file1.md, file2.md]
+---
+```

package/squads/squad-claude/knowledge-base/mcp-integration-patterns.md

@@ -0,0 +1,284 @@
+# MCP Integration Patterns
+
+## Overview
+
+The Model Context Protocol (MCP) extends Claude Code with tools from external services. MCP servers expose tools that Claude Code can invoke just like built-in tools. This guide covers transport types, setup patterns, security, and common integrations.
+
+## Transport Types
+
+### stdio (Standard I/O)
+
+**How it works:** Claude Code spawns a local process and communicates via stdin/stdout using JSON-RPC.
+
+**Best for:** Local CLI tools, language servers, file processors, custom scripts.
+
+**Configuration:**
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["/path/to/server.js"],
+      "env": {
+        "API_KEY": "${MY_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Characteristics:**
+- Fastest transport (no network overhead)
+- Process lifecycle managed by Claude Code
+- Environment variables for configuration
+- Works offline (for local-only tools)
+- One process per session
+
+### SSE (Server-Sent Events)
+
+**How it works:** Claude Code connects to a remote HTTP server that streams responses via Server-Sent Events.
+
+**Best for:** Remote services, shared servers, cloud-hosted tools, team-wide integrations.
+
+**Configuration:**
+```json
+{
+  "mcpServers": {
+    "remote-server": {
+      "type": "sse",
+      "url": "https://mcp.example.com/sse",
+      "headers": {
+        "Authorization": "Bearer ${MCP_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+**Characteristics:**
+- Network latency applies
+- Server managed externally (always running)
+- Authentication via headers
+- Supports multiple concurrent clients
+- Requires network access
+
+### Docker
+
+**How it works:** Claude Code runs an MCP server inside a Docker container, communicating via stdio or mapped ports.
+
+**Best for:** Isolated environments, servers with complex dependencies, security-sensitive tools, reproducible setups.
+
+**Configuration:**
+```json
+{
+  "mcpServers": {
+    "docker-server": {
+      "type": "stdio",
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "mcp/server-image:latest"],
+      "env": {
+        "DB_URL": "${DATABASE_URL}"
+      }
+    }
+  }
+}
+```
+
+**Characteristics:**
+- Full isolation (filesystem, network, processes)
+- Reproducible environment
+- Higher startup time (container launch)
+- Docker must be installed
+- Can map volumes for file access
+
+---
+
+## Transport Selection Guide
+
+| Factor | stdio | SSE | Docker |
+|--------|-------|-----|--------|
+| Latency | Lowest | Medium | Medium-High |
+| Security isolation | Low (same user) | High (network only) | Highest (container) |
+| Setup complexity | Low | Medium | Medium-High |
+| Offline capability | Yes | No | Yes (if image cached) |
+| Multi-user sharing | No | Yes | Possible |
+| Dependency management | Manual | Server-side | Container image |
+| Best use case | Local tools | Team services | Sensitive operations |
+
+---
+
+## Common MCP Servers
+
+### Supabase MCP
+
+**Purpose:** Database operations, migrations, edge functions, project management.
+
+**Tools provided:** `execute_sql`, `apply_migration`, `list_tables`, `get_logs`, `deploy_edge_function`, and 20+ more.
+
+**Setup:**
+```json
+{
+  "mcpServers": {
+    "supabase": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@supabase/mcp-server"],
+      "env": {
+        "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### GitHub MCP
+
+**Purpose:** Repository management, issues, PRs, code search, Actions.
+
+**Setup:**
+```json
+{
+  "mcpServers": {
+    "github": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+### Figma MCP
+
+**Purpose:** Design inspection, component discovery, design token extraction.
+
+**Tools provided:** `get_screenshot`, `get_metadata`, `get_design_context`, `get_code_connect_suggestions`.
+
+### Notion MCP
+
+**Purpose:** Document management, database queries, page creation and updates.
+
+**Tools provided:** `notion-search`, `notion-create-pages`, `notion-update-page`, `notion-fetch`.
+
+### Gmail MCP
+
+**Purpose:** Email reading, drafting, label management.
+
+**Tools provided:** `gmail_search_messages`, `gmail_read_message`, `gmail_create_draft`.
+
+### Context7
+
+**Purpose:** Library documentation lookup with up-to-date information.
+
+**Tools provided:** `resolve-library-id`, `get-library-docs`.
+
+---
+
+## Agent-as-MCP Pattern
+
+A Claude Code agent can be exposed as an MCP server, allowing other agents or systems to invoke it as a tool.
+
+**Architecture:**
+```
+External System → MCP Protocol → Agent Wrapper → Claude Code Agent → Result
+```
+
+**Use cases:**
+- Expose a code review agent as a CI/CD tool
+- Let other AI systems delegate to specialized Claude Code agents
+- Create reusable agent services across projects
+
+**Implementation approach:**
+1. Create an MCP server that wraps agent invocation
+2. Define tools that map to agent capabilities
+3. Handle authentication and rate limiting
+4. Return structured results
+
+---
+
+## Docker MCP Toolkit
+
+The Docker MCP Toolkit provides a managed way to run MCP servers in containers.
+
+**Key features:**
+- Pre-built images for common servers
+- Health monitoring and auto-restart
+- Network isolation between servers
+- Volume management for persistent data
+- Log aggregation
+
+**Setup:**
+```bash
+# Install Docker MCP gateway
+docker run -d --name mcp-gateway \
+  -p 8080:8080 \
+  -v /var/run/docker.sock:/var/run/docker.sock \
+  mcp/gateway:latest
+
+# Register a server
+curl -X POST http://localhost:8080/servers \
+  -d '{"name": "supabase", "image": "mcp/supabase:latest", "env": {"TOKEN": "..."}}'
+```
+
+---
+
+## Security Considerations
+
+### Environment Variable Management
+- NEVER hardcode secrets in settings.json
+- Use `${ENV_VAR}` syntax for variable substitution
+- Store secrets in .env files (gitignored) or OS keychain
+- Rotate API keys regularly
+
+### Network Security
+- SSE servers should use HTTPS only
+- Docker servers should use internal networks (not exposed to host)
+- Limit MCP server network access with Docker network policies
+- Monitor outbound connections from MCP servers
+
+### Tool-Level Permissions
+- Review which tools each MCP server exposes
+- Use Claude Code's permission system to restrict MCP tool access
+- Deny MCP tools that can modify production data in development environments
+- Log all MCP tool invocations for audit
+
+### Data Flow Security
+- Understand what data flows through each MCP server
+- Ensure sensitive data is not logged by MCP servers
+- Use encryption for data at rest and in transit
+- Comply with data residency requirements
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| "Server not found" | MCP config not in settings.json | Add server config to correct settings file |
+| "Connection refused" | Server not running / wrong port | Start server, check URL/port |
+| "Tool not found" | Server connected but tool not registered | Check server implements the tool, restart server |
+| "Authentication failed" | Invalid or expired token | Rotate token, check env var name |
+| "Timeout" | Server too slow | Increase timeout, check server performance |
+| "Permission denied" | Tool blocked by deny list | Update permissions in settings.json |
+
+### Diagnostic Commands
+
+```bash
+# Check if MCP server process is running (stdio)
+ps aux | grep mcp-server
+
+# Test SSE endpoint
+curl -N https://mcp.example.com/sse
+
+# Test Docker MCP container
+docker logs mcp-server-name
+
+# Verify environment variables
+echo $SUPABASE_ACCESS_TOKEN | head -c 10
+```