fableforge-agent-runtime 0.1.0

Persistent agent daemon — systemd for AI agents

AgentRuntime — systemd for AI Agents

A persistent agent daemon that manages AI agent processes, serializes state, and resumes sessions. Think of it as systemd for AI agents — start, pause, resume, and checkpoint agent sessions with full state persistence.

Architecture

┌─────────────┐     ┌──────────────────┐     ┌────────────────┐
│   CLI       │────▶│   FastAPI Server │────▶│  SessionManager│
│  (agentd)   │     │   (port 8721)    │     │                │
└─────────────┘     └──────────────────┘     └───────┬────────┘
                                                      │
                              ┌─────────────────────────┼─────────────────────┐
                              │                         │                     │
                     ┌────────▼────────┐      ┌────────▼────────┐   ┌───────▼──────┐
                     │ StateSerializer │      │   MemoryStore   │   │    Daemon     │
                     │   (SQLite)      │      │  (Short+Long)   │   │  (Heartbeat)  │
                     └─────────────────┘      └─────────────────┘   └──────────────┘

Features

• Session Lifecycle: Create, start, pause, resume, stop agent sessions
• State Persistence: Full session state serialized to SQLite
• Checkpoints: Save and restore complete state at any point
• Memory Management: Short-term (conversation context) and long-term (key-value with semantic search)
• Memory Consolidation: Auto-summarize old short-term memories
• Auto-Checkpoint: Configurable interval for automatic state snapshots
• Graceful Shutdown: State preservation on daemon stop
• Session Timeout: Automatic cleanup of stopped sessions
• REST API: Full HTTP API via FastAPI
• CLI: Command-line interface for all operations
• Docker: Production-ready container image

Quick Start

Install

pip install -e .

Start the Daemon

agentd start --port 8721

Create a Session

agentd create --name "my-agent" --model fableforge-14b --system-prompt "You are a helpful assistant"

List Sessions

agentd list

Resume a Session

agentd resume <session-id> --checkpoint-id <checkpoint-id>

Stop the Daemon

agentd stop

API Reference

POST /sessions

Create a new session.

{
  "name": "my-agent",
  "model": "fableforge-14b",
  "system_prompt": "You are a helpful assistant.",
  "tools": ["search", "calculator"]
}

GET /sessions

List all sessions.

GET /sessions/{id}

Get session state.

POST /sessions/{id}/start

Start a session (begins heartbeat and auto-checkpoint).

POST /sessions/{id}/pause

Pause a running session (creates checkpoint, cancels heartbeat).

POST /sessions/{id}/resume

Resume a paused or stopped session.

{
  "session_id": "abc123",
  "checkpoint_id": "cp_456"
}

POST /sessions/{id}/stop

Stop a session (creates final checkpoint).

GET /sessions/{id}/memory

List memory keys or retrieve specific key: ?key=my_key

POST /sessions/{id}/memory

Store a memory entry.

{
  "key": "user_preference",
  "value": {"theme": "dark", "language": "en"}
}

GET /sessions/{id}/checkpoints

List all checkpoints for a session.

POST /sessions/{id}/checkpoints

Create a checkpoint. Query param: ?label=my-checkpoint

GET /health

Daemon health status.

Session States

CREATED ──▶ RUNNING ──◆──▶ PAUSED ──▶ RUNNING
              │    │         │
              │    └──▶ STOPPED
              └──▶ ERROR

Memory Architecture

Short-Term Memory

• Last N messages per session (default 50)
• Automatic pruning when window exceeded
• Used for conversation context

Long-Term Memory

• Key-value store with optional embeddings
• Cosine similarity semantic search
• Persistent across sessions
• Consolidation: summarizes old short-term into long-term

Consolidation

When short-term memory exceeds a threshold, the daemon:

1. Summarizes the recent conversation
2. Stores the summary in long-term memory
3. Prunes old short-term entries

Configuration

Env Variable	Default	Description
AGENT_RUNTIME_DB	~/.agent_runtime/state.db	SQLite database path
AGENT_RUNTIME_MEMORY_DB	~/.agent_runtime/memory.db	Memory database path
AGENT_RUNTIME_PORT	8721	HTTP server port
AGENT_RUNTIME_HOST	0.0.0.0	HTTP server bind address
AGENT_RUNTIME_CHECKPOINT_INTERVAL	60	Auto-checkpoint interval (seconds)
AGENT_RUNTIME_SESSION_TIMEOUT	3600	Session timeout (seconds)

Docker

docker build -f docker/Dockerfile -t agent-runtime .
docker run -p 8721:8721 -v agent_data:/root/.agent_runtime agent-runtime

Testing

pip install -e ".[dev]"
pytest tests/ -v

Project Structure

agent-runtime/
├── pyproject.toml
├── docker/
│   └── Dockerfile
├── src/
│   └── agent_runtime/
│       ├── __init__.py
│       ├── models.py              # Pydantic models
│       ├── state_serializer.py    # SQLite state persistence
│       ├── memory_store.py        # Short/long-term memory
│       ├── session_manager.py     # Session lifecycle
│       ├── daemon.py              # Background daemon process
│       ├── server.py              # FastAPI HTTP server
│       └── cli.py                 # CLI interface
├── tests/
│   └── test_state_serializer.py
└── README.md

License

MIT

Ecosystem

Part of the FableForge ecosystem — 21 open-source projects built from 210K real agent traces:

Project	Description
Anvil	Self-verified coding agent
VerifyLoop	Plan→Execute→Verify→Recover framework
ErrorRecovery	Self-healing middleware (3,725 error patterns)
FableForge-14B	The fine-tuned 14B model (4-stage training)
ShellWhisperer	1.5B edge agent (phone/RPi, 50ms)
ReasonCritic	Verification model (130 benchmark tasks)
TraceCompiler	Compile traces → LoRA skills
AgentRuntime	Persistent agent daemon (systemd for AI)
AgentSwarm	Multi-agent from real trace transitions
AgentTelemetry	Datadog for agents (token tracking, costs)
BenchAgent	HumanEval for tool-use (107 tasks)
AgentDev	VSCode extension with verification
TraceViz	Trace replay visualizer (Next.js)
AgentSkills	npm for agent behaviors
AgentCurriculum	5-stage progressive training
AgentFuzzer	Adversarial testing for agents
AgentConstitution	Safety guardrails from traces
CostOptimizer	Token cost reduction (50-80%)
AgentProfiler	Behavioral fingerprinting
TrajectoryDistiller	Trace→training data pipeline
Fable5-Dataset	HuggingFace dataset release