# eazy-k/vault-engine architecture

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

- Interactive diagram: https://gitdiagram.com/eazy-k/vault-engine
- Repository: https://github.com/eazy-k/vault-engine

## Overview

vault-engine is a local, model-independent notes engine: an agent or user invokes its CLI to retrieve task-relevant context from a separate data repository, while optional setup, project discovery, agent integrations, and maintenance support that workflow. The README documents the major capabilities; sampled source confirms the retrieval engine’s weighted-note model and selected module relationships. Some command dispatch and integration wiring is not shown, so those links are omitted or marked unverified.

Main entry points: [`tools/graph.py`](https://github.com/eazy-k/vault-engine/blob/main/tools/graph.py) (Engine CLI), [`tools/onboarding.py`](https://github.com/eazy-k/vault-engine/blob/main/tools/onboarding.py) (Setup and onboarding), [`tools/claude_hooks.py`](https://github.com/eazy-k/vault-engine/blob/main/tools/claude_hooks.py) (Claude hook setup), [`tools/codex_hooks.py`](https://github.com/eazy-k/vault-engine/blob/main/tools/codex_hooks.py) (Codex hook setup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_core["Context engine"]
  node_cli["Engine CLI<br/>[graph.py]"]
  node_retrieval["Weighted retrieval<br/>[graph.py]"]
  node_vaultdata[("Notes and graph data")]
  node_defaults["Default notes"]
end

subgraph group_vault["Vault lifecycle"]
  node_templates["Vault templates"]
  node_onboarding["Setup and onboarding<br/>[onboarding.py]"]
  node_schema["Schema migrations<br/>[schema.py]"]
  node_updates["Engine updates<br/>[update.py]"]
end

subgraph group_agents["Agent integrations"]
  node_claudehooks["Claude hook setup<br/>[claude_hooks.py]"]
  node_claudedirs["Claude config dirs<br/>[claude_dirs.py]"]
  node_claudeworkers["Claude hook handlers"]
  node_codexhooks["Codex hook setup<br/>[codex_hooks.py]"]
  node_codexhandlers["Codex hook handlers"]
  node_models["Model configuration<br/>[models.py]"]
  node_modelrules["Model policy<br/>[model_config.py]"]
end

subgraph group_support["Supporting features"]
  node_discovery["Project discovery<br/>[discovery.py]"]
  node_feedback["Opt-in feedback<br/>[feedback.py]"]
  node_tokenstats["Token statistics<br/>[token_stats.py]"]
end

node_user(("User or agent"))

node_user -->|"invokes commands"| node_cli
node_cli -->|"retrieves context"| node_retrieval
node_retrieval -->|"loads and updates"| node_vaultdata
node_retrieval -->|"loads fallback notes"| node_defaults
node_cli -->|"offers setup commands"| node_onboarding
node_onboarding -->|"scaffolds vault"| node_templates
node_onboarding -->|"configures and checks"| node_vaultdata
node_cli -->|"scans projects"| node_discovery
node_discovery -->|"caches results"| node_vaultdata
node_cli -->|"offers migration"| node_schema
node_cli -->|"offers update command"| node_updates
node_cli -->|"offers feedback commands"| node_feedback
node_cli -->|"reports usage"| node_tokenstats
node_cli -.->|"configures Claude hooks"| node_claudehooks
node_claudehooks -->|"uses config directories"| node_claudedirs
node_claudehooks -.->|"installs handlers"| node_claudeworkers
node_cli -.->|"configures Codex hooks"| node_codexhooks
node_codexhooks -.->|"installs handlers"| node_codexhandlers
node_cli -->|"offers model settings"| node_models
node_models -->|"loads model policy"| node_modelrules

click node_cli "https://github.com/eazy-k/vault-engine/blob/main/tools/graph.py"
click node_retrieval "https://github.com/eazy-k/vault-engine/blob/main/tools/graph.py"
click node_defaults "https://github.com/eazy-k/vault-engine/tree/main/defaults"
click node_templates "https://github.com/eazy-k/vault-engine/tree/main/templates"
click node_onboarding "https://github.com/eazy-k/vault-engine/blob/main/tools/onboarding.py"
click node_schema "https://github.com/eazy-k/vault-engine/blob/main/tools/schema.py"
click node_updates "https://github.com/eazy-k/vault-engine/blob/main/tools/update.py"
click node_discovery "https://github.com/eazy-k/vault-engine/blob/main/tools/discovery.py"
click node_feedback "https://github.com/eazy-k/vault-engine/blob/main/tools/feedback.py"
click node_tokenstats "https://github.com/eazy-k/vault-engine/blob/main/tools/token_stats.py"
click node_claudehooks "https://github.com/eazy-k/vault-engine/blob/main/tools/claude_hooks.py"
click node_claudedirs "https://github.com/eazy-k/vault-engine/blob/main/tools/claude_dirs.py"
click node_claudeworkers "https://github.com/eazy-k/vault-engine/tree/main/tools/claude-hooks"
click node_codexhooks "https://github.com/eazy-k/vault-engine/blob/main/tools/codex_hooks.py"
click node_codexhandlers "https://github.com/eazy-k/vault-engine/tree/main/tools/codex-hooks"
click node_models "https://github.com/eazy-k/vault-engine/blob/main/tools/models.py"
click node_modelrules "https://github.com/eazy-k/vault-engine/blob/main/tools/model_config.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_cli,node_retrieval,node_vaultdata,node_defaults,node_user toneBlue
class node_templates,node_onboarding,node_schema,node_updates toneAmber
class node_claudehooks,node_claudedirs,node_claudeworkers,node_codexhooks,node_codexhandlers,node_models,node_modelrules toneMint
class node_discovery,node_feedback,node_tokenstats toneRose
```

## Components

### Context engine

- [Engine CLI](https://github.com/eazy-k/vault-engine/blob/main/tools/graph.py): `tools/graph.py`
- [Weighted retrieval](https://github.com/eazy-k/vault-engine/blob/main/tools/graph.py): `tools/graph.py`
- **Notes and graph data**
- [Default notes](https://github.com/eazy-k/vault-engine/tree/main/defaults): `defaults`

### Vault lifecycle

- [Vault templates](https://github.com/eazy-k/vault-engine/tree/main/templates): `templates`
- [Setup and onboarding](https://github.com/eazy-k/vault-engine/blob/main/tools/onboarding.py): `tools/onboarding.py`
- [Schema migrations](https://github.com/eazy-k/vault-engine/blob/main/tools/schema.py): `tools/schema.py`
- [Engine updates](https://github.com/eazy-k/vault-engine/blob/main/tools/update.py): `tools/update.py`

### Agent integrations

- [Claude hook setup](https://github.com/eazy-k/vault-engine/blob/main/tools/claude_hooks.py): `tools/claude_hooks.py`
- [Claude config dirs](https://github.com/eazy-k/vault-engine/blob/main/tools/claude_dirs.py): `tools/claude_dirs.py`
- [Claude hook handlers](https://github.com/eazy-k/vault-engine/tree/main/tools/claude-hooks): `tools/claude-hooks`
- [Codex hook setup](https://github.com/eazy-k/vault-engine/blob/main/tools/codex_hooks.py): `tools/codex_hooks.py`
- [Codex hook handlers](https://github.com/eazy-k/vault-engine/tree/main/tools/codex-hooks): `tools/codex-hooks`
- [Model configuration](https://github.com/eazy-k/vault-engine/blob/main/tools/models.py): `tools/models.py`
- [Model policy](https://github.com/eazy-k/vault-engine/blob/main/tools/model_config.py): `tools/model_config.py`

### Supporting features

- [Project discovery](https://github.com/eazy-k/vault-engine/blob/main/tools/discovery.py): `tools/discovery.py`
- [Opt-in feedback](https://github.com/eazy-k/vault-engine/blob/main/tools/feedback.py): `tools/feedback.py`
- [Token statistics](https://github.com/eazy-k/vault-engine/blob/main/tools/token_stats.py): `tools/token_stats.py`

### Other components

- **User or agent**

## Connections

- User or agent → Engine CLI: invokes commands (evidence: `README.md`)
- Engine CLI → Weighted retrieval: retrieves context (evidence: `README.md`)
- Weighted retrieval → Notes and graph data: loads and updates (evidence: `tools/graph.py`)
- Weighted retrieval → Default notes: loads fallback notes (evidence: `README.md`)
- Engine CLI → Setup and onboarding: offers setup commands (evidence: `README.md`)
- Setup and onboarding → Vault templates: scaffolds vault (evidence: `README.md`)
- Setup and onboarding → Notes and graph data: configures and checks (evidence: `README.md`)
- Engine CLI → Project discovery: scans projects (evidence: `README.md`)
- Project discovery → Notes and graph data: caches results (evidence: `README.md`)
- Engine CLI → Schema migrations: offers migration (evidence: `README.md`)
- Engine CLI → Engine updates: offers update command (evidence: `README.md`)
- Engine CLI → Opt-in feedback: offers feedback commands (evidence: `README.md`)
- Engine CLI → Token statistics: reports usage (evidence: `README.md`)
- Engine CLI → Claude hook setup: configures Claude hooks (evidence: `tools/claude_hooks.py`)
- Claude hook setup → Claude config dirs: uses config directories (evidence: `tools/claude_hooks.py`)
- Claude hook setup → Claude hook handlers: installs handlers
- Engine CLI → Codex hook setup: configures Codex hooks (evidence: `tools/codex_hooks.py`)
- Codex hook setup → Codex hook handlers: installs handlers
- Engine CLI → Model configuration: offers model settings (evidence: `tools/models.py`)
- Model configuration → Model policy: loads model policy (evidence: `tools/models.py`)