# ar9av/obsidian-wiki architecture

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

- Interactive diagram: https://gitdiagram.com/ar9av/obsidian-wiki
- Repository: https://github.com/ar9av/obsidian-wiki

## Overview

obsidian-wiki is an agent-guided knowledge system: an agent uses Markdown skills to capture and maintain knowledge in a local Obsidian vault, then retrieves connected knowledge and session context. The Python package provides CLI, API, and optional remote-server access; the browser extension adds web capture and form filling. The graph preserves these documented product branches, but sampled excerpts do not establish the detailed wiring for most skill-driven workflows, so those links are kept at the documented agent-to-skill boundary.

Main entry points: [`extensions/brain/host/brain_fill_host.py`](https://github.com/ar9av/obsidian-wiki/blob/main/extensions/brain/host/brain_fill_host.py) (Form-fill host), [`obsidian_wiki/session_graph.py`](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_graph.py) (Session graph), [`obsidian_wiki/graphrag.py`](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/graphrag.py) (Graph-aware retrieval), [`obsidian_wiki/server.py`](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/server.py) (HTTP and MCP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_agent_workflows["Agent workflows"]
  node_skills["Wiki skills<br/>[.skills]"]
  node_ingest_skill["Ingest skills<br/>[wiki-ingest]"]
  node_update_skill["Update skill<br/>[wiki-update]"]
  node_query_skills["Query and narrate<br/>[wiki-query]"]
  node_maintenance_skills["Vault maintenance<br/>[wiki-lint]"]
  node_capture_skill["Conversation capture<br/>[wiki-capture]"]
end

subgraph group_knowledge_vault["Knowledge vault"]
  node_vault[("Markdown vault")]
  node_graph_query["Graph-aware retrieval<br/>[graphrag.py]"]
  node_graph_analysis["Graph analysis<br/>[graph_analysis.py]"]
  node_context_pack["Context packing<br/>[context_pack.py]"]
end

subgraph group_memory_sessions["Memory and sessions"]
  node_memory_core["Memory operations<br/>[memory.py]"]
  node_session_sources["Session sources<br/>[session_sources.py]"]
  node_session_index["Session index<br/>[session_index.py]"]
  node_session_graph["Session graph<br/>[session_graph.py]"]
  node_session_query["Session search<br/>[session_query.py]"]
end

subgraph group_interfaces["Interfaces"]
  node_cli["CLI<br/>[cli.py]"]
  node_memory_api["Python memory API<br/>[client.py]"]
  node_http_mcp["HTTP and MCP<br/>[server.py]"]
end

subgraph group_browser_tools["Browser tools"]
  node_browser_extension["Capture extension<br/>[background.js]"]
  node_extension_popup["Capture and fill UI<br/>[popup.js]"]
  node_native_host["Form-fill host<br/>[brain_fill_host.py]"]
end

node_person(("Vault user"))
node_agent(("AI agent"))
node_web_page(("Web page"))
node_llm_cli(("Agent CLI providers"))

node_person -->|"requests work"| node_agent
node_agent -->|"reads and runs"| node_skills
node_agent -->|"dispatches ingestion"| node_ingest_skill
node_agent -->|"dispatches updates"| node_update_skill
node_agent -->|"asks knowledge"| node_query_skills
node_agent -->|"maintains vault"| node_maintenance_skills
node_agent -->|"captures conversation"| node_capture_skill
node_ingest_skill -->|"compiles knowledge"| node_vault
node_update_skill -->|"updates pages"| node_vault
node_capture_skill -->|"saves knowledge"| node_vault
node_query_skills -->|"queries graph"| node_graph_query
node_graph_query -->|"reads page metadata"| node_vault
node_graph_query -->|"analyzes structure"| node_graph_analysis
node_maintenance_skills -->|"checks and cleans"| node_vault
node_agent -->|"runs commands"| node_cli
node_cli -->|"operates on"| node_vault
node_memory_api -->|"delegates memory"| node_memory_core
node_memory_core -->|"reads and writes"| node_vault
node_http_mcp -->|"serves vault access"| node_vault
node_http_mcp -->|"delegates search"| node_graph_query
node_http_mcp -->|"delegates packing"| node_context_pack
node_session_sources -->|"provides session text"| node_session_index
node_session_graph -->|"reads histories"| node_session_sources
node_session_graph -->|"builds vectors"| node_session_index
node_session_graph -->|"detects communities"| node_graph_analysis
node_session_query -->|"loads graph"| node_session_graph
node_person -->|"captures web content"| node_browser_extension
node_web_page -->|"provides page content"| node_browser_extension
node_browser_extension -->|"writes raw capture"| node_vault
node_extension_popup -->|"sends native messages"| node_native_host
node_native_host -->|"runs context-pack"| node_context_pack
node_native_host -.->|"requests form answers"| node_llm_cli
node_native_host -->|"resolves vault"| node_vault

click node_skills "https://github.com/ar9av/obsidian-wiki/tree/main/.skills"
click node_ingest_skill "https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-ingest"
click node_update_skill "https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-update"
click node_query_skills "https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-query"
click node_maintenance_skills "https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-lint"
click node_capture_skill "https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-capture"
click node_cli "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/cli.py"
click node_graph_query "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/graphrag.py"
click node_graph_analysis "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/graph_analysis.py"
click node_context_pack "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/context_pack.py"
click node_memory_api "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/client.py"
click node_memory_core "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/memory.py"
click node_http_mcp "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/server.py"
click node_session_sources "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_sources.py"
click node_session_index "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_index.py"
click node_session_graph "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_graph.py"
click node_session_query "https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_query.py"
click node_browser_extension "https://github.com/ar9av/obsidian-wiki/blob/main/extensions/brain/background.js"
click node_extension_popup "https://github.com/ar9av/obsidian-wiki/blob/main/extensions/brain/popup.js"
click node_native_host "https://github.com/ar9av/obsidian-wiki/blob/main/extensions/brain/host/brain_fill_host.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_skills,node_ingest_skill,node_update_skill,node_query_skills,node_maintenance_skills,node_capture_skill,node_person toneBlue
class node_vault,node_graph_query,node_graph_analysis,node_context_pack toneAmber
class node_memory_core,node_session_sources,node_session_index,node_session_graph,node_session_query toneMint
class node_cli,node_memory_api,node_http_mcp toneRose
class node_browser_extension,node_extension_popup,node_native_host,node_agent,node_web_page,node_llm_cli toneIndigo
```

## Components

### Agent workflows

- [Wiki skills](https://github.com/ar9av/obsidian-wiki/tree/main/.skills): `.skills`
- [Ingest skills](https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-ingest): `.skills/wiki-ingest`
- [Update skill](https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-update): `.skills/wiki-update`
- [Query and narrate](https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-query): `.skills/wiki-query`
- [Vault maintenance](https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-lint): `.skills/wiki-lint`
- [Conversation capture](https://github.com/ar9av/obsidian-wiki/tree/main/.skills/wiki-capture): `.skills/wiki-capture`

### Knowledge vault

- **Markdown vault**
- [Graph-aware retrieval](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/graphrag.py): `obsidian_wiki/graphrag.py`
- [Graph analysis](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/graph_analysis.py): `obsidian_wiki/graph_analysis.py`
- [Context packing](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/context_pack.py): `obsidian_wiki/context_pack.py`

### Memory and sessions

- [Memory operations](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/memory.py): `obsidian_wiki/memory.py`
- [Session sources](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_sources.py): `obsidian_wiki/session_sources.py`
- [Session index](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_index.py): `obsidian_wiki/session_index.py`
- [Session graph](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_graph.py): `obsidian_wiki/session_graph.py`
- [Session search](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/session_query.py): `obsidian_wiki/session_query.py`

### Interfaces

- [CLI](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/cli.py): `obsidian_wiki/cli.py`
- [Python memory API](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/client.py): `obsidian_wiki/client.py`
- [HTTP and MCP](https://github.com/ar9av/obsidian-wiki/blob/main/obsidian_wiki/server.py): `obsidian_wiki/server.py`

### Browser tools

- [Capture extension](https://github.com/ar9av/obsidian-wiki/blob/main/extensions/brain/background.js): `extensions/brain/background.js`
- [Capture and fill UI](https://github.com/ar9av/obsidian-wiki/blob/main/extensions/brain/popup.js): `extensions/brain/popup.js`
- [Form-fill host](https://github.com/ar9av/obsidian-wiki/blob/main/extensions/brain/host/brain_fill_host.py): `extensions/brain/host/brain_fill_host.py`

### Other components

- **Vault user**
- **AI agent**
- **Web page**
- **Agent CLI providers**

## Connections

- Vault user → AI agent: requests work
- AI agent → Wiki skills: reads and runs
- AI agent → Ingest skills: dispatches ingestion
- AI agent → Update skill: dispatches updates
- AI agent → Query and narrate: asks knowledge
- AI agent → Vault maintenance: maintains vault
- AI agent → Conversation capture: captures conversation
- Ingest skills → Markdown vault: compiles knowledge
- Update skill → Markdown vault: updates pages
- Conversation capture → Markdown vault: saves knowledge
- Query and narrate → Graph-aware retrieval: queries graph
- Graph-aware retrieval → Markdown vault: reads page metadata
- Graph-aware retrieval → Graph analysis: analyzes structure
- Vault maintenance → Markdown vault: checks and cleans
- AI agent → CLI: runs commands
- CLI → Markdown vault: operates on
- Python memory API → Memory operations: delegates memory
- Memory operations → Markdown vault: reads and writes
- HTTP and MCP → Markdown vault: serves vault access
- HTTP and MCP → Graph-aware retrieval: delegates search
- HTTP and MCP → Context packing: delegates packing
- Session sources → Session index: provides session text
- Session graph → Session sources: reads histories
- Session graph → Session index: builds vectors
- Session graph → Graph analysis: detects communities
- Session search → Session graph: loads graph
- Vault user → Capture extension: captures web content
- Web page → Capture extension: provides page content
- Capture extension → Markdown vault: writes raw capture
- Capture and fill UI → Form-fill host: sends native messages
- Form-fill host → Context packing: runs context-pack
- Form-fill host → Agent CLI providers: requests form answers
- Form-fill host → Markdown vault: resolves vault