# floomhq/icontext architecture

> Architecture diagram of the GitHub repository floomhq/icontext, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/floomhq/icontext
- Repository: https://github.com/floomhq/icontext

## Overview

icontext is a local, shared Markdown memory vault for AI coding agents. The main workflow uses agent skills to gather evidence from Gmail, LinkedIn, or user input, synthesize and validate a profile, then write tiered profile files that Claude Code, Cursor, Codex, and OpenCode can share. Optional headless sync and MCP/retrieval extend that workflow; tier classification and encryption protect stored context. The README documents several skill-driven stages whose implementation is not represented by sampled Python source, so those links reflect documentation rather than inspected calls.

Main entry points: [`skills/icontext-populate-profile/SKILL.md`](https://github.com/floomhq/icontext/blob/main/skills/icontext-populate-profile/SKILL.md) (Populate Skill), [`cli.py`](https://github.com/floomhq/icontext/blob/main/cli.py) (Headless Sync), [`mcp/server.py`](https://github.com/floomhq/icontext/blob/main/mcp/server.py) (MCP Server), [`scripts/indexlib.py`](https://github.com/floomhq/icontext/blob/main/scripts/indexlib.py) (Local Retrieval)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_profile["Profile Workflow"]
  node_populate["Populate Skill<br/>[SKILL.md]"]
  node_refresh["Refresh Skill<br/>[SKILL.md]"]
  node_entity["Entity Extraction<br/>[SKILL.md]"]
  node_validation["Evidence Validation<br/>[gmail.py]"]
  node_render["Profile Rendering<br/>[gmail.py]"]
  node_sharecard["Share Card Skill<br/>[SKILL.md]"]
  node_writefact["Write Fact Skill<br/>[SKILL.md]"]
  node_headless["Headless Sync<br/>[cli.py]"]
end

subgraph group_sources["Data Sources"]
  node_gmail["Gmail Connector<br/>[gmail.py]"]
  node_linkedin["LinkedIn Connector<br/>[linkedin.py]"]
  node_selfdescribe["Self Description<br/>[SKILL.md]"]
end

subgraph group_vault["Vault and Security"]
  node_vault[("Tiered Markdown Vault")]
  node_classify["Sensitivity Classifier"]
  node_tierconfig["Tier Configuration<br/>[tiers.yml]"]
  node_encryption["Vault Encryption<br/>[sensitivity.yml]"]
end

subgraph group_access["Agent Access"]
  node_retrieval["Local Retrieval<br/>[indexlib.py]"]
  node_prompt_hook["Prompt Context Hook<br/>[prompt_context.py]"]
  node_mcp["MCP Server<br/>[server.py]"]
end

node_user(("User"))
node_agent(("AI Agent"))
node_gemini{{"Gemini API"}}
node_agents(("Coding Agents"))

node_user -->|"invokes"| node_populate
node_agent -->|"follows"| node_populate
node_populate -.->|"tries first"| node_gmail
node_populate -.->|"fallback source"| node_linkedin
node_populate -->|"fallback source"| node_selfdescribe
node_gmail -.->|"provides metadata"| node_entity
node_linkedin -.->|"provides profile"| node_entity
node_selfdescribe -->|"provides answers"| node_entity
node_entity -->|"filters evidence"| node_validation
node_validation -->|"validated entities"| node_render
node_populate -->|"synthesizes profile"| node_render
node_render -->|"writes Markdown"| node_vault
node_user -->|"requests update"| node_refresh
node_refresh -->|"updates profile"| node_vault
node_user -->|"requests summary"| node_sharecard
node_sharecard -->|"writes summary"| node_vault
node_user -->|"provides fact"| node_writefact
node_writefact -->|"routes fact"| node_vault
node_user -.->|"runs sync"| node_headless
node_headless -.->|"syncs source"| node_gmail
node_headless -.->|"syncs source"| node_linkedin
node_headless -.->|"requests synthesis"| node_gemini
node_headless -.->|"writes profile"| node_vault
node_tierconfig -->|"configures tiers"| node_classify
node_vault -->|"checks sensitivity"| node_classify
node_vault -->|"protects vault tier"| node_encryption
node_agents -->|"submits prompt"| node_prompt_hook
node_prompt_hook -->|"searches context"| node_retrieval
node_retrieval -->|"reads indexed files"| node_vault
node_agents -.->|"calls tools"| node_mcp
node_mcp -.->|"searches vault"| node_retrieval
node_mcp -.->|"reads and appends"| node_vault
node_mcp -.->|"rebuilds index"| node_retrieval
node_vault -->|"shared context"| node_agents

click node_gmail "https://github.com/floomhq/icontext/blob/main/connectors/gmail.py"
click node_linkedin "https://github.com/floomhq/icontext/blob/main/connectors/linkedin.py"
click node_selfdescribe "https://github.com/floomhq/icontext/blob/main/skills/icontext-populate-profile/SKILL.md"
click node_populate "https://github.com/floomhq/icontext/blob/main/skills/icontext-populate-profile/SKILL.md"
click node_refresh "https://github.com/floomhq/icontext/blob/main/skills/icontext-refresh-profile/SKILL.md"
click node_entity "https://github.com/floomhq/icontext/blob/main/skills/icontext-populate-profile/SKILL.md"
click node_validation "https://github.com/floomhq/icontext/blob/main/connectors/gmail.py"
click node_render "https://github.com/floomhq/icontext/blob/main/connectors/gmail.py"
click node_sharecard "https://github.com/floomhq/icontext/blob/main/skills/icontext-share-card/SKILL.md"
click node_writefact "https://github.com/floomhq/icontext/blob/main/skills/icontext-write-fact/SKILL.md"
click node_headless "https://github.com/floomhq/icontext/blob/main/cli.py"
click node_classify "https://github.com/floomhq/icontext/blob/main/scripts/icontext_classify.py"
click node_tierconfig "https://github.com/floomhq/icontext/blob/main/config/tiers.yml"
click node_encryption "https://github.com/floomhq/icontext/blob/main/workflows/sensitivity.yml"
click node_retrieval "https://github.com/floomhq/icontext/blob/main/scripts/indexlib.py"
click node_prompt_hook "https://github.com/floomhq/icontext/blob/main/scripts/prompt_context.py"
click node_mcp "https://github.com/floomhq/icontext/blob/main/mcp/server.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_populate,node_refresh,node_entity,node_validation,node_render,node_sharecard,node_writefact,node_headless,node_user toneBlue
class node_gmail,node_linkedin,node_selfdescribe toneAmber
class node_vault,node_classify,node_tierconfig,node_encryption,node_gemini toneMint
class node_retrieval,node_prompt_hook,node_mcp toneRose
class node_agent,node_agents toneIndigo
```

## Components

### Profile Workflow

- [Populate Skill](https://github.com/floomhq/icontext/blob/main/skills/icontext-populate-profile/SKILL.md): `skills/icontext-populate-profile/SKILL.md`
- [Refresh Skill](https://github.com/floomhq/icontext/blob/main/skills/icontext-refresh-profile/SKILL.md): `skills/icontext-refresh-profile/SKILL.md`
- [Entity Extraction](https://github.com/floomhq/icontext/blob/main/skills/icontext-populate-profile/SKILL.md): `skills/icontext-populate-profile/SKILL.md`
- [Evidence Validation](https://github.com/floomhq/icontext/blob/main/connectors/gmail.py): `connectors/gmail.py`
- [Profile Rendering](https://github.com/floomhq/icontext/blob/main/connectors/gmail.py): `connectors/gmail.py`
- [Share Card Skill](https://github.com/floomhq/icontext/blob/main/skills/icontext-share-card/SKILL.md): `skills/icontext-share-card/SKILL.md`
- [Write Fact Skill](https://github.com/floomhq/icontext/blob/main/skills/icontext-write-fact/SKILL.md): `skills/icontext-write-fact/SKILL.md`
- [Headless Sync](https://github.com/floomhq/icontext/blob/main/cli.py): `cli.py`

### Data Sources

- [Gmail Connector](https://github.com/floomhq/icontext/blob/main/connectors/gmail.py): `connectors/gmail.py`
- [LinkedIn Connector](https://github.com/floomhq/icontext/blob/main/connectors/linkedin.py): `connectors/linkedin.py`
- [Self Description](https://github.com/floomhq/icontext/blob/main/skills/icontext-populate-profile/SKILL.md): `skills/icontext-populate-profile/SKILL.md`

### Vault and Security

- **Tiered Markdown Vault**
- [Sensitivity Classifier](https://github.com/floomhq/icontext/blob/main/scripts/icontext_classify.py): `scripts/icontext_classify.py`
- [Tier Configuration](https://github.com/floomhq/icontext/blob/main/config/tiers.yml): `config/tiers.yml`
- [Vault Encryption](https://github.com/floomhq/icontext/blob/main/workflows/sensitivity.yml): `workflows/sensitivity.yml`

### Agent Access

- [Local Retrieval](https://github.com/floomhq/icontext/blob/main/scripts/indexlib.py): `scripts/indexlib.py`
- [Prompt Context Hook](https://github.com/floomhq/icontext/blob/main/scripts/prompt_context.py): `scripts/prompt_context.py`
- [MCP Server](https://github.com/floomhq/icontext/blob/main/mcp/server.py): `mcp/server.py`

### Other components

- **User**
- **AI Agent**
- **Gemini API**
- **Coding Agents**

## Connections

- User → Populate Skill: invokes
- AI Agent → Populate Skill: follows
- Populate Skill → Gmail Connector: tries first
- Populate Skill → LinkedIn Connector: fallback source
- Populate Skill → Self Description: fallback source
- Gmail Connector → Entity Extraction: provides metadata
- LinkedIn Connector → Entity Extraction: provides profile
- Self Description → Entity Extraction: provides answers
- Entity Extraction → Evidence Validation: filters evidence
- Evidence Validation → Profile Rendering: validated entities
- Populate Skill → Profile Rendering: synthesizes profile
- Profile Rendering → Tiered Markdown Vault: writes Markdown
- User → Refresh Skill: requests update
- Refresh Skill → Tiered Markdown Vault: updates profile
- User → Share Card Skill: requests summary
- Share Card Skill → Tiered Markdown Vault: writes summary
- User → Write Fact Skill: provides fact
- Write Fact Skill → Tiered Markdown Vault: routes fact
- User → Headless Sync: runs sync
- Headless Sync → Gmail Connector: syncs source
- Headless Sync → LinkedIn Connector: syncs source
- Headless Sync → Gemini API: requests synthesis
- Headless Sync → Tiered Markdown Vault: writes profile
- Tier Configuration → Sensitivity Classifier: configures tiers
- Tiered Markdown Vault → Sensitivity Classifier: checks sensitivity
- Tiered Markdown Vault → Vault Encryption: protects vault tier
- Coding Agents → Prompt Context Hook: submits prompt
- Prompt Context Hook → Local Retrieval: searches context
- Local Retrieval → Tiered Markdown Vault: reads indexed files
- Coding Agents → MCP Server: calls tools
- MCP Server → Local Retrieval: searches vault
- MCP Server → Tiered Markdown Vault: reads and appends
- MCP Server → Local Retrieval: rebuilds index
- Tiered Markdown Vault → Coding Agents: shared context