DEV Community

Cover image for Flowork Agent: Self-Hosted AI Agent OS with Persistent Memory and Built-in Security
floworkos
floworkos

Posted on

Flowork Agent: Self-Hosted AI Agent OS with Persistent Memory and Built-in Security

#ai #selfhosted #security #productivity

🧠 The Mind: A Brain That Learns, A Doctrine That Won't Lie

Most AI systems treat memory like a luxury — something you pay extra for, that resets between sessions, that never learns from its own mistakes. Flowork's memory is foundational. Every agent owns a persistent brain that lives in its own folder, carries its experience forward, and gets smarter by studying what went wrong.

The Brain: Local-First Memory That Never Forgets

Each agent's memory lives in its own SQLite database (state.db) — clone the folder to a USB stick and the entire mind travels with it. No cloud sync, no third-party embeddings, no dependency on a vector database service.

The brain has four wings — separate storage layers for different kinds of knowledge:

  • General — facts and observations the agent has seen.
  • Experience — lessons from its own past interactions; when something worked or failed, it goes here.
  • Eureka — high-level patterns discovered during idle reflection; the brain's own insights.
  • Constitution — the agent's founding rules and identity constraints (immutable unless you edit the agent).

All memory is searchable via SQLite FTS5 (full-text search) with BM25 ranking — fast, instant, completely offline. No embeddings, no neural overhead, no external API calls. When an agent encounters a new message, it:

  1. Stores what it sees (wings are deduplicated by content hash).
  2. Recalls related memories ranked by relevance.
  3. Thinks (LLM call) with those memories in context.
  4. Replies and logs the outcome.

Memory first, then reasoning. The recalled context shapes every turn.

Educational Errors: Mistakes as Redemptive Lessons

This is where Flowork departs from standard practice. Most AI systems hide their mistakes — suppress them in logs, fine-tune them away, pretend they never happened. Flowork treats every error as education.

The system captures four dimensions of each mistake:

  • Capture — what went wrong and why (the failure is logged with full context).
  • Explain — a structured analysis of the root cause.
  • Retain — the mistake is stored in the agent's brain (tagged, dated, ranked by severity).
  • Redemptive — the agent isn't deleted or punished; it's given a chance to correct and learn.

On the next similar situation, the agent recalls that past mistake and has a concrete reason to avoid the same path. The loop is: fail → study the failure → remember it → recognize the pattern next time → choose differently. No retraining, no GPU cost, no human intervention — learning happens at runtime, in the agent's own brain.

Over time, the agent's experience and eureka wings fill with its own hard-won knowledge. You can inspect them; they're plain text and searchable.

The Router: Anti-Hallucination by Architecture

When you aim an agent at a raw LLM API, it gets no memory context and no guard rails. Flowork's router (http://127.0.0.1:2402/v1/chat/completions) changes that.

Before the LLM sees a prompt, the router injects three layers of protection:

  1. The agent's own past mistakes — ranked by relevance and recency. If the agent hallucinated about database queries yesterday, that mistake appears in today's system prompt as "you made this error before; here's why."
  2. The constitution — sacred rules and identity constraints (e.g., "you will not promise delivery dates you can't meet"; "you are the truth-teller, not the idea-person"). These are enforced on every turn.
  3. The 5W1H gate — a structural check that forces the agent to reason through who, what, when, where, why, how before answering.

This is deterministic anti-hallucination — no fine-tuning, no special training. The mistakes the brain keeps are the exact antibodies the router injects back.

You can swap the underlying model (Haiku, GPT-4, a local Llama) in one place; the router architecture stays the same. One door, multiple models.

Dream & Eureka: Idle Self-Reflection

While an agent is idle (no messages for a few minutes), a quiet background pass runs — the agent "dreams." It:

  • Scans its recent experience and general wings.
  • Identifies recurring patterns (mistakes it made multiple times, solutions that worked, themes in its interactions).
  • Consolidates those patterns into eureka insights — higher-level knowledge.

The agent's brain grows from its own use. No external training loop, no human labeling, no data exports to a lab. Every agent is its own researcher.

The Antibody Scanner: Self-Protecting Memory

A poisoned memory can corrupt reasoning — a false fact lodged in the brain, repeatedly recalled, becoming "true." Flowork includes an antibody scanner that runs in the background:

  • Checks stored memories against a quarantine list (known hallucinations, contradictions, unsafe facts).
  • Isolates suspicious memories without deleting them (so you can inspect what went wrong).
  • Prevents the agent from recalling and repeating poisoned context.

The agent's brain is transparent and editable; you can always open state.db and see what it "knows."

🔌 MCP: Two-Way Integration

Model Context Protocol (MCP) is a standard for connecting tools and data sources. Flowork speaks it both ways.

As an MCP Client

An agent can use external MCP servers as tools — GitHub filesystem access, database queries, web scraping, code execution. When an agent calls tool.run("github-ls-files"), the kernel routes it through the MCP client to the registered server. Standard tools (117 built-in) live in the kernel; external ones come through MCP.

As an MCP Server

Expose your Flowork agents to Claude Desktop, Cursor, or any MCP client. A third-party app sends a message to your local Flowork instance and an agent responds — the agent's memory and constitution apply.

This means:

  • Your agents are usable everywhere — Claude can talk to your agent directly.
  • You stay in control — the agent runs on your machine, uses your API keys (from Settings), respects its own rules.
  • No vendor lock-in — your agents aren't trapped in a Flowork-only ecosystem.

📊 Self-Hosted Autonomy: The Microkernel in Action

The entire system runs on a microkernel architecture. The core (written in Go) is frozen — a tiny contract that never changes. Everything else — agents, tools, scanners, connectors, MCP servers — is a plug-and-play module.

  • An agent is sandboxed in WebAssembly — it can only call capabilities the kernel grants (llm.complete, brain_search, tool.run, send_message). It cannot fork processes, read arbitrary files, or make raw network calls.
  • Each agent owns its folder — the folder contains the agent's code (compiled WASM), its database (the brain), its settings, and its logs. Clone the folder; the agent and its entire history go with you.
  • Everything is offline-capable — the agent can think, remember, and reason without touching the internet. Tools and MCP servers are your choice; the agent itself works fully disconnected.
  • The kernel guards itself — the Guardian module watches the core for tampering. If a file is modified, the system detects it and drops into safe-mode, refusing to run untrusted code.

This architecture means:

  • A broken agent doesn't crash the system; you fix its folder and restart it.
  • You can audit every agent's behavior (logs, memory, tool calls) independently.
  • No "one size fits all" LLM config — each agent can use a different model, a different memory strategy, a different set of rules.
  • Agents don't interfere with each other unless you wire them together (via groups).

🛡️ Security Radar: The Built-In Guardian

No other agent framework ships a real security scanner. Flowork does.

The Guardian watches the code that agents run — specifically, tool code and MCP handlers. Before execution, the scanner:

  • Analyzes the bytecode for dangerous patterns (shell injection, path traversal, unsafe file I/O).
  • Flags suspicious code (but doesn't auto-block; humans review and decide).
  • Logs all capability calls — every time an agent asks for tool.run or network access, it's recorded.
  • Enforces capability boundaries — an agent can't escalate its own permissions; only the owner can grant new capabilities.

The kernel itself is frozen, watched by the Guardian, and will refuse to load if it detects tampering.

🚀 Getting Started: One Command 

git clone https://github.com/flowork-os/Flowork_Agent.git
cd Flowork_Agent
./start.sh
Enter fullscreen mode Exit fullscreen mode

On first run, start.sh compiles the binary (requires Go 1.25+), then serves the control panel at http://127.0.0.1:1987. Create your owner account, and you're in.

  • No Docker, no accounts, no cloud. Everything runs on your machine.
  • Works on Linux, macOS, and Windows.
  • Stop with ./stop.sh, restart with ./restart.sh.
  • Your agents, your memory, your rules — forever on your hardware.

The handbook is in the repo (plain Markdown, readable before you run anything). Start with Getting Started to understand the UI, then build or clone an agent and watch it learn.

Why This Matters

Most agent frameworks are either:

  1. Cloud-first — your data leaves your machine, your agent resets on logout, you're renting intelligence.
  2. Code-heavy — you wire tools manually in YAML or Python, and everything breaks when dependencies update.
  3. Forgetting — no memory, no learning, no improvement over time.

Flowork is different. It's a genuine operating system for agents — a place where they live, own themselves, remember their past, and get smarter. The microkernel stays forever. Your agents and their brains travel with you. Security is baked in, not bolted on.

Build one agent, run it offline, give it a memory that never forgets, and watch it learn from its own mistakes. That's the offer.

🔗 Open source on GitHub

💬 Join the Flowork community on Telegram: https://t.me/+55oqrk75lc43YWE1

Top comments (0)