# agno-agi/pal architecture

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

- Interactive diagram: https://gitdiagram.com/agno-agi/pal
- Repository: https://github.com/agno-agi/pal

## Overview

1. **Product shape**
   - Pal is a local-first personal agent system built around one FastAPI service plus persistent context on disk and PostgreSQL.
   - It exposes a team-runner API, optional Slack entrypoint, and scheduled jobs for background maintenance.

2. **Top-level runtime**
   - `app/main.py` is the main service entrypoint: it boots the AgentOS/FastAPI app, enables tracing/scheduling, and wires the custom routes.
   - `app/router.py` defines the repo-specific endpoints for context reload, wiki compile/lint/ingest, and Git sync.
   - The app is containerized with `Dockerfile` and `compose.yaml`, so the runtime boundary is the API container plus PostgreSQL.

3. **Agent team orchestration**
   - `pal/team.py` coordinates a five-agent “team” pattern.
   - The leader delegates to specialist agents in `pal/agents/`: Navigator, Researcher, Compiler, Linter, and Syncer.
   - This is the core architecture boundary: one orchestrator, multiple domain-specialized agents, each with a constrained toolset.

4. **Navigator path: answer questions from many sources**
   - `pal/agents/navigator.py` is the primary interactive agent for user queries.
   - It routes across SQL, context files, wiki index/articles, email, calendar, Slack, and web search, choosing the native interface for each source.
   - This is where metadata routing matters most: the agent uses knowledge about where something lives instead of flattening all sources into one index.

5. **Research → compile pipeline**
   - `pal/agents/researcher.py` ingests external content into `context/raw/`.
   - `pal/agents/compiler.py` turns raw sources into a compiled wiki under `context/wiki/`:
     - `index.md` as the master index
     - `concepts/` for concept articles
     - `summaries/` for per-source summaries
     - `outputs/` for generated reports
   - The pipeline is incremental and file-backed, with manifest/state files tracking progress.

6. **Knowledge maintenance**
   - `pal/agents/linter.py` performs health checks over the wiki and supporting context.
   - It looks for gaps, contradictions, stale content, and missing concepts, then writes findings back into the knowledge system.
   - This makes the wiki a living artifact rather than a static document dump.

7. **Sync and persistence boundaries**
   - `pal/agents/syncer.py` handles pushing/pulling `context/` state to and from GitHub when configured.
   - `db/` provides PostgreSQL session and URL plumbing; the database stores structured entities such as notes, people, projects, decisions, plus internal tables like `pal_knowledge` and `pal_learnings`.
   - In practice, Git-backed files and SQL-backed records are two separate persistence layers with different access patterns.

8. **Context directory as the file knowledge layer**
   - `context/` is not just data; it is a first-class input to the agent.
   - It contains user preferences, voice guides, templates, authored notes, raw ingests, and the compiled wiki.
   - The `context/load_context.py` flow indexes these files into the metadata layer so the agents can route questions correctly.

9. **Routing and learning model**
   - The system explicitly separates **knowledge** from **learnings**.
   - `pal_knowledge` stores “where to look” metadata: file locations, schemas, source capabilities, and cross-source mappings.
   - `pal_learnings` stores operational memory: what retrieval strategy worked, recurring patterns, and corrections. This influences future Navigator behavior.

10. **External integrations**
   - Gmail, Google Calendar, and Slack are optional and gated by env vars.
   - Exa is used for general web search; Parallel is used for deeper web research and extraction when enabled.
   - These integrations are accessed as native tools, not through a unified document index, which preserves source-specific semantics.

11. **Scheduled automation**
   - The repo includes cron-like background tasks for context refresh, daily briefing, wiki compilation, inbox digest, learning summary, weekly review, wiki lint, and Git sync.
   - These jobs are part of the same service boundary, but they run on a schedule rather than on user request.
   - Slack can receive the outputs of these jobs when configured.

12. **Testing and operational tooling**
   - `evals/` contains scenario-based evaluation suites for routing, governance, knowledge, security, voice, and wiki behavior.
   - `docs/` documents integration setup and behavioral specs; `scripts/` contains build, validation, auth, and deployment helpers.
   - This repo is organized so architecture changes can be validated against concrete agent behaviors, not just unit functions.

Main entry points: [`pal/team.py`](https://github.com/agno-agi/pal/blob/main/pal/team.py) (Team runner), [`pal/agents/navigator.py`](https://github.com/agno-agi/pal/blob/main/pal/agents/navigator.py) (Navigator), [`app/router.py`](https://github.com/agno-agi/pal/blob/main/app/router.py) (API routes), [`app/main.py`](https://github.com/agno-agi/pal/blob/main/app/main.py) (Main app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_app_main["Main app<br/>FastAPI entrypoint<br/>[main.py]"]
  node_app_router["API routes<br/>Repo routes<br/>[router.py]"]
  node_compose["Container stack<br/>Docker compose<br/>[compose.yaml]"]
end

subgraph group_orchestration["Orchestration"]
  node_team{{"Team runner<br/>Agent orchestrator<br/>[team.py]"}}
end

subgraph group_agents["Agents"]
  node_nav(("Navigator<br/>Query agent<br/>[navigator.py]"))
  node_researcher(("Researcher<br/>Ingest agent<br/>[researcher.py]"))
  node_compiler(("Compiler<br/>Wiki builder<br/>[compiler.py]"))
  node_linter(("Linter<br/>Wiki health<br/>[linter.py]"))
  node_syncer(("Syncer<br/>Git sync<br/>[syncer.py]"))
end

subgraph group_knowledge["Knowledge Layer"]
  node_load_context["Context loader<br/>Metadata index<br/>[load_context.py]"]
  node_context_dir["Context tree<br/>File knowledge"]
  node_wiki["Wiki<br/>Compiled knowledge"]
  node_raw["Raw ingest<br/>Input cache"]
end

subgraph group_persistence["Persistence"]
  node_db[("Postgres layer<br/>SQL persistence")]
  node_pal_tables[("PAL tables<br/>Operational memory<br/>[session.py]")]
end

subgraph group_integrations["Integrations"]
  node_external["External APIs<br/>Native tools"]
end

subgraph group_tooling["Tooling"]
  node_scripts["Scripts<br/>Ops helpers"]
  node_evals["Evals<br/>Behavior suites"]
end

node_app_main -->|"starts"| node_team
node_app_main -->|"mounts"| node_app_router
node_app_main -->|"loads"| node_load_context
node_app_main -->|"connects"| node_db
node_compose -->|"runs"| node_app_main
node_team -->|"delegates"| node_nav
node_team -->|"delegates"| node_researcher
node_team -->|"delegates"| node_compiler
node_team -->|"delegates"| node_linter
node_team -->|"delegates"| node_syncer
node_nav -->|"reads"| node_context_dir
node_nav -->|"reads"| node_wiki
node_nav -->|"queries"| node_db
node_nav -->|"uses"| node_external
node_researcher -->|"writes"| node_raw
node_compiler -->|"reads"| node_raw
node_compiler -->|"writes"| node_wiki
node_linter -->|"checks"| node_wiki
node_linter -->|"checks"| node_context_dir
node_syncer -->|"syncs"| node_context_dir
node_syncer -->|"uses"| node_external
node_load_context -->|"indexes"| node_context_dir
node_load_context -->|"improves routing"| node_nav
node_db -->|"stores"| node_pal_tables
node_app_router -->|"reloads"| node_load_context
node_app_router -->|"triggers"| node_compiler
node_app_router -->|"triggers"| node_linter
node_app_router -->|"triggers"| node_syncer
node_scripts -->|"supports"| node_compose
node_evals -->|"validates"| node_team

click node_app_main "https://github.com/agno-agi/pal/blob/main/app/main.py"
click node_app_router "https://github.com/agno-agi/pal/blob/main/app/router.py"
click node_compose "https://github.com/agno-agi/pal/blob/main/compose.yaml"
click node_team "https://github.com/agno-agi/pal/blob/main/pal/team.py"
click node_nav "https://github.com/agno-agi/pal/blob/main/pal/agents/navigator.py"
click node_researcher "https://github.com/agno-agi/pal/blob/main/pal/agents/researcher.py"
click node_compiler "https://github.com/agno-agi/pal/blob/main/pal/agents/compiler.py"
click node_linter "https://github.com/agno-agi/pal/blob/main/pal/agents/linter.py"
click node_syncer "https://github.com/agno-agi/pal/blob/main/pal/agents/syncer.py"
click node_load_context "https://github.com/agno-agi/pal/blob/main/context/load_context.py"
click node_context_dir "https://github.com/agno-agi/pal/tree/main/context"
click node_wiki "https://github.com/agno-agi/pal/tree/main/context/wiki"
click node_raw "https://github.com/agno-agi/pal/tree/main/context/raw"
click node_db "https://github.com/agno-agi/pal/tree/main/db"
click node_pal_tables "https://github.com/agno-agi/pal/blob/main/db/session.py"
click node_scripts "https://github.com/agno-agi/pal/tree/main/scripts"
click node_evals "https://github.com/agno-agi/pal/tree/main/evals"

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_app_main,node_app_router,node_compose,node_scripts,node_evals toneBlue
class node_team toneAmber
class node_nav,node_researcher,node_compiler,node_linter,node_syncer toneMint
class node_load_context,node_context_dir,node_wiki,node_raw toneRose
class node_db,node_pal_tables toneIndigo
class node_external toneTeal
```

## Components

### Runtime

Service entrypoints and deployment boundary

- [Main app](https://github.com/agno-agi/pal/blob/main/app/main.py): FastAPI entrypoint · Boots the service, tracing, scheduling, and routes · `app/main.py`
- [API routes](https://github.com/agno-agi/pal/blob/main/app/router.py): Repo routes · Context reload, wiki, and Git sync endpoints · `app/router.py`
- [Container stack](https://github.com/agno-agi/pal/blob/main/compose.yaml): Docker compose · Containerized runtime boundary with the API and PostgreSQL · `compose.yaml`

### Orchestration

Agent team and request routing

- [Team runner](https://github.com/agno-agi/pal/blob/main/pal/team.py): Agent orchestrator · Coordinates the five-agent team pattern · `pal/team.py`

### Agents

Specialized agent roles

- [Navigator](https://github.com/agno-agi/pal/blob/main/pal/agents/navigator.py): Query agent · Answers questions across SQL, files, wiki, email, calendar, Slack, and web · `pal/agents/navigator.py`
- [Researcher](https://github.com/agno-agi/pal/blob/main/pal/agents/researcher.py): Ingest agent · Pulls external material into raw context · `pal/agents/researcher.py`
- [Compiler](https://github.com/agno-agi/pal/blob/main/pal/agents/compiler.py): Wiki builder · Compiles raw inputs into the wiki structure · `pal/agents/compiler.py`
- [Linter](https://github.com/agno-agi/pal/blob/main/pal/agents/linter.py): Wiki health · Checks for gaps, drift, contradictions, and missing concepts · `pal/agents/linter.py`
- [Syncer](https://github.com/agno-agi/pal/blob/main/pal/agents/syncer.py): Git sync · Pushes and pulls context state to GitHub when enabled · `pal/agents/syncer.py`

### Knowledge Layer

Disk-backed context and wiki

- [Context loader](https://github.com/agno-agi/pal/blob/main/context/load_context.py): Metadata index · Indexes context files into the routing layer · `context/load_context.py`
- [Context tree](https://github.com/agno-agi/pal/tree/main/context): File knowledge · Preferences, templates, notes, raw ingests, and wiki content · `context`
- [Wiki](https://github.com/agno-agi/pal/tree/main/context/wiki): Compiled knowledge · Index, concepts, summaries, outputs, and state · `context/wiki`
- [Raw ingest](https://github.com/agno-agi/pal/tree/main/context/raw): Input cache · Staging area for external content before compilation · `context/raw`

### Persistence

Database and sync boundaries

- [Postgres layer](https://github.com/agno-agi/pal/tree/main/db): SQL persistence · Session and URL plumbing for structured records · `db`
- [PAL tables](https://github.com/agno-agi/pal/blob/main/db/session.py): Operational memory · Knowledge and learning tables plus structured entities · `db/session.py`

### Integrations

Optional external services and native tools

- **External APIs**: Native tools · Gmail, Calendar, Slack, Exa, and Parallel when configured

### Tooling

Operational scripts and validation

- [Scripts](https://github.com/agno-agi/pal/tree/main/scripts): Ops helpers · Build, validation, auth, and deployment automation · `scripts`
- [Evals](https://github.com/agno-agi/pal/tree/main/evals): Behavior suites · Scenario-based checks for routing, knowledge, security, voice, and wiki behavior · `evals`

## Connections

- Main app → Team runner: starts · Main service boots the agent team and supporting runtime
- Main app → API routes: mounts · Registers repo-specific API endpoints
- Main app → Context loader: loads · Initializes file-backed context metadata
- Main app → Postgres layer: connects · Uses PostgreSQL session/url plumbing
- Container stack → Main app: runs · Container runtime launches the service
- Team runner → Navigator: delegates · Routes interactive requests to the navigator
- Team runner → Researcher: delegates · Sends external collection work to research
- Team runner → Compiler: delegates · Sends compilation work to wiki building
- Team runner → Linter: delegates · Sends maintenance checks to linting
- Team runner → Syncer: delegates · Sends Git-backed sync work to the sync agent
- Navigator → Context tree: reads · Uses file-backed context as a source of truth
- Navigator → Wiki: reads · Answers from compiled wiki content
- Navigator → Postgres layer: queries · Retrieves structured records from SQL
- Navigator → External APIs: uses · Calls native integrations and search tools
- Researcher → Raw ingest: writes · Stages ingested content in raw context
- Compiler → Raw ingest: reads · Consumes staged inputs for compilation
- Compiler → Wiki: writes · Builds the compiled wiki artifacts
- Linter → Wiki: checks · Inspects wiki health and consistency
- Linter → Context tree: checks · Scans supporting context for gaps and drift
- Syncer → Context tree: syncs · Pushes and pulls file-backed state
- Syncer → External APIs: uses · Integrates with GitHub when configured
- Context loader → Context tree: indexes · Builds metadata over context files
- Context loader → Navigator: improves routing · Helps select the best source for a question
- Postgres layer → PAL tables: stores · Holds knowledge, learnings, and structured entities
- API routes → Context loader: reloads · Exposes context refresh flow
- API routes → Compiler: triggers · Exposes wiki compile and ingest actions
- API routes → Linter: triggers · Exposes wiki lint action
- API routes → Syncer: triggers · Exposes Git sync action
- Scripts → Container stack: supports · Build and deployment helpers target the containerized stack
- Evals → Team runner: validates · Exercises routing and behavior across the agent system
