Birdie

      ___                       ___           ___                       ___
    /\  \          ___        /\  \         /\  \          ___        /\  \
   /::\  \        /\  \      /::\  \       /::\  \        /\  \      /::\  \
  /:/\:\  \       \:\  \    /:/\:\  \     /:/\:\  \       \:\  \    /:/\:\  \
 /::\~\:\__\      /::\__\  /::\~\:\  \   /:/  \:\__\      /::\__\  /::\~\:\  \
/:/\:\ \:|__|  __/:/\/__/ /:/\:\ \:\__\ /:/__/ \:|__|  __/:/\/__/ /:/\:\ \:\__\
\:\~\:\/:/  / /\/:/  /    \/_|::\/:/  / \:\  \ /:/  / /\/:/  /    \:\~\:\ \/__/
 \:\ \::/  /  \::/__/        |:|::/  /   \:\  /:/  /  \::/__/      \:\ \:\__\
  \:\/:/  /    \:\__\        |:|\/__/     \:\/:/  /    \:\__\       \:\ \/__/
   \::/__/      \/__/        |:|  |        \::/__/      \/__/        \:\__\
    ~~                        \|__|         ~~                        \/__/

A LangGraph-based agent that discovers capabilities at runtime from SKILL.MD and AGENT.MD files. Skills, tools, and sub-agents are all declared in plain Markdown - no code changes required to add new capabilities.

Birdie is a minimal yet fully functional implementation. The design goal is simplicity and transparency: the codebase is intended to be readable, hackable, and easy to extend. Every major feature - the agent loop, skill loading, session persistence, conversation compaction, long-term memory - is implemented in a small number of well-commented Python files that you can read from top to bottom in an afternoon.

Security notice: Birdie has no guardrails against local tool misuse. Skills such as Shell and Filesystem can read, write, and execute anything the running user is permitted to do. Only enable skills you trust and run Birdie under an account with appropriate restrictions.

Installation

From PyPI (recommended)

pip install birdie-agent

From source

git clone https://github.com/gkvas/birdie.git
cd birdie
pip install -e .

Optional extras

pip install "birdie-agent[mcp]"   # MCP server support
pip install -e ".[dev,mcp]"       # development + MCP (from source)

Quick start

Configure your LLM provider and run birdie.

Environment variables

# Anthropic
export LLM_VENDOR=anthropic
export LLM_MODEL=claude-sonnet-4-6
export ANTHROPIC_API_KEY=your-key-here
birdie

# OpenAI
export LLM_VENDOR=openai
export LLM_MODEL=gpt-4o
export OPENAI_API_KEY=your-key-here
birdie

# Mistral
export LLM_VENDOR=mistral
export LLM_MODEL=mistral-large-latest
export MISTRAL_API_KEY=your-key-here
birdie

# Azure OpenAI
export LLM_VENDOR=azure
export LLM_MODEL=your-deployment-name
export AZURE_OPENAI_API_KEY=your-key-here
export AZURE_OPENAI_ENDPOINT=your-base-url
birdie

JSON config file

birdie --config ~/.birdie/provider.json

{
  "vendor": "anthropic",
  "model": "claude-sonnet-4-6",
  "api_key": "sk-ant-..."
}

See doc/cli.md for all supported vendors, config fields, and environment variable options.

Built-in skills

Skills extend Birdie and are defined in SKILL.MD files. All skills are disabled by default. Enable them for the current session:

/skill enable Shell
/skill enable DuckDuckGo

Birdie ships with the following default skills:

See doc/skills.md for the full SKILL.MD format and how to write skills.

Sub-agents

Sub-agents are AI agents defined by AGENT.MD files. When enabled, a sub-agent appears to the calling LLM as a regular tool. Invoking it spins up an ephemeral agent, runs it to completion, and returns the result.

All agents are disabled by default. Enable them for the current session:

/agent enable Summarizer

Drop an AGENT.MD in ~/.birdie/agents/<name>/ to add custom sub-agents without reinstalling.

See doc/agents.md for the full AGENT.MD format and how to write custom agents.

Conversation memory

Birdie maintains three separate memory stores that work together to give the agent context across turns and sessions.

Short-term memory is handled automatically by LangGraph's SQLite checkpointer. Every message is stored in ~/.birdie/sessions/<user>/checkpoints.db and loaded at the start of each turn. The full history is sent to the LLM; once it grows past the compaction threshold (80 messages by default, or a configurable token budget), the oldest segment is summarised away in the background so cost stays bounded even in very long sessions.

Manual long-term memory is written by you, explicitly. Use /remember to save any fact you want the agent to recall in future sessions:

/remember I prefer compact, direct answers without preamble
/remember The project uses Python 3.12 and pytest for tests

Notes are stored in ~/.birdie/sessions/<user>/memory.json and injected into the model's context on every turn, across all sessions.

Automatic long-term memory is written by the compaction pipeline. When a session grows beyond 80 messages, Birdie summarises the oldest segment using the LLM in the background, extracts structured facts, preferences, tool outcomes, and open tasks, and stores them in ~/.birdie/ltm/<user>.json. The summary also stays with the session as a rolling continuity bridge, and on future turns the top-5 most semantically relevant entries are retrieved and injected alongside your manual /remember notes.

You can trigger compaction at any time with:

/compact

This is useful at the end of a long working session to capture everything important before starting fresh. The command displays the summary that was generated and how many messages were removed from the checkpoint.

The retrieval uses a lightweight hash-trick embedding (birdie/core/retrieval.py) that requires no model downloads or extra dependencies - just SHA-256 and a dot product.

See doc/architecture.md for a detailed explanation of how all three stores interact, how the compaction algorithm picks the split point, and how the LTM store is queried each turn.

Key commands

Documentation

Running tests

pip install -e ".[dev,mcp]"
pytest