CLAUDE.md

This file provides context for Claude Code when working with this repository.

Project Overview

Agentic Investment Team — A multi-agent system built with Agno that simulates a professional investment team deploying $10M into public equities. Demonstrates 5 multi-agent architectures, three-layer knowledge, and institutional learning.

Architecture

AgentOS (app/main.py)
├── Agents (7 reusable specialists)
│   ├── Market Analyst          — macro trends, sector analysis, news (Exa + YFinance)
│   ├── Financial Analyst       — fundamentals, valuation, financials (YFinance)
│   ├── Technical Analyst       — price action, momentum, entry/exit (YFinance)
│   ├── Risk Officer            — downside scenarios, portfolio exposure (YFinance)
│   ├── Knowledge Agent         — research library (RAG) + memo archive (FileTools)
│   ├── Memo Writer             — synthesizes analysis into formal memos (FileTools)
│   └── Committee Chair         — final decisions, capital allocation (Gemini 3.1 Pro)
│
├── Teams (4 architectures)
│   ├── Coordinate Team         — Chair orchestrates analysts dynamically
│   ├── Route Team              — routes questions to the right specialist
│   ├── Broadcast Team          — all analysts evaluate simultaneously
│   └── Task Team               — autonomous task decomposition
│
├── Workflows (1 architecture)
│   └── Investment Workflow     — deterministic pipeline with parallel steps
│
├── Three-Layer Knowledge
│   ├── Layer 1: Static Context     — mandate, risk policy, process (always in prompt)
│   ├── Layer 2: Research Library   — company profiles, sector analysis (PgVector RAG)
│   └── Layer 3: Memo Archive       — past investment memos (FileTools)
│
└── Institutional Learning          — patterns, corrections, insights (LearningMachine)

All specialist agents use:

• Gemini 3 Flash model (gemini-3-flash-preview)
• PostgreSQL database (pgvector) for persistence
• Committee context (Layer 1) in system prompt
• Shared knowledge base (Layer 2) for RAG
• Shared learnings (institutional learning)

Committee Chair and team leaders use:

• Gemini 3.1 Pro model (gemini-3.1-pro-preview)

Key Files

Development Setup

Virtual Environment

./scripts/venv_setup.sh
source .venv/bin/activate

Format & Validation

source .venv/bin/activate && ./scripts/format.sh
source .venv/bin/activate && ./scripts/validate.sh

Conventions

Agent Pattern

All agents follow this structure:

from agno.agent import Agent
from agno.models.google import Gemini
from agno.learn import LearningMachine, LearnedKnowledgeConfig, LearningMode

from context import COMMITTEE_CONTEXT
from agents.settings import team_knowledge, team_learnings
from db import get_postgres_db

agent_db = get_postgres_db()

instructions = f"""\
You are the [Role] on a $10M investment team.

## Committee Rules (ALWAYS FOLLOW)

{COMMITTEE_CONTEXT}

## Your Role
[Role-specific instructions...]
"""

my_agent = Agent(
    id="my-agent",
    name="My Agent",
    model=Gemini(id="gemini-3-flash-preview"),
    db=agent_db,
    instructions=instructions,
    tools=[...],
    knowledge=team_knowledge,
    search_knowledge=True,
    learning=LearningMachine(
        knowledge=team_learnings,
        learned_knowledge=LearnedKnowledgeConfig(
            mode=LearningMode.AGENTIC,
            namespace="global",
        ),
    ),
    add_datetime_to_context=True,
    add_history_to_context=True,
    num_history_runs=5,
    markdown=True,
    enable_agentic_memory=True,
)

Critical Rules

1. Never duplicate knowledge instances — always import from agents.settings
2. All instructions include COMMITTEE_CONTEXT via f-string (Layer 1)
3. Gemini Pro for Chair/team leaders, Gemini Flash for specialists
4. Memos = files (FileTools), Research = vectors (PgVector) — never mix
5. committee_chair is NOT a member of Coordinate/Broadcast/Task teams (the team model= acts as chair). It IS a member of Route team and the final Workflow step.
6. No learning config on: Memo Writer, Committee Chair, Knowledge Agent, Route team
7. Agent IDs are kebab-case and match config.yaml keys
8. skip_if_exists=True on research loading to prevent re-indexing

Database

• Use get_postgres_db() from db module
• Knowledge bases use create_knowledge() from db module
• The contents_table parameter is only needed when provided to a Knowledge base

# Shared knowledge instances (import from agents.settings)
from agents.settings import team_knowledge, team_learnings

# Agent database (no contents_table needed)
agent_db = get_postgres_db()

Imports

# Database
from db import db_url, get_postgres_db, create_knowledge

# Context
from context import COMMITTEE_CONTEXT

# Shared settings
from agents.settings import team_knowledge, team_learnings, MEMOS_DIR, EXA_MCP_URL

# Agents
from agents import (
    market_analyst, financial_analyst, technical_analyst,
    risk_officer, knowledge_agent, memo_writer, committee_chair,
)

# Teams
from teams import coordinate_team, route_team, broadcast_team, task_team

# Workflows
from workflows import investment_workflow

Commands

# Setup virtual environment
./scripts/venv_setup.sh
source .venv/bin/activate

# Local development with Docker
docker compose up -d --build

# Load research into knowledge base
python -m app.load_knowledge
python -m app.load_knowledge --recreate  # Drop and reload

# Format & validation
./scripts/format.sh
./scripts/validate.sh

# Generate requirements
./scripts/generate_requirements.sh

Environment Variables

Required:

• GOOGLE_API_KEY — for Gemini models and embeddings
• EXA_API_KEY — for Exa web search

Optional:

• PARALLEL_API_KEY — for ParallelTools web search
• RUNTIME_ENV — set to dev for auto-reload
• DB_HOST, DB_PORT, DB_USER, DB_PASS, DB_DATABASE

Ports

• API: 8000
• Database: 5432

Data Storage