Goink: a desktop AI novel-writing agent with structured state tracking and local semantic search

The failure Goink is built around: an assistant that forgets chapter five by chapter thirty

The README opens with a concrete complaint rather than a feature list. Generic chat models lose the protagonist's name by the fifth chapter; by the thirtieth you are scrolling back to find a planted detail; and after finishing a chapter you have to remind the model to update character state and check arc progress. Goink's answer is not a better prompt. It is a persistent structured store that the agent reads and writes on its own.

The target user is someone writing novel-length fiction in Chinese, on a desktop, who is willing to supply an LLM API key. The README states the installer ships templates for DeepSeek, GLM and MiMo and is compatible with the OpenAI format, so the model is a configuration choice rather than a hard dependency. The stated package is under 60MB and does not require Python, Node.js, a separate database or a GPU. That combination (structured memory, no runtime stack to assemble) is the specific gap this project is aiming at, and it is a narrower gap than "AI writing tool" suggests.

A ReAct loop with 31 tools, not a chapter-by-chapter pipeline

The architecture the README describes is an agent loop written in Go, streaming over SSE, exposing 31 function-calling tools, with support for nested sub-agents. The distinction the documentation draws is deliberate: this is not a pipeline where chapter output is handed to the next stage. The model decides which tool to call, with which arguments, and what to do next, inside the current conversation.

That choice has consequences. A pipeline is inspectable and cheap to reason about; an agent loop is neither, which is why the project layers three separate maintenance mechanisms on top. First, the system prompt hardcodes the maintenance procedure. Second, after a long generation the system injects a checklist covering character changes, foreshadowing status, arc nodes and reader knowledge. Third, an optional review sub-agent reads the chapter against system state independently and writes any inconsistency into the conversation for the main agent to fix. The README's phrasing is that the agent is forced to self-check item by item.

Whether three overlapping mechanisms are necessary or a symptom of an unreliable loop is a fair question. The honest reading is that the project assumes the model will skip maintenance if not pushed, and pays for that assumption with prompt overhead on every long generation.

The state model: directed relationships, foreshadowing deadlines, arcs as node chains, locations as a graph

This is where Goink differs most from a chat wrapper. Character records hold personality, abilities and background, and relationships are a directed graph with history. The README's example is that A regards B as a mentor while privately wary, and B regards A with respect while concealing something: two independent records. When a relationship changes, the old record is kept so the evolution can be reviewed.

Foreshadowing entries carry a target recovery chapter and an importance level. The system warns as the target approaches and flags entries that pass it unrecovered. Chapter plans are split into three bands: next chapter, near term, long term. Arcs are chains of nodes, each tied to a target chapter, advanced automatically when a chapter is written; the README says a story typically tracks three to five arcs in parallel. Locations form a hierarchy (kingdom, palace, hall) plus spatial connectivity (two places joined by a mountain road), and the agent can query details, children, connections or the whole map. Reader knowledge tracks what the audience knows, what questions they are waiting on, and what they have misread.

The design decision worth naming is that reader knowledge is modelled as first-class state. Most writing tools treat suspense as a property of the prose. Here it is a table the agent can query before deciding whether to reveal something, which is a more mechanical but more controllable approach to pacing reveals.

Local semantic search: bge-small-zh-v1.5 under ONNX Runtime with sqlite-vec and MMR reranking

Search is not keyword matching. The README's example is asking about a pendant and retrieving passages that never use the word but imply it. The stack is stated plainly: a BGE Chinese semantic model running under ONNX Runtime, specifically bge-small-zh-v1.5 with int8 quantization, a sqlite-vec vector index, and MMR reranking to reduce redundancy. Indexing runs in the background incrementally after a chapter is written. No network and no extra configuration are required for the search path itself.

Two things follow. The embedding model is small and quantized, so retrieval quality is bounded by that choice; the project is trading recall on subtle queries for a sub-60MB installer and CPU-only operation. And because the index is incremental and background, there is a window after writing where a freshly written passage may not yet be retrievable. The README does not describe how that window is handled, so treat it as unverified. The agent can also search proactively while drafting, which is the mechanism behind the consistency claim, but the same index lag applies.

Skills as markdown files: three layers, three trigger modes, hot reload

A Skill is a single .md file with YAML frontmatter and a markdown body. The frontmatter shown in the README carries name, description, category and mode. Layers override by priority: novel-level beats user-level beats builtin. Builtin skills are packaged read-only; user skills live in ~/.goink/skills/; novel skills live in {novel}/skills/. Edits are hot-reloaded without restarting.

The trigger modes are the part with real design content. auto skills can be invoked by the model or by the user typing a slash command and appear in a catalogue. manual skills are slash-command only and do not appear in the catalogue. always skills are injected in full at the start of a session, and the README notes they do not appear in the catalogue. The builtin set includes scene beats, dialogue subtext, pacing, suspense hooks, character design, revision, de-AI-flavoured prose and co-creation ideation, plus manual commands named review, memory, collect and next.

The always mode is the one to watch. Injecting a skill's full text at session start consumes context on every conversation, and with several always skills the cost compounds in a way the README does not quantify. The layer priority also means a novel-level file silently shadows a user-level file of the same name, which is convenient until you forget which layer you edited.

Style distillation is a related feature: paste a sample of prose, and the model decomposes it across six dimensions (sentence structure, word choice, rhetorical devices, pacing, narrative distance, tone) into a generated imitation skill, loadable afterwards by slash command. The README is explicit that this extracts patterns rather than substituting keywords.

Diff approval, Git history and a two-layer file sandbox

The agent does not write to the manuscript directly. Every edit produces a diff first, which the user approves, rejects, or answers with feedback so the model revises. There is an automatic mode for continuous drafting. All changes are committed to an internal Git history, with automatic commit per conversation and revert to any state.

File access is restricted by two layers: a regex whitelist permitting only paths such as chapters/, outlines/ and goink.md, and a SafePath check against traversal. Before writing, the file is re-read and compared so manual edits are not overwritten.

The whitelist is the sharpest limitation in the whole design. It is a fixed set of allowed paths, so any project structure that puts manuscript content elsewhere will not work without changing the source. The README does not document a configuration key to extend the whitelist, and no such key appears in the material. If your workflow depends on a different directory layout, verify this before adopting rather than after.

Installation and build: installers, or Go 1.25 plus Wails v2 and system GTK/WebKit packages

The primary path is a release binary: an installer on Windows, a DMG on macOS, an AppImage on Linux. The README warns that Windows SmartScreen may flag the unsigned build, requiring More info then Run anyway. A mirror download link is offered for users with poor connectivity. An LLM API key is required.

Building from source is documented as a short sequence. On Debian-family systems the prerequisites are libsqlite3-dev, libgtk-3-dev, libwebkit2gtk-4.1-dev and gcc. Then git clone https://github.com/sigpanic/goink, cd goink, make deps, and either make build for a production build or make dev for a hot-reload development mode. The toolchain versions the README advertises are Go 1.25, Wails v2.12, React 19, TypeScript 6, Tailwind 4.3, SQLite 3 and ONNX Runtime 1.26.

Those are unusual version numbers to pin in a README, and they are worth reading as a maintenance signal: this is a project tracking current releases of its dependencies rather than sitting on older ones. The cost is that building from source requires a reasonably current toolchain, and the Linux build pulls in WebKitGTK 4.1 specifically, which not every distribution ships by default.

Where Goink is the wrong tool, and what it is not replacing

Goink is a desktop GUI application. There is no indication in the material of a headless mode, a server deployment, a CLI, or an HTTP API for external callers. If you want writing assistance inside an existing editor, or a service multiple people hit, this is not that. The Wails plus WebView architecture also means the UI is bound to a desktop session.

The comparison that matters is against a general chat model plus your own notes, which is what most long-form AI drafting looks like today. The difference in approach is concrete: with a chat model you re-explain the cast every session and maintain notes by hand, and the model's edits are opaque text you paste back. Goink moves the notes into queryable tables, forces the agent through tool calls to read and write them, and gates every text change behind a diff. That is more machinery, and it is machinery that only pays off past the length where you would otherwise lose track. For a short story, the state layer is overhead you will not exercise.

Alternatives in the same space include general-purpose agent frameworks wired to a file system, and dedicated novel tools that keep state in prose notes rather than tables. The material here does not name competitors, so the fair statement is narrower: Goink's distinguishing choice is structured, queryable state plus local embedding search in a single signed-agnostic desktop binary, and if you do not need those two things, the extra layers cost you context and setup for nothing.

Licence, maintenance and what to verify before you commit a manuscript

Goink is licensed under AGPL-3.0, and the README points to a separate NOTICE file describing additional terms under AGPLv3 Section 7. That combination matters for anyone planning to embed the agent engine in a network service or a closed-source product: the network-use clause and the Section 7 additional terms both need reading before you build on it. This is a description of what the repository states, not legal advice.

Maintenance cost is visible in the release cadence: v1.4.1, v1.4.2 and v1.4.3 landed between 15 August and 6 September 2026, roughly every one to two weeks. Frequent releases are good for fixes and bad for the assumption that a given version is stable. There is no long-term support branch mentioned, and the dependency pins are aggressive, so expect to move forward rather than stay put.

The practical cost of upgrading is the skill and state layer. Skills are plain markdown in ~/.goink/skills/ and {novel}/skills/, so they survive a binary swap. Story state lives in SQLite under the application's control, and the README does not document a migration or export path for it. Before you put a real manuscript into Goink, confirm that the internal Git history is actually producing commits you can revert to, and confirm the whitelist covers every path you need the agent to read. Those two checks are cheap and they are the ones that determine whether the tool is recoverable when something goes wrong.

Editorial conclusion

Adopt Goink if you write long Chinese-language fiction, want an agent that maintains character, foreshadowing and arc state rather than a chat window, and are comfortable with a desktop binary plus your own LLM API key. Do not adopt it if you need a headless service, a web deployment, or permissive licensing for a closed-source derivative, because AGPL-3.0 plus the NOTICE terms under Section 7 apply. Before committing a manuscript, verify three things in the app itself: that your chosen provider works through the OpenAI-compatible path, that the built-in Git history actually captures each conversation as the README states, and that the regex whitelist plus SafePath sandbox permits every directory you intend the agent to touch.

Official sources

1. Issues
2. License: AGPL-3.0
3. README
4. Releases
5. sigpanic/goink on GitHub