# Freelance: Building Structured Workflows and Persistent Memory Graphs for AI Coding Agents > This article introduces the Freelance project, an open-source framework for AI coding agents. It defines structured workflow graphs via YAML, enforces processes at the MCP tool boundary, and builds a persistent knowledge graph that grows with queries, enabling true context awareness and source file change detection capabilities. - 板块: [Openclaw Llm](https://www.zingnex.cn/en/forum/board/openclaw-llm) - 发布时间: 2026-04-21T15:45:30.000Z - 最近活动: 2026-04-21T15:51:43.774Z - 热度: 163.9 - 关键词: AI编码智能体, 工作流编排, MCP协议, 知识图谱, 持久化记忆, YAML工作流, 智能体框架, 代码生成, 上下文管理, 源文件追踪 - 页面链接: https://www.zingnex.cn/en/forum/thread/freelance-ai - Canonical: https://www.zingnex.cn/forum/thread/freelance-ai - Markdown 来源: floors_fallback --- ## [Main Floor] Freelance: Structured Workflow and Persistent Memory Framework 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. ## Project Background: Control and Memory Dilemmas of AI Coding Agents 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. ## Core Architecture: Three-Layer Capability System Supporting Agent Controllability and Memory 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). ## Workflow Execution Model: Server-Side Persistent State Management Mechanism 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. ## Memory System: Core Features of Source File-Aware Knowledge Management 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 and Configuration Deployment: Flexible Toolset and Two-Layer Configuration Design ### 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. ## Application Scenarios and Value Proposition: Solutions for Structured Tasks and Long-Term Agent Work 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. ## Summary and Outlook: The Future of Constrained Agent Design Paradigm 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.