Bickford AI Agent
README.md

Baia Agent #

A simple LangGraph-based CLI agent with terminal access and memory.

Features #

  • LangGraph Agent - Stateful agent with tool execution
  • Terminal Access - Execute shell commands safely in container
  • Two-Tier Memory System:
    • Short-term: memory.md (10k char limit, LRU eviction, LLM deduplication)
    • Long-term: Persistent chat logs (data/chats/, never expires)
  • OpenAI-Compatible - Works with OpenAI, Ollama, or any compatible endpoint

Quick Start #

Install #

git clone https://github.com/user/baia.git
cd baia

Configure #

Copy the example file and edit:

cp .env.example .env

Edit .env:

# For Ollama (local)
OPENAI_BASE_URL=http://host.docker.internal:11434/v1
MODEL=qwen3.5:27b
OPENAI_API_KEY=ollama

# For OpenAI
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-...
MODEL=gpt-4o

Run #

# Start the container
docker compose up -d


# interactive mode
docker exec -it baia-agent python -m baia.cli


# Single message
docker exec baia-agent python -m baia.cli --message "What's 2+2?"

# With custom model/endpoint
docker exec baia-agent python -m baia.cli --model gpt-4o --base-url https://api.openai.com/v1 --api-key sk-...

Tools #

The agent has four built-in tools:

Tool Description
execute_command Run shell commands
read_memory Read all short-term memories from memory.md
write_memory Save information to short-term memory (10k char limit, LRU eviction)
search_chat_logs Search persistent chat history for long-term recall

Memory System #

Short-term Memory (data/memory.md):

  • Max 10,000 characters with automatic LRU eviction
  • LLM-based deduplication merges related facts
  • Entire file loaded into context window on each read_memory call

Long-term Memory (data/chats/):

  • All conversations saved as timestamped JSON files
  • Never expires or cleaned up
  • Searchable via search_chat_logs tool for historical context

License #

MIT