A modular Go toolkit for extensible AI applications, long-term memory, provider integrations, voice, and local interactive workflows.
FlowCraft is a Go workspace for building and evaluating AI applications without tying application code to one model provider or execution model. Graphs are one built-in option, not a required architecture. Use the SDK packages directly, or start with Claw for a runnable local workspace.
cmd/claw— Local CLI and TUI for creating agent workspaces, running conversations, inspecting memory, serving debug APIs, and executing scripted tests.sdk— Agent, graph, engine, model, tool, event, telemetry, and workspace contracts.memory— Recall, conversation history, knowledge retrieval, text processing, and persistence backends.sdkx— Provider adapters and optional implementations for LLMs, embeddings, reranking, checkpointing, sandboxing, and Claw.voice— Real-time STT → LLM → TTS pipelines with VAD, barge-in, and WebRTC.
The library layers are independently versioned Go modules. Applications can adopt only the layers they need.
| You need… | FlowCraft provides… |
|---|---|
| A runnable local agent environment | Claw workspaces, TUI sessions, debug HTTP endpoints, and scripted tests |
| Explicit execution contracts | A small engine.Engine / engine.Host boundary that supports graph, scripted, remote, or custom execution models |
| Long-term memory | Hybrid recall, histories, knowledge stores, retrieval indexes, and SQLite/Postgres backends |
| Provider portability | OpenAI, Anthropic, DeepSeek, MiniMax, and Volcengine adapters behind shared SDK interfaces |
| Multi-agent composition | Kanban agent-as-tool delegation that can run over graph or custom engines |
| Real-time voice | VAD, endpointing, barge-in, STT/TTS contracts, and WebRTC integration |
Claw is the fastest way to explore the stack. It creates persistent local workspaces, opens an interactive TUI, exposes debug endpoints, and runs scripted agent tests.
cd cmd/claw
go run . help
# Open the interactive TUI and select an embedded raid config.
go run . tui newBuild a reusable local binary:
cd cmd/claw
go build -o claw .
./claw helpSee cmd/claw/README.md for workspace, TUI, debug API,
configuration, and test commands.
Use sdk directly and add memory or sdkx when the application needs recall,
history, knowledge, persistence, or provider adapters. Applications execute any
engine.Engine through agent.Run; the bundled graph runner is one available
implementation, alongside scripted, remote, or application-defined engines.
sdk/agent/run_test.go— minimalagent.Runpatternsexamples/voice-pipeline/setup.go— a real graph-runner build wiring an LLM provider + script node
p := voice.NewPipeline(
sttProvider, // any voice/stt backend (e.g. bytedance, …)
ttsProvider, // any voice/tts backend (e.g. minimax, …)
eng, // engine.Engine driving each turn
agent.Agent{ID: "voice"},
voice.WithSTTOptions(stt.WithLanguage("zh"), stt.WithTargetSampleRate(16000)),
voice.WithTTSOptions(tts.WithCodec(audio.CodecMP3)),
)End-to-end: examples/voice-pipeline/ — a runnable WebRTC voice agent.
The SDK defines the execution contracts. Memory, provider adapters, voice, and Claw compose those contracts without becoming dependencies of the core.
┌──────────────────────┐
│ Your application │
└──────────┬───────────┘
│
┌─────────────────────┼─────────────────────┐
│ │ │
┌──────▼──────┐ ┌──────▼──────┐ ┌──────▼──────┐
│ cmd/claw │ │ voice/ │ │ sdkx/ │
│ CLI · TUI · │ │ STT · TTS · │ │ providers · │
│ debug · test│ │ VAD · WebRTC│ │ persistence │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└──────────────┬──────┴──────────────┬──────┘
│ │
┌──────▼──────┐ ┌──────▼───────┐
│ memory/ │──────►│ sdk/ │
│ recall · │ │ agent · graph│
│ history · │ │ engine · tool│
│ knowledge │ │ event · model│
└─────────────┘ └──────────────┘
Layering rule: sdk/engine is a leaf package. It does not import agent,
graph, LLM, or tool packages. Execution implementations satisfy
engine.Engine; hosts provide capabilities through engine.Host. Memory lives
in its own module and depends on SDK contracts, never the reverse.
| Path | Role | Distribution |
|---|---|---|
cmd/claw |
Local workspace runner, TUI, debug API, and scripted-test CLI | Source-built command |
sdk |
Agent execution contracts, graph runtime, tools, models, events, and telemetry | Versioned Go module |
memory |
Recall, history, knowledge, retrieval, text processing, and stores | Versioned Go module |
sdkx |
Provider, persistence, sandbox, and application adapters | Versioned Go module |
voice |
Real-time STT, TTS, VAD, audio, and WebRTC pipeline | Versioned Go module |
eval |
Offline and synthetic quality-evaluation harnesses | Workspace module |
examples |
Runnable recall-chatbot and voice-pipeline integrations | Examples |
tests/conformance |
Provider conformance suites | Tests |
- Persistent workspaces with config, history, memory, and graph state.
- Interactive TUI plus an embeddable Go runtime.
- Debug HTTP endpoints for workspace, history, memory, and recall inspection.
- Scripted and simulation-style tests with captured workspace artifacts.
- Three-lane retrieval (BM25 + vector + entity), fused via Reciprocal Rank Fusion (K=60), then re-weighted by entity-overlap boost, supersede decay, and time decay.
- Predicate alias normalisation so "favourite color" and "favorite colour" hit the same memory.
- Pluggable
retrieval.Indexbackend —memory/retrieval/memory(in-memory),memory/retrieval/sqlite(SQLite), andmemory/retrieval/postgres(Postgres + pgvector) ship in-tree; bring your own by implementingretrieval.Index.
Subject-routed event bus — every step emits structured envelopes.Checkpoint/CheckpointStorecontract — pause and resume an agent across restarts.Interrupt/Waitsemantics that compose cleanly withcontext.Context.
- VAD with hysteresis, endpointing, barge-in.
- WebRTC ingress / egress.
- Provider-agnostic: any
sdkxSTT/TTS backend works.
The canonical reference is the per-package doc.go files, browsable on pkg.go.dev:
cmd/claw/README.md— CLI, TUI, workspace, debug API, and scripted-test guide- pkg.go.dev/github.com/GizClaw/flowcraft/sdk — core primitives (agent, engine, graph, llm, tool, telemetry, …)
- pkg.go.dev/github.com/GizClaw/flowcraft/memory — recall, history, knowledge, retrieval, and text packages
- pkg.go.dev/github.com/GizClaw/flowcraft/sdkx — provider implementations
- pkg.go.dev/github.com/GizClaw/flowcraft/voice — voice pipeline
Worked examples live under examples/ — each one is runnable end-to-end with a single command.
The active project surface is sdk, memory, sdkx, voice, and Claw.
Library modules are released independently and remain pre-1.0. Claw currently
ships from source as the local interactive runner.
Durable execution contracts, Postgres and SQLite checkpoint stores, OTel instrumentation, quality-evaluation harnesses, and retrieval end-to-end coverage are maintained in-tree.
The next milestone is the assertion-graph memory model: first-class observations, assertions, and links with provenance, so recall can retrieve linked evidence packets instead of isolated facts.
API surface is governed by SemVer per module. Breaking changes may ship as minor
bumps until a module reaches v1.0.0.
git clone https://github.com/GizClaw/flowcraft
cd flowcraft
make help # list every target
make ci # vet + test for all in-tree modules
make release-check # validate changesets and the pending release planThis repository is a Go workspace. Active members are sdk, memory, sdkx,
voice, cmd/claw, and eval. Some examples and test harnesses intentionally
run with GOWORK=off against pinned released modules.
Issues and pull requests are welcome. Before opening a PR:
make cishould be green.gofmt -l .should print nothing.- Tests for new features. New behaviour without a test won't merge.
- Commit messages follow Conventional Commits (
feat:,fix:,docs:,refactor:,test:,chore:).
Library releases are declared explicitly with immutable .release/*.json
changesets for sdk, memory, sdkx, and voice; a changeset is optional for
ordinary PRs. After merge, automation aggregates pending summaries into a
Release PR that updates CHANGELOG.md. Merging that PR runs isolated tidy,
build, vet, and race-test gates before all planned tags are pushed atomically.
Claw remains source-only and does not receive module tags. See
CONTRIBUTING.md for the contract and coordinated dependency
rules.
For larger work, please open a discussion or draft RFC issue first — it's much faster than reviewing a 5k-line PR cold.
MIT © GizClaw