Freelance: Building Structured Workflows and Persistent Memory Graphs for AI Coding Agents

Freelance is an open-source framework for AI coding agents, designed to address two core challenges faced by current agents: lack of process control and fragile context memory. The framework achieves breakthroughs through three core capabilities: 1) Defining structured workflow graphs based on YAML to ensure controllable execution paths; 2) Enforcing workflow rules at the tool call boundary via the MCP protocol to achieve state persistence; 3) Building a persistent knowledge graph that grows with queries, with source file change detection capabilities, enabling agents to truly achieve context awareness.

With the widespread application of large language models in code generation, AI coding agents have become a hot topic, but they face two major pain points:

Lack of process control: Agents' behaviors are free and divergent, lacking structured execution paths, leading to low efficiency and easy omission of key steps in complex tasks.

Fragile context memory: Memory is limited by the model's context window, early information is easily forgotten, and there is no source file change detection capability, making it impossible to distinguish the validity of knowledge.

The Freelance project is a solution designed specifically for these pain points.

Freelance provides control and memory capabilities through the collaboration of three subsystems:

YAML-Based Workflow Graph Definition

The workflow is a directed graph, defined declaratively in YAML, with visual maintainability, a strict type system (node types like action/decision/gate), and subgraph composition capabilities (context and return value mapping).

MCP Boundary Enforcement

MCP is a standard interface for agent-tool interaction. Freelance enforces workflow rules at the call boundary: Agents must use freelance_start/freelance_advance to advance the process; gate nodes block until conditions are met; state is stored on the server, decoupled from agent sessions, solving the amnesia problem.

Persistent Knowledge Graph

Built-in SQLite knowledge graph supports: Compiling knowledge into atomic propositions, source tracing (file/hash/modification time), validity verification (hash matching to determine expiration), and incremental learning (only compiling gaps to avoid repetition).

Details of Freelance's workflow execution mechanism:

Initiation and Traversal: Agents call freelance_start to initiate; the system creates a server-side persistent traversal state, decoupled from sessions.

Node Processing: Each node receives descriptions and instructions; action nodes perform work, gate nodes verify condition expressions to block progress.

Edge Condition Evaluation: Transition edges have attached condition expressions (e.g., context.taskDone == true), evaluated at runtime to determine the next step.

Hook Mechanism: Nodes can declare onEnter hooks, which automatically execute built-in functions or local scripts before entry to prepare the context.

Core features of Freelance's memory system:

Propositional Knowledge Representation: Knowledge is represented as natural language propositions, independent and self-consistent, suitable for human-machine processing.

Content Hash Deduplication: Propositions with the same content are automatically deduplicated to avoid knowledge base bloat.

Git Branch Awareness: Knowledge validity is determined based on file hashes; automatic adaptation when switching branches (valid if hash matches, otherwise expired); knowledge converges after branch merging.

Set Organization: Propositions are grouped into named sets, supporting management by project/module; the same proposition can exist in multiple sets.

Tool Ecosystem

Divided into workflow control tools (e.g., freelance_list/freelance_start) and memory tools (e.g., memory_emit/memory_search). Write operations require active workflow traversal permission, while read operations are available at any time.

Configuration and Deployment

Two-layer configuration: config.yml (team-shared, version-controlled) and config.local.yml (machine-specific, git-ignored). Priority order: CLI parameters > environment variables > config.local.yml > config.yml > default values.

Scenarios suitable for Freelance:

Structured code review: Define multi-stage review processes to ensure PRs pass necessary checkpoints.

Complex refactoring tasks: Decompose large refactorings into manageable steps, allowing agents to execute without omissions.

Knowledge-intensive projects: Build project knowledge graphs to enable agents to truly understand the codebase.

Long-running agents: State persistence allows cross-session continuous work, suitable for complex tasks lasting hours/days.

Value proposition: Provide reliable structured processes and persistent memory to solve agent disorder and amnesia problems.

Freelance represents a new AI agent design paradigm—"constrained intelligence", which has more practical application value than unconstrained intelligence.

Future outlook: More built-in workflow templates, stronger memory query capabilities, and integration with more development tools. For AI-assisted development teams pursuing reliability and controllability, Freelance is a framework worth exploring.