How agno-agi/pal works
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: team.py Team runner · navigator.py Navigator · router.py API routes · main.py Main app
Components 18
Runtime
Service entrypoints and deployment boundary
- Main app · Boots the service, tracing, scheduling, and routes
app/main.py - API routes · Context reload, wiki, and Git sync endpoints
app/router.py - Container stack · Containerized runtime boundary with the API and PostgreSQL
compose.yaml
Orchestration
Agent team and request routing
- Team runner · Coordinates the five-agent team pattern
pal/team.py
Agents
Specialized agent roles
- Navigator · Answers questions across SQL, files, wiki, email, calendar, Slack, and web
pal/agents/navigator.py - Researcher · Pulls external material into raw context
pal/agents/researcher.py - Compiler · Compiles raw inputs into the wiki structure
pal/agents/compiler.py - Linter · Checks for gaps, drift, contradictions, and missing concepts
pal/agents/linter.py - Syncer · Pushes and pulls context state to GitHub when enabled
pal/agents/syncer.py
Knowledge Layer
Disk-backed context and wiki
- Context loader · Indexes context files into the routing layer
context/load_context.py - Context tree · Preferences, templates, notes, raw ingests, and wiki content
context - Wiki · Index, concepts, summaries, outputs, and state
context/wiki - Raw ingest · Staging area for external content before compilation
context/raw
Persistence
Database and sync boundaries
- Postgres layer · Session and URL plumbing for structured records
db - PAL tables · Knowledge and learning tables plus structured entities
db/session.py
Integrations
Optional external services and native tools
- External APIs · Gmail, Calendar, Slack, Exa, and Parallel when configured
Connections 30
- 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