Pal

Type: ../types/agent-memory-system-review.md · Status: current

Pal, from agno-agi/pal, is a personal knowledge agent built on Agno AgentOS. It coordinates a leader, Navigator, optional Researcher, Compiler, Linter, and optional Syncer over PostgreSQL/pgvector knowledge stores, Agno session storage, user-created SQL tables, a local context/ file tree, a compiled wiki, scheduled runs, and optional Gmail, Calendar, Slack, Exa, Parallel, and git-sync integrations.

Repository: https://github.com/agno-agi/pal

Reviewed commit: 6516b8ede0c085e48f39f3bd04cb85b475a855dc

Source directory: related-systems/agno-agi--pal

Core Ideas

The system is an Agno team, not a standalone memory library. pal/team.py creates a coordinate-mode team with a leader and specialist members; Navigator owns most retrieval and action tools, Researcher ingests source material when Parallel is configured, Compiler turns raw files into wiki articles, Linter writes wiki health reports, and Syncer commits context/ changes when git sync is configured (pal/team.py, pal/agents/navigator.py, pal/agents/compiler.py, pal/agents/linter.py, pal/agents/syncer.py).

The knowledge architecture deliberately keeps heterogeneous sources separate. pal_knowledge is a routing map for files, schemas, source capabilities, discoveries, wiki articles, and raw sources; pal_learnings is operational memory; files and wiki articles stay under context/; structured notes, people, projects, and decisions live in PostgreSQL pal_* tables; Gmail, Calendar, Slack, Exa, and Parallel keep their native interfaces (pal/instructions.py, db/session.py, pal/tools/build.py).

Context efficiency is progressive and role-scoped. context/load_context.py inserts compact file metadata into pal_knowledge rather than embedding full file bodies; Navigator instructions require recall before reading, wiki index reads before article reads, manifest checks before raw-source reads, and per-source summaries when outputs are large (context/load_context.py, pal/instructions.py). Complexity is still model- and tool-dependent: Agno knowledge search, SQL queries, file reads, and specialist delegation can all expand the context path.

Learning is mostly framework-wired, not Pal-local extraction code. The leader and Navigator configure LearningMachine(... LearningMode.AGENTIC), enable_agentic_memory=True, search_past_sessions=True, add_history_to_context=True, and read_chat_history=True; the leader and optional Researcher also set add_learnings_to_context=True (pal/team.py, pal/agents/navigator.py, pal/agents/researcher.py). Pal also gives Navigator prose rules to save_learning, but I did not find Pal-local code that parses interaction traces, merges learned records, or exposes Agno's extraction policy.

The wiki pipeline is an agent-maintained file layer. Researcher writes raw Markdown with frontmatter and manifest entries; Compiler reads uncompiled raw files, writes summaries and concept articles, updates wiki/index.md and .state.json, and marks raw files compiled; Linter reads the wiki, finds contradictions, stale articles, missing concepts, or duplicates, and writes a lint report (pal/tools/ingest.py, pal/agents/compiler.py, pal/tools/wiki.py, pal/agents/linter.py).

Schedules turn maintenance into active work. AgentOS runs with scheduler=True and registers daily context refresh, weekday briefing, wiki compile, inbox digest, Monday learning summary, Friday weekly review, Sunday wiki lint, and optional sync pull (app/main.py). These schedules start endpoint calls or team runs; they are activation mechanisms, not independent evidence that every scheduled output is correct.

Artifact analysis

  • Storage substrate: rdbms vector files repo service-object — PostgreSQL stores Agno sessions, pal_knowledge, pal_learnings, and user-created pal_* tables; PgVector stores hybrid-search vectors and contents rows; context/ stores authored files, raw ingests, wiki articles, templates, and reports; optional git sync stores context history; AgentOS schedules and external integrations live as service objects.
  • Representational form: prose symbolic parametric — Context Markdown, wiki articles, raw sources, learnings, instructions, and session text are prose; SQL schemas, manifests, frontmatter, schedules, tool definitions, team configuration, user-id scoping rules, and eval cases are symbolic; PgVector embeddings and Agno retrieval state are parametric.
  • Lineage: authored imported trace-extracted — User/agent-authored files, SQL rows, instructions, schedules, and learnings are authored; URL/text ingests, email/calendar/web outputs, and raw source material are imported; Agno session/chat history and Agno-managed learned knowledge are trace-extracted from runtime interactions, but Pal-local code does not expose the extraction algorithm.
  • Behavioral authority: knowledge instruction enforcement routing validation ranking learning — Files, wiki articles, SQL rows, sessions, and raw sources advise as knowledge; agent instructions, team configuration, tool assemblies, and schedules instruct; disabled deletes/sends, confirmation rules, and user-id scoping enforce; pal_knowledge, wiki index, manifest, tags, discoveries, and specialist routing route; evals, context-loader tests, wiki lint, and state reports validate; Agno hybrid search and past-session search rank attention; pal_learnings and Agno agentic memory learn operational patterns.

pal_knowledge routing map. Storage substrate: PostgreSQL PgVector plus Agno contents tables named from create_knowledge("Pal Knowledge", "pal_knowledge") (db/session.py). Representational form: prose metadata records plus symbolic title prefixes and vector/keyword index state. Lineage: bootstrap file metadata from context/load_context.py and agent-authored Schema:, Source:, Discovery:, Wiki:, and Raw: entries. Behavioral authority: routing system-definition artifact because it tells agents where to inspect next, while instructions warn it is a map rather than raw content.

pal_learnings operational memory. Storage substrate: PostgreSQL PgVector knowledge store named pal_learnings. Representational form: prose learning entries with prefixes such as Retrieval:, Pattern:, and Correction:. Lineage: Agno-managed agentic learning and instruction-driven save_learning calls; Pal does not show the extraction, deduplication, or merge algorithm. Behavioral authority: advisory-to-instructional context because corrections are instructed to win, and Agno can add learnings to runtime context before action.

Agno session and chat history. Storage substrate: PostgresDb configured with the shared DB URL. Representational form: framework-managed structured session records and conversation text. Lineage: runtime traces captured by Agno. Behavioral authority: read-back context when search_past_sessions, add_history_to_context, and read_chat_history are enabled; Pal sets counts for searched sessions and history runs but does not expose Agno's relevance scoring.

Context files and compiled wiki. Storage substrate: local filesystem under PAL_CONTEXT_DIR, optionally committed by Syncer. Representational form: Markdown, YAML/JSON frontmatter, manifests, wiki state JSON, templates, and voice guides. Lineage: authored by users or agents, imported from URLs/text, compiled from raw files, and maintained by scheduled team runs. Behavioral authority: knowledge when read as evidence, instruction when voice/templates/preferences shape drafting, and routing when wiki/index.md or raw/.manifest.json selects what to read.

SQL user tables. Storage substrate: PostgreSQL schema pal, with agent-created pal_* tables accessed through SQLTools (db/session.py, pal/instructions.py). Representational form: symbolic relational rows plus prose fields and tags. Lineage: agent-created from natural conversation and external source reads. Behavioral authority: knowledge for retrieval and synthesis; weak routing when Discovery: entries point later queries to SQL.

Agent instructions, tool assemblies, schedules, and evals. Storage substrate: authored Python modules, config files, and eval cases. Representational form: prose instructions plus symbolic team/tool/schedule/eval definitions. Lineage: shipped implementation. Behavioral authority: strong system-definition authority because these artifacts decide delegation, tool availability, file deletion, email sending, external confirmation, user scoping, scheduled actions, and evaluation criteria.

Promotion path: raw files can become summaries and concept articles; concept articles can update the wiki index and state; successful multi-source searches can become Discovery: routing entries; explicit corrections and useful strategies can become pal_learnings; structured facts can become SQL rows plus discovery metadata; context changes can be committed to a git-backed context repo. Most promotion is prompt-governed rather than enforced by deterministic validators.

Comparison with Our System

Dimension Pal Commonplace
Primary purpose Running personal assistant over heterogeneous personal context Agent-operated methodology KB and framework
Orchestration Agno Team, AgentOS APIs, scheduler, optional Slack interface CLI commands, skills, collection contracts, validation, review workflows
Canonical stores PostgreSQL/pgvector, Agno sessions, SQL tables, context/ files, optional git sync Git-tracked Markdown artifacts, schemas, source snapshots, generated indexes, reports
Context strategy Metadata routing, wiki index-first reads, files/SQL/native tools, Agno learnings/history rg, authored/generated indexes, links, type specs, validation, review gates
Learning Agno LearningMachine, pal_learnings, past-session search, agent-saved learnings Deliberate artifact writing, source-grounded reviews, validation, semantic QA
Governance Prose rules, disabled tools, user-id scoping instructions, eval cases, wiki lint Type contracts, deterministic validation, review bundles, replacement archives, git diffs

Pal is useful to compare because it bundles patterns Commonplace usually keeps separated: a vector-backed routing map, native files, SQL facts, a compiled wiki, scheduled maintenance, and runtime agent learning. That makes Pal more operational than Commonplace, but also harder to audit from a single artifact. A Correction: learning or Discovery: entry can influence the next interaction faster than Commonplace would normally allow a methodology claim into durable use.

The strongest alignment is progressive disclosure. Pal's pal_knowledge, wiki/index.md, and raw manifest serve the same broad purpose as Commonplace directory indexes and collection metadata: they tell the agent where to look before loading large bodies of text. The difference is reviewability. Commonplace keeps these routing and quality contracts in git-readable artifacts; Pal keeps part of them inside PgVector/Agno stores and prompt-managed agent behavior.

Pal's specialist team also exposes a tradeoff. Splitting Navigator, Researcher, Compiler, Linter, and Syncer narrows tools and makes scheduled maintenance natural, but the semantics of one answer are spread across Agno framework behavior, prompts, database state, file state, tool assemblies, and schedules. Commonplace is less runtime-integrated but easier to inspect as a library.

Borrowable Ideas

Metadata routing as a first-class artifact. Commonplace could use compact, reviewed "where this topic lives" records analogous to Pal's Discovery: entries. Ready as a file-native note/report pattern; database-backed automatic discovery needs invalidation and review gates first.

Specialist agents by context surface. Pal's role split is useful for long workflows where source reading, artifact writing, validation, and sync should not share every tool. Ready for complex review or ingestion runs; unnecessary for simple edits.

Scheduled prompts into existing workflows. Pal reuses team endpoints for compile, lint, briefings, learning summaries, and weekly reviews. Commonplace could schedule review sweeps or index refreshes, but only where an operator explicitly wants proactive work.

Keep raw, compiled, routing, learning, and structured fact stores distinct. Pal's anti-flattening stance is worth borrowing: a vector map should not replace source files, SQL facts, raw snapshots, or compiled synthesis. Ready as a design constraint.

Do not borrow fast learning authority without review. Pal's Agno learnings can shape runtime context quickly. That is appropriate for a personal assistant; Commonplace should treat trace- or interaction-derived rules as candidates until promoted through source-grounded review.

Write side

Write agency: manual automatic — Users and agents manually save notes, files, raw ingests, wiki outputs, SQL rows, and context changes; automatic or scheduled paths reload context metadata, run team prompts for wiki compile/lint/briefing/review, invoke Agno learning/session storage, update manifests/state, and optionally commit context changes through Syncer.

Curation operations: consolidate evolve promote — Compiler consolidates stored raw files into summaries and concept articles, evolves existing concept pages with new source-backed information, and promotes raw/imported material into wiki articles, index entries, state, and knowledge metadata. Linter reports contradictions, staleness, thin articles, or duplicates, but I did not find code that automatically invalidates or merges the affected articles.

Pal is not tagged trace-derived in this review because the local repository configures Agno agentic memory and session history but does not expose a Pal-local trace parser, extraction prompt, merge policy, or durable trace-to-artifact pipeline. Agno-managed sessions and learned knowledge are retained behavior-shaping artifacts; the trace-derived extraction mechanism is owned by Agno rather than inspectable Pal code at this commit.

Read-back

Read-back: both — Pull paths include deliberate knowledge search, SQL queries, file reads, wiki index/article reads, manifest reads, email/calendar/web calls, and learning searches. Push paths include Agno-added learnings, bounded history, past-session search, and scheduled team runs that assemble retained context before the acting agent responds.

Read-back signal: coarse — Pal visibly configures coarse runtime memory insertion through add_learnings_to_context, add_history_to_context, read_chat_history, and bounded history/session counts. It also requests Agno past-session search, but this repo does not reveal whether Agno's instance-specific selection uses lexical, embedding, or judgment signals, so those subtypes are not tokenized here.

Faithfulness tested: no — Pal has evals and deterministic context-loader tests, but I did not find a with/without behavioral ablation or post-action audit proving that pushed learnings, chat history, or past-session search changed downstream agent behavior.

Direction edge cases. Static instructions, context files, and wiki articles do not by themselves make Pal push-based; they matter when read by a tool, loaded by Agno runtime settings, or activated by a scheduled run. Scheduled prompts are push from time/state into the agent loop, and the team run can then receive Agno learnings/history before action.

Targeting and signal. The visible pushed context is mostly coarse: added learnings, recent chat history, datetime, and bounded session history. Pal's search_past_sessions=True is likely instance-conditioned on the current prompt/session, but the ranking mechanism is hidden behind Agno APIs. Pull retrieval uses hybrid PgVector search, SQL tags, file paths, wiki index links, manifests, and external tool filters, but those do not become pushed signals unless Agno or a schedule loads them before the agent acts.

Injection point. Agno read-back happens before leader/Navigator/Researcher model calls when configured context is assembled. AgentOS schedules also inject task prompts before a team run, after which the normal Agno memory/session settings apply. Compiler and Linter outputs are write-side maintenance until later read through a tool or pushed through Agno context.

Selection, scope, and complexity. Leader searches up to ten past sessions and reads five history runs; Navigator searches up to five past sessions and reads ten history runs. File/wiki retrieval uses index-first and manifest-first instructions, while SQL and email paths are instructed to summarize large result sets. Actual precision, recall, and context dilution are not verified from Pal code.

Authority at consumption. pal_knowledge mostly routes. pal_learnings, especially Correction: entries, are intended to override conflicts. Voice guides and templates become instruction-like when read before drafting. Schedules can force maintenance work without a live user request.

Other consumers. Humans can read and edit context/, wiki files, templates, lint reports, scheduled Slack posts, git history, and SQL-backed data through Pal. Scheduler and Syncer consume retained state operationally, and evals consume the team behavior as a quality surface.

Curiosity Pass

The README's "every interaction improves the next one" promise is real only at Agno-boundary confidence from this repo. Pal wires Agno learning and gives agents save-learning instructions, but the repository does not show the extraction, ranking, review, or deduplication policy for learned records.

pal_knowledge is a map, not the territory. That is a good context-efficiency choice, but context/load_context.py --recreate clears the whole knowledge index because row-level delete is not supported. Schema, discovery, and source entries then need to be rebuilt organically.

The wiki pipeline is stronger architecturally than as checked-in content. The Compiler/Linter instructions and tools are detailed, while the bundled context/wiki/index.md is initially empty. The code shows the maintenance pattern more than the quality of generated articles.

Governance is split between code and prompt. File deletion and Gmail sending are disabled in tool configuration, while SQL user-id scoping, correction priority, calendar confirmation, and many routing rules rely on instructions plus eval coverage.

Schedules are memory activation infrastructure. Daily context refresh, wiki compile, learning summary, weekly review, and wiki lint can all create or activate retained artifacts without the user asking in that moment.

What to Watch

  • Whether Pal adds local learning extraction code with source session ids, extraction prompts, merge policy, confidence, invalidation, and review gates; that would change the trace-derived decision.
  • Whether Agno learnings expose enough lineage in Pal to audit a Correction: or Retrieval: record back to the interaction that produced it.
  • Whether pal_knowledge gets stale-entry repair for files, SQL schemas, sources, discoveries, wiki articles, and live integrations.
  • Whether wiki compilation gains source-grounding tests for concept articles, not just routing and knowledge evals.
  • Whether prompt-level SQL and cross-user governance moves into tool wrappers or database policies.
  • Whether scheduled outputs are reviewed before Syncer commits and pushes them to the git-backed context repository.

Relevant Notes: