# sigpanic/goink: a desktop AI writing system that keeps its own story state

> Goink is a Go and Wails desktop app for long-form novel writing. Its pitch is structured memory: character records, foreshadowing, arcs, locations and reader knowledge that the agent queries and updates itself, plus local semantic search over the manuscript.

**sigpanic/goink** — Goink 桌面 AI 小说创作助手，对话式写作 + 自动状态追踪 + 本地语义搜索。跨平台开箱即用。AI Agent Novel Generator.

- Repository: https://github.com/sigpanic/goink
- Stars: 380 · Forks: 60
- Language: Go
- License: AGPL-3.0
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/sigpanic-goink

## The problem Goink targets: state that outlives the context window

The README opens with the failure mode it is built around: a general chat model forgets the protagonist's name by chapter five, you hunt through earlier text for a planted detail by chapter thirty, and after every chapter you have to remind the model to update character state and check arc progress. Goink's answer is to move that bookkeeping out of the prompt and into a structured store the agent reads and writes through tools.

The audience is narrow and specific: novelists writing at length with an LLM in the loop, who are willing to supply an API key and accept a desktop application rather than a web chat. The README positions the alternative as a chat window where every session starts by re-explaining the cast. Goink instead keeps character profiles, relationship edges, foreshadowing entries, arc nodes, location graphs and reader knowledge in SQLite, and exposes them to the model as callable tools. That is the whole thesis, and it is a data-modelling claim more than a text-generation one.

## How the agent loop, the 31 tools and the maintenance pass fit together

The engine is described as a self-built ReAct loop in Go, streaming over SSE, exposing 31 function-calling tools, with nested sub-agents. The README is explicit that this is not a pipeline passing a chapter from one stage to the next: the agent decides inside the current conversation which tool to call, with which arguments, and what to do next.

After a chapter is written, the system injects a maintenance reminder into the conversation listing what to check: whether characters changed, whether due foreshadowing was collected, whether arc nodes need advancing, whether reader knowledge needs refreshing. The README frames this as forcing self-inspection rather than trusting the model to remember. A separate review sub-agent can be started to read a chapter against system state and write discrepancies back into the conversation for the main agent to fix.

Three layers are claimed for this: the system prompt hardcodes the maintenance flow, dynamic injection adds the checklist after long output, and the review agent provides an independent pass. Whether the third layer is worth its token cost is a judgement the README does not make; it presents all three as safeguards.

## Installing Goink and getting a first chapter out of it

Goink ships as a desktop installer. The README points to the Releases page and gives one instruction per platform: run the installer on Windows, open the DMG and drag to Applications on macOS, run the AppImage on Linux. You need an LLM API key. Built-in templates exist for DeepSeek, GLM and MiMo, and the client is compatible with the OpenAI format, so a self-hosted or third-party endpoint that speaks that format is presumably usable as well.

The README states the installer is under 60MB and needs no Python, Node.js, database or GPU. On Windows, SmartScreen may warn because the build is unsigned; the README's instruction is to click More info, then Run anyway.

If you prefer to build from source, the README gives this sequence. Note that the GTK and WebKit packages are listed for the Linux build path:

```bash
sudo apt install libsqlite3-dev libgtk-3-dev libwebkit2gtk-4.1-dev gcc
git clone https://github.com/sigpanic/goink
cd goink
make deps
make build   # production build
make dev     # development mode with hot reload
```

The Makefile confirms these targets. make deps downloads the Git and ONNX Runtime bundles into build/runtime and skips them if they already exist; make build runs the frontend build first, then wails build with the webkit2_41 tag and a version ldflag. The README gives no first-run walkthrough beyond supplying an API key, so the first real use is: launch the app, enter your key, create a novel, and write a chapter, at which point the diff approval dialog is what you actually interact with.

## Local semantic search: BGE, sqlite-vec and MMR without a network call

Search is the feature that most cleanly separates Goink from a chat wrapper. The README's example is looking up which chapter the protagonist first saw a pendant. It states the search is semantic rather than keyword matching, so a query about pendant clues can surface passages that never use the word.

The stack is named in the README and confirmed by go.mod: an ONNX Runtime binding, sqlite-vec for the vector index, and the bge-small-zh-v1.5 model in int8 quantization for Chinese semantic embeddings. MMR reranking is applied to reduce redundancy in results. Indexing runs in the background after a chapter is written, incrementally. No network and no extra configuration are required.

Two consequences follow from those choices. The embedding model is Chinese-oriented, which is consistent with a Chinese-first README and UI, but it means retrieval quality for English manuscripts is not something the documentation addresses. And because the index is local and incremental, a large existing manuscript has to be indexed before search is useful; the README does not describe a bulk reindex command or what happens if the index and the text drift apart.

## Skills as markdown files, and the three-level override

A Skill is a single .md file with YAML frontmatter and markdown body. The README's example frontmatter uses name, description, category and mode keys, with mode set to auto. Skills resolve by name across three levels: novel over user over builtin. User skills live in ~/.goink/skills/, novel skills in {novel}/skills/, and builtin skills are packaged read-only. Editing is hot-reloaded, so no restart is needed.

Trigger modes are auto (the agent may call it, and it appears in the catalogue), manual (only via a slash command), and always (injected in full at the start of a session). The README counts this as a 3x3 matrix, nine combinations of level and mode. Builtin auto skills include scene beats, subtext in dialogue, pacing, suspense hooks, character design, revision, removing AI-sounding prose, and collaborative ideation; the builtin manual set is review, memory, collect and next.

Style distillation is the other half: paste a sample passage, and the model decomposes it along six axes (sentence structure, word choice, rhetorical devices, pacing, narrative distance, tone) into a generated imitation Skill, loadable with a slash command. The README is careful to call this pattern extraction rather than keyword substitution, which is the right distinction to make, though the quality of a generated Skill is not something the documentation can promise.

## Where Goink is the wrong tool, and how it differs from SillyTavern

The constraints are structural. Goink requires an LLM API key, so it is not an offline writing tool; the ONNX model is local, but the prose generation is not. The Windows build is unsigned, which is a real friction point in managed environments. The README does not document rollback for a failed upgrade, and it does not state whether novel data survives an uninstall or where the SQLite database lives. Anyone whose manuscript is the only copy should resolve that before trusting the app with it.

The clearest alternative in the same space is SillyTavern, which is also a local front end for LLM-driven writing and roleplay, with character cards and prompt management. The difference in approach is where the state lives. SillyTavern keeps character and world information in cards and prompt templates that you assemble and that the model reads as context; persistence is largely your responsibility, and long-range continuity depends on what fits in the prompt. Goink moves that state into a queryable store with tools, and adds a maintenance pass that runs after writing. If you want a lightweight chat front end with broad model support and no opinion about your story's structure, SillyTavern is the simpler choice. If you want the application to own foreshadowing and arc tracking, that is exactly what Goink was built for.

## Licence, maintenance and what an upgrade costs you

Goink is licensed under AGPL-3.0, and the README points to a NOTICE file for additional terms under AGPLv3 Section 7. That combination matters if you plan to distribute a modified build or run one as a network service; the Section 7 additional terms are the part to read rather than assume. Nothing here is legal advice, and the LICENSE and NOTICE files in the repository are the authoritative text.

The repository is not archived, and the last push was on 2026-09-06, the same day as the v1.4.3 release. Three releases landed in the three weeks before that: v1.4.1 on 2026-08-15, v1.4.2 on 2026-08-26 and v1.4.3 on 2026-09-06. That is a fast cadence, and it has a cost for anyone tracking it: you are upgrading a desktop app that bundles its own Git runtime and ONNX Runtime, downloads both via make deps, and stores your novel in SQLite. The README does not document a migration path between versions, so the practical check before upgrading is whether the release notes mention schema changes. If they do not, back up the novel directory first.

## Conclusion

Goink fits writers who already work with an LLM API key and want the model to maintain character, foreshadowing and arc state across hundreds of chapters, with diff approval before any prose is written. It does not fit anyone who wants a plain text editor, a browser-only tool, or a writing app that runs without a model provider. Before committing, verify the AGPL-3.0 and NOTICE terms against how you plan to distribute anything you build on it, and check that your platform's installer is present in the v1.4.3 release assets.

## FAQ

### What is Goink and who is it for?

Goink is a cross-platform desktop AI writing system for long-form novel writing, built in Go with Wails and React. It is aimed at writers who use an LLM to draft chapters and want character, foreshadowing, arc, location and reader-knowledge state tracked in a structured store rather than re-explained each session.

### Does Goink run offline?

The semantic search engine runs locally: the README states the BGE Chinese model runs through ONNX Runtime on the machine with a sqlite-vec index, no network needed. Prose generation still requires an LLM API key, and the README lists built-in templates for DeepSeek, GLM and MiMo with OpenAI-format compatibility.

### How do I install Goink?

Download the installer for your platform from the Releases page: run the installer on Windows, open the DMG and drag to Applications on macOS, or run the AppImage on Linux. The README states the package is under 60MB and needs no Python, Node.js, database or GPU, but you must supply an LLM API key.

### Does Goink change my manuscript without asking?

The README states that the AI does not edit prose directly: each edit first produces a diff that you approve, reject, or send back with feedback, and there is an automatic mode for continuous writing. All changes are kept in an internal Git history so you can revert to any earlier state.

## Sources

- [Issues](https://github.com/sigpanic/goink/issues)
- [License: AGPL-3.0](https://github.com/sigpanic/goink/blob/master/LICENSE)
- [README](https://github.com/sigpanic/goink/blob/master/README.md)
- [Releases](https://github.com/sigpanic/goink/releases)
- [sigpanic/goink on GitHub](https://github.com/sigpanic/goink)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/sigpanic-goink