floop

Persistent memory for AI coding agents.

floop captures corrections you make to AI agents, extracts reusable behaviors, and activates them in the right context — so your agents learn from mistakes and stay consistent across sessions. It uses spreading activation (inspired by how the brain retrieves memories) to build an associative "blast radius" around your current work — not just direct matches, but related behaviors that provide useful context and bolster the AI's understanding.

Features

• Learns from corrections — Tell the agent what it did wrong and what to do instead; floop turns that into a durable behavior
• Context-aware activation — Behaviors fire based on file type, task, and semantic relevance — not a static prompt dump
• Spreading activation — Graph-based memory retrieval inspired by cognitive science (Collins & Loftus, ACT-R) — triggered behaviors propagate energy to related nodes, pulling in associative context
• Token-optimized — Budget-aware assembly keeps injected context within limits
• MCP server — Works with any AI tool that supports the Model Context Protocol
• CLI-first — Every operation available as a command with --json output for agent consumption

Quick Start

# Install
go install github.com/nvandessel/feedback-loop/cmd/floop@latest

# Initialize in your project
cd your-project
floop init

# Teach it something
floop learn --wrong "Used fmt.Println for errors" --right "Use log.Fatal or return error"

# See what it learned
floop list

# See what's active for your current context
floop active

Integrate with your AI tool

Add floop as an MCP server so your AI tool loads behaviors automatically.

Claude Code (~/.claude/settings.json):

{
  "mcpServers": {
    "floop": {
      "command": "floop",
      "args": ["mcp-server"]
    }
  }
}

See docs/integrations/ for setup guides for Cursor, Windsurf, Copilot, and more.

How It Works

When you correct your AI agent, floop captures the correction and extracts a behavior — a reusable rule with context conditions. Behaviors are stored as nodes in a graph, connected by typed edges (similar-to, learned-from, requires, conflicts). When you start a session, floop builds a context snapshot (file types, task, project) and uses spreading activation to propagate energy through the graph from seed nodes. This doesn't just retrieve direct matches — energy cascades outward through associations, pulling in related behaviors that provide useful context. The result is a focused but rich set of behaviors tuned to your current work, like the brain activating related memories through associative networks.

Documentation

• Integration guides — Setup for Claude Code, Cursor, Windsurf, and others
• Research & theory — The cognitive science behind spreading activation
• Origin story — How floop came to be
• Contributing — How to contribute
• Changelog — Release history

Project Status

This is a hobby project I'm building in my free time. It's in early alpha — things work, but the API may change between minor versions and there's plenty left to build. Contributions and feedback are welcome, but please set expectations accordingly.

License

Apache License 2.0