OpenFin Agent System

A filesystem-based agent definition and runtime system for long-running AI agents with persistent memory, action logging, and reflection capabilities.

Overview

OpenFin allows you to define agents through filesystem organization, enabling:

• Long-running processes that persist state across sessions
• Temporal memory of actions and context
• Action logging for understanding agent behavior over time
• Reflection on capabilities, tools, and skills
• Filesystem-based definition - define agents, skills, and tools through directory structure

Filesystem Structure

agent/
├── PERSONALITY.md    # Agent personality definition
└── BEHAVIOUR.md      # Agent behavior definition

skills/
├── technical-writing/
├── coding/
├── marketing/
└── growth-hacking/

tools/
├── file-io/
├── network-io/
├── websearch/
├── sandbox/
├── docker/
├── code-running/
└── terminal-access/

Each directory can contain:

• README.md - Documentation describing the capability
• prompt.md - Versioned prompt definitions
• tool.py or skill.py - Executable Python modules

Features

Memory & State

• Persistent state across sessions
• Temporal memory with importance weighting
• Action logging with full context
• Memory retrieval by tags and importance

Reflection

• Automatic capability discovery
• Tool and skill evaluation
• Self-awareness of available capabilities
• Reflection history

Long-Running Agents

• Graceful shutdown handling
• Session management
• State persistence
• Context continuity

Usage

Running an Agent

python cli.py --base-path . --agent-id my-agent

Viewing Logs

View action logs:

python utils/view_logs.py --agent-id my-agent --limit 100

View memories:

python utils/view_logs.py --agent-id my-agent --memories

Filter by tool:

python utils/view_logs.py --agent-id my-agent --filter-tool file-io

Interactive Commands

• help - Show available commands
• context - Show full agent context
• memory - Show recent memories
• capabilities - Show available tools and skills
• action <type> <description> [tool:<name>] - Execute an action
• memory <content> [importance:<0.0-1.0>] [tags:<tag1,tag2>] - Add a memory
• exit - Shutdown the agent

Example

# Start the agent
python cli.py

# In the agent shell:
> capabilities
> action read_file Read config file tool:file-io
> memory Important configuration loaded importance:0.8 tags:config,setup
> context
> exit

Architecture

Core Components

• AgentRuntime - Main runtime for executing agents
• MemoryStore - Manages persistent memory and state
• ReflectionEngine - Handles capability discovery and reflection
• AgentDefinition - Loads agent personality and behavior

Memory Structure

Memory is stored in memory/<agent-id>/:

• actions.jsonl - Action log (append-only)
• memory.json - Important memories
• state.json - Agent state

Development

Adding a Tool

1. Create directory: tools/my-tool/
2. Add README.md with description and capabilities
3. Optionally add tool.py with execute(input_data, context) function

Adding a Skill

1. Create directory: skills/my-skill/
2. Add README.md with description and capabilities
3. Optionally add skill.py with execute(input_data, context) function

Versioning

Files can include version information in their content. The system will parse version numbers from markdown files.

Requirements

• Python 3.8+
• No external dependencies (uses only standard library)

License

MIT