# gowtham0992/link architecture

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

- Interactive diagram: https://gitdiagram.com/gowtham0992/link
- Repository: https://github.com/gowtham0992/link

## Overview

Link is a local, Markdown-backed memory layer for AI agents. Users capture source material, structure it into a source-backed wiki, review proposed durable memories, then retrieve compact context through CLI, MCP, or the local viewer. The graph includes those domain stages, security and filesystem foundations, and the macOS LinkBar client. Several capability branches are documented but their implementations were not sampled; those are represented at directory level, and only documented or indexed relationships are connected.

Main entry points: [`mcp_package/link_core/memory.py`](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/memory.py) (Memory governance), [`link.py`](https://github.com/gowtham0992/link/blob/main/link.py) (CLI), [`mcp_package/link_core/query.py`](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/query.py) (Query packets), [`mcp_package/link_core/capture.py`](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/capture.py) (Capture proposals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Agent interfaces"]
  node_cli["CLI<br/>[link.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_viewer["Local viewer<br/>[serve.py]"]
  node_hooks["Session hooks<br/>[agent_hooks.py]"]
  node_web_features["Viewer features"]
end

subgraph group_capture["Capture and structure"]
  node_capture_flow["Capture proposals<br/>[capture.py]"]
  node_ingest_flow["Raw ingestion<br/>[ingest.py]"]
  node_structured["Structured import"]
  node_importers["Memory importers<br/>[importers.py]"]
  node_security["Safety checks<br/>[security.py]"]
end

subgraph group_memory["Memory and retrieval"]
  node_review["Memory governance<br/>[memory.py]"]
  node_query["Query packets<br/>[query.py]"]
  node_wiki["Wiki indexing<br/>[wiki.py]"]
  node_semantic["Semantic retrieval<br/>[semantic.py]"]
  node_consolidate["Memory consolidation<br/>[consolidate.py]"]
end

subgraph group_workspace["Local workspace"]
  node_raw["Raw sources"]
  node_markdown["Markdown wiki"]
  node_file_ops["Atomic file access<br/>[files.py]"]
  node_audit_log["Activity log<br/>[log.py]"]
end

subgraph group_desktop["Desktop client"]
  node_linkbar["LinkBar app<br/>[LinkStore.swift]"]
  node_cli_runner["CLI bridge<br/>[LinkCLI.swift]"]
end

node_person(("User"))
node_agents(("Local agents"))

node_person -->|"runs commands"| node_cli
node_agents -->|"query memory"| node_mcp
node_agents -->|"retrieve context"| node_cli
node_person -->|"opens viewer"| node_viewer
node_person -->|"reviews memory"| node_linkbar
node_cli -->|"captures proposals"| node_capture_flow
node_cli -->|"manages memories"| node_review
node_cli -->|"builds packets"| node_query
node_cli -->|"checks ingest"| node_ingest_flow
node_mcp -->|"calls memory logic"| node_review
node_mcp -->|"handles capture"| node_capture_flow
node_viewer -->|"serves retrieval"| node_query
node_viewer -->|"serves pages"| node_web_features
node_hooks -.->|"proposes captures"| node_capture_flow
node_capture_flow -->|"checks content"| node_security
node_capture_flow -->|"writes proposals"| node_file_ops
node_raw -->|"ingested from"| node_ingest_flow
node_ingest_flow -->|"scans sources"| node_security
node_ingest_flow -->|"structures pages"| node_wiki
node_structured -->|"writes pages"| node_file_ops
node_importers -.->|"imports memory"| node_review
node_review -->|"checks memory"| node_security
node_review -->|"persists memory"| node_file_ops
node_review -->|"delegates consolidation"| node_consolidate
node_review -->|"uses retrieval"| node_semantic
node_query -->|"recalls memories"| node_review
node_query -->|"retrieves pages"| node_wiki
node_query -->|"ranks semantically"| node_semantic
node_wiki -->|"reads workspace"| node_file_ops
node_wiki -->|"indexes pages"| node_markdown
node_semantic -->|"reads local index"| node_file_ops
node_linkbar -->|"requests CLI data"| node_cli_runner
node_cli_runner -->|"runs commands"| node_cli
node_markdown -->|"inspected directly"| node_person

click node_cli "https://github.com/gowtham0992/link/blob/main/link.py"
click node_mcp "https://github.com/gowtham0992/link/blob/main/mcp_package/link_mcp/server.py"
click node_viewer "https://github.com/gowtham0992/link/blob/main/serve.py"
click node_hooks "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/agent_hooks.py"
click node_capture_flow "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/capture.py"
click node_ingest_flow "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/ingest.py"
click node_structured "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/structured_ingest.py"
click node_importers "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/importers.py"
click node_security "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/security.py"
click node_review "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/memory.py"
click node_query "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/query.py"
click node_wiki "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/wiki.py"
click node_semantic "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/semantic.py"
click node_consolidate "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/consolidate.py"
click node_file_ops "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/files.py"
click node_audit_log "https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/log.py"
click node_web_features "https://github.com/gowtham0992/link/tree/main/mcp_package/link_core"
click node_linkbar "https://github.com/gowtham0992/link/blob/main/apps/LinkBar/Sources/LinkBar/LinkStore.swift"
click node_cli_runner "https://github.com/gowtham0992/link/blob/main/apps/LinkBar/Sources/LinkBar/LinkCLI.swift"

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_cli,node_mcp,node_viewer,node_hooks,node_web_features,node_person toneBlue
class node_capture_flow,node_ingest_flow,node_structured,node_importers,node_security toneAmber
class node_review,node_query,node_wiki,node_semantic,node_consolidate toneMint
class node_raw,node_markdown,node_file_ops,node_audit_log toneRose
class node_linkbar,node_cli_runner,node_agents toneIndigo
```

## Components

### Agent interfaces

- [CLI](https://github.com/gowtham0992/link/blob/main/link.py): `link.py`
- [MCP server](https://github.com/gowtham0992/link/blob/main/mcp_package/link_mcp/server.py): `mcp_package/link_mcp/server.py`
- [Local viewer](https://github.com/gowtham0992/link/blob/main/serve.py): `serve.py`
- [Session hooks](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/agent_hooks.py): `mcp_package/link_core/agent_hooks.py`
- [Viewer features](https://github.com/gowtham0992/link/tree/main/mcp_package/link_core): `mcp_package/link_core`

### Capture and structure

- [Capture proposals](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/capture.py): `mcp_package/link_core/capture.py`
- [Raw ingestion](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/ingest.py): `mcp_package/link_core/ingest.py`
- [Structured import](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/structured_ingest.py): `mcp_package/link_core/structured_ingest.py`
- [Memory importers](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/importers.py): `mcp_package/link_core/importers.py`
- [Safety checks](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/security.py): `mcp_package/link_core/security.py`

### Memory and retrieval

- [Memory governance](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/memory.py): `mcp_package/link_core/memory.py`
- [Query packets](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/query.py): `mcp_package/link_core/query.py`
- [Wiki indexing](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/wiki.py): `mcp_package/link_core/wiki.py`
- [Semantic retrieval](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/semantic.py): `mcp_package/link_core/semantic.py`
- [Memory consolidation](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/consolidate.py): `mcp_package/link_core/consolidate.py`

### Local workspace

- **Raw sources**
- **Markdown wiki**
- [Atomic file access](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/files.py): `mcp_package/link_core/files.py`
- [Activity log](https://github.com/gowtham0992/link/blob/main/mcp_package/link_core/log.py): `mcp_package/link_core/log.py`

### Desktop client

- [LinkBar app](https://github.com/gowtham0992/link/blob/main/apps/LinkBar/Sources/LinkBar/LinkStore.swift): `apps/LinkBar/Sources/LinkBar/LinkStore.swift`
- [CLI bridge](https://github.com/gowtham0992/link/blob/main/apps/LinkBar/Sources/LinkBar/LinkCLI.swift): `apps/LinkBar/Sources/LinkBar/LinkCLI.swift`

### Other components

- **User**
- **Local agents**

## Connections

- User → CLI: runs commands (evidence: `README.md`)
- Local agents → MCP server: query memory (evidence: `README.md`)
- Local agents → CLI: retrieve context (evidence: `README.md`)
- User → Local viewer: opens viewer (evidence: `README.md`)
- User → LinkBar app: reviews memory (evidence: `README.md`)
- CLI → Capture proposals: captures proposals (evidence: `link.py`)
- CLI → Memory governance: manages memories (evidence: `link.py`)
- CLI → Query packets: builds packets (evidence: `link.py`)
- CLI → Raw ingestion: checks ingest (evidence: `link.py`)
- MCP server → Memory governance: calls memory logic (evidence: `mcp_package/link_mcp/server.py`)
- MCP server → Capture proposals: handles capture (evidence: `mcp_package/link_mcp/server.py`)
- Local viewer → Query packets: serves retrieval (evidence: `serve.py`)
- Local viewer → Viewer features: serves pages (evidence: `serve.py`)
- Session hooks → Capture proposals: proposes captures
- Capture proposals → Safety checks: checks content (evidence: `mcp_package/link_core/capture.py`)
- Capture proposals → Atomic file access: writes proposals (evidence: `mcp_package/link_core/capture.py`)
- Raw sources → Raw ingestion: ingested from (evidence: `README.md`)
- Raw ingestion → Safety checks: scans sources (evidence: `mcp_package/link_core/ingest.py`)
- Raw ingestion → Wiki indexing: structures pages (evidence: `mcp_package/link_core/ingest.py`)
- Structured import → Atomic file access: writes pages (evidence: `mcp_package/link_core/structured_ingest.py`)
- Memory importers → Memory governance: imports memory
- Memory governance → Safety checks: checks memory (evidence: `mcp_package/link_core/memory.py`)
- Memory governance → Atomic file access: persists memory (evidence: `mcp_package/link_core/memory.py`)
- Memory governance → Memory consolidation: delegates consolidation (evidence: `mcp_package/link_core/memory.py`)
- Memory governance → Semantic retrieval: uses retrieval (evidence: `mcp_package/link_core/memory.py`)
- Query packets → Memory governance: recalls memories (evidence: `mcp_package/link_core/query.py`)
- Query packets → Wiki indexing: retrieves pages (evidence: `mcp_package/link_core/query.py`)
- Query packets → Semantic retrieval: ranks semantically (evidence: `mcp_package/link_core/query.py`)
- Wiki indexing → Atomic file access: reads workspace (evidence: `mcp_package/link_core/wiki.py`)
- Wiki indexing → Markdown wiki: indexes pages (evidence: `README.md`)
- Semantic retrieval → Atomic file access: reads local index (evidence: `mcp_package/link_core/semantic.py`)
- LinkBar app → CLI bridge: requests CLI data (evidence: `apps/LinkBar/Sources/LinkBar/LinkStore.swift`)
- CLI bridge → CLI: runs commands
- Markdown wiki → User: inspected directly (evidence: `README.md`)
