Thoughtline
A local-first memory MCP server for game developers — with the memory types and tags that generic memory tools don't ship.
Save your project's lore. Recall it from any session. Forever.
What this is
A memory server, and the vocabulary that makes it worth searching.
This repository ships its own MCP memory server. It keeps memories in a local SQLite file, searches them with FTS5, and exposes the tl_* tool surface over MCP: save a memory, search for one, read one in full, link related ones, judge a pending capture, and open or close a session. A Bubbletea dashboard ships with it. It is a single Go build — go build -o thoughtline ./cmd/thoughtline.
On top of that sits the part generic memory tools do not have. Their vocabulary is the language of backend engineers: bugfix, decision, architecture, pattern. Useful — and nowhere near the texture of building games. This repository is the missing opinion: the memory types and tags shaped for how a game studio actually works, plus the guidance to start using them in five minutes.
That vocabulary is not welded to this server. It runs unchanged on Engram too, which stores a memory's type as a free-form string; this server is the one that validates it against the closed set — see the section on Engram below.
What it actually saves you
You stop re-explaining things like:
- Why the inn entity is split into
world/staticandworld/interactive - The lantern texture import settings that don't blow out the bloom
- Which script handles the camera nudge when the player enters the cellar
- That Android batching gotcha on the chairs — the draw-call count you couldn't cross
- The animation curve numbers your animator finally locked in
Memories are typed (discovery, bugfix, decision, config, pattern) and tagged (engine:unity, platform:switch, pipeline:fbx-to-godot) so you can search them later.
Any engine — Unity, Unreal, Godot, PlayCanvas, Bevy, your own. Any AI tool that speaks MCP — Claude Code, Cursor, Zed, Rider, Visual Studio, JetBrains.
Why a vocabulary has to be an opinion
This is the part worth understanding before adopting anything, because it explains why the vocabulary lives in documents while the storage lives in code.
Engram stores an observation's type as a free-form string. It accepts perf_bugfix_thing exactly as happily as bugfix — verified end to end: save under an invented type, read it back, and it returns byte-for-byte unchanged. That is a deliberate and correct choice for a general-purpose tool.
But a field that accepts anything gives you no shared language — and a memory you cannot search by category is a memory you will not find again. Left to its own devices, every session invents its own words and the store slowly fills with mush.
So the division of labour is:
The storage and the words ship together here, and the words alone still work on Engram. That is why the vocabulary is both enforced and written down: the code is the single source for the closed set, and the documents are what carry it to an engine that has no opinion of its own.
The taxonomy
Seven core types, each with a reason to exist, ordered by measured use across 2,336 real memories in 13 projects, read on 2026-09-29. The full catalogue — the required sections per type, the tag vocabulary (engine:, platform:, pipeline:) and worked examples per engine — lives in docs/design/memory-domain.md and docs/design/tag-conventions.md. That file is the only place the complete catalogue lives; the table below is the short version.
These seven are the ones every agent session on this stack is already told to choose from — type: bugfix | decision | architecture | discovery | pattern | config | preference. A catalogue that disagrees with that instruction gets contradicted back, which is how the previous revision of this table ended up with 24.8% of a real store typed in words it declared invalid.
Game projects can also reach for seven optional extensions — game-design-decision, scene-pattern, asset-reference, perf-gotcha, pipeline-step, script-pattern, convention — documented in the same file. Together they account for 4 of those 2,336 memories, so they are available rather than recommended.
Each memory carries the same envelope: title, type, topic_key, scope, project, tags, created_at, revision_count, free-form content.
How to adopt it in five minutes
There are two engines this vocabulary can run on. Pick one — not both, or you end up with two separate memory stores.
With this repository's server
- Build it.
go build -o thoughtline ./cmd/thoughtline, and put the binary on yourPATH. - Wire it into your editor. The Claude Code plugin under
plugin/claude-code/registers it for you, and any other MCP client takes a standard stdio server entry. Platform notes live in Installation. - Teach your agent the words. This is the step that makes the vocabulary real — and the one most people skip. Copy
presets/AGENTS.mdinto your project — asAGENTS.md, or pasted intoCLAUDE.md, a rules file or a skill — and your agent will type memories correctly from the first session. There is nothing to install; the file is the artefact.
With Engram as the engine
- Install Engram. Prefer the latest stable release from Engram's releases. Homebrew works too —
brew install gentleman-programming/tap/engram— though the tap lags the release line. Windows, Linux and source builds: Engram's installation guide. - Wire it into your editor. Engram documents its own MCP setup for Claude Code, Cursor, Zed, Copilot, Windsurf and others. For Claude Code specifically:
claude plugin marketplace add Gentleman-Programming/engram && claude plugin install engram. - Teach your agent the words. Same file and same step as above. A memory's type is a free-form string with no validator on either side, so the model falls back to its own defaults unless you tell it otherwise.
Either way, read the tag conventions for the longer form: docs/design/tag-conventions.md.
How this relates to Engram
Engram is the general-purpose engine, and it is excellent: 6,931 stars and 30 releases, measured on 2026-09-29, with SQLite + FTS5, an MCP server, an HTTP API, a CLI and its own TUI. Its vocabulary is deliberately unspecified — it accepts any type string.
Thoughtline is the opinionated one: the same kind of machinery, carrying the types and tags that game work needs. Both are local-first memory servers for AI coding assistants, and the vocabulary documented here runs on either of them.
They are separate tools with separate stores, so installing both gives you two places to look — which is the fastest way to lose a memory you saved. Pick one. If you are not building games, use Engram on its own; you will be well served.
Where the engine stands
The server is in the tree, it builds, and its own test suite passes. Two facts about its state matter before you rely on it:
- The newest published tag is not the current source.
v0.1.0was cut on 2026-05-07 and the source has moved on since — the published binary exposes fewer tools thanmaindoes, and it rejectsdiscovery,configandpattern, three of the core types above. Build from the repository to get current behaviour. mainsits mid-feature. Thestorage-capswork landed its first three phases on 2026-05-15 and its fourth phase never landed; the second change in that goal,slim-inject, was never started. Nothing in the tool surface described above depends on the unfinished phase, and the resume checkpoint is recorded assdd/storage-caps/state.
There is no release cadence here: CHANGELOG.md is the record of what changed and why, and it is a live document.
Where the decisions live
The corpus is the part that carried the judgement, and it is all still here: docs/decisions/ holds the architectural decisions, docs/research/ the investigations, and docs/design/ the domain and tag catalogues. These pages describe behaviour; docs/TOOLS.md is the tool reference.
Attribution
This project is heavily inspired by Engram (https://github.com/Gentleman-Programming/engram) by Alan Buscaglia, also released under the MIT License. Architectural patterns, tool naming conventions, and storage layout decisions are deliberately kept close to Engram's to ease cross-pollination of improvements.
This paragraph lives here rather than in LICENSE on purpose: GitHub's licence detector matches the licence text itself, and extra prose appended after it drops the match — the repository would report no licence while the README claimed MIT. Keeping the licence file canonical is what makes the MIT claim visible to tooling. Attribution belongs in the README, and this is the README.
Appendix — the v0.1.0 documentation set
Everything below documents the server as it stood at v0.1.0, kept as the record of that point. Parts of it are superseded by the sections above — in particular the comparison table's claim that gamedev types exist "at the schema level", which is misleading: a memory's type is stored as a free-form string, and that is exactly why the vocabulary is worth having.
Quick start
Windows — one command (auto-installer)
From PowerShell (recommended):
irm https://raw.githubusercontent.com/AgusLoza2021/Thoughtline/main/scripts/install.ps1 | iex
From classic cmd.exe:
powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/AgusLoza2021/Thoughtline/main/scripts/install.ps1 | iex"
The installer is idempotent and does not need admin/UAC. It will:
- Install Go via
wingetif missing - Run
go installfor thethoughtlinebinary - Add
%USERPROFILE%\go\binto your user PATH - Register
thoughtlineas an MCP server in%USERPROFILE%\.claude.json(Claude Code CLI and the VS Code extension share this config — one entry covers both) - Verify with
thoughtline version
After it finishes, restart Claude Code (or VS Code with the Claude Code extension) and the tl_* tools are live.
Already cloned the repo? You can run the script locally:
.\scripts\install.ps1 # default
.\scripts\install.ps1 -Version v0.0.1 # pin a version
.\scripts\install.ps1 -Force # overwrite an existing MCP entry
Flags: -Version <ref>, -SkipPathSetup, -SkipMcp, -Force. See scripts/install.ps1.
Manual install (macOS / Linux / Windows)
Install (Go 1.25+):
go install github.com/AgusLoza2021/Thoughtline/cmd/thoughtline@latest
Or grab a prebuilt binary from the latest release.
Add to Claude Code — drop this into ~/.claude.json (or claude_desktop_config.json):
{
"mcpServers": {
"thoughtline": {
"command": "thoughtline",
"args": ["serve"]
}
}
}
Open the dashboard:
thoughtline ui
That's it. Restart your AI client and the tl_save, tl_search, tl_context, … tools are available.
Or install the Claude Code plugin
If you use Claude Code, the official plugin wires everything up — MCP server registration, SessionStart/post-compaction hooks that inject the active-protocol markdown, slash commands (/tl-recent, /tl-search, /tl-stats, /tl-ui, /tl-export), a tl-archivist subagent for memory hygiene, and the thoughtline-memory skill that tells Claude when to save and recall.
claude plugin install github:AgusLoza2021/Thoughtline/plugin/claude-code
The plugin is cross-platform — it shells out to the thoughtline protocol subcommand instead of bash scripts, so Windows users do not need WSL or Git Bash.
See plugin/claude-code/README.md for the full plugin reference.
What is Thoughtline?
Thoughtline is an MCP (Model Context Protocol) server that gives AI assistants like Claude Code, Cursor, or Zed a long-term memory shaped for how a game studio actually works: design decisions, asset references, performance gotchas, scene patterns, pipeline steps. It runs locally, per developer, in a single Go binary backed by a SQLite database you own.
Thoughtline stands on the shoulders of Engram by Alan Buscaglia — we deliberately reuse Engram's MCP shape, storage layout, and the clever bits like FTS5 full-text search and topic_key upserts. What we add is a gamedev-first memory taxonomy and a vocabulary tuned for engines like PlayCanvas, Unity, Unreal, and Godot.
Curious how Thoughtline lines up against Engram and claude-mem? See docs/COMPARISON.md for an honest side-by-side.
Status: M5 done + passive capture. Twelve tools live:
tl_save,tl_search,tl_get_observation,tl_context,tl_update,tl_delete,tl_session_start,tl_session_summary,tl_stats, plustl_pending_list,tl_pending_get,tl_promotefor opt-in passive capture of Claude Code hook events. See docs/integrations/claude-code-passive-capture.md for the setup guide. M6 (semantic embeddings) remains deferred per ADR 0002. Seedocs/PROGRESS.md.
Why this exists
Generic AI memory tools speak the language of backend engineers: bugfix, decision, architecture, pattern. Useful — but nowhere near the texture of building games.
When a gamedev team works on a real title, they routinely need to remember things like:
- "Why is the inn entity hierarchy split into
world/staticandworld/interactive?" - "What were the import settings we landed on for the lantern texture so it didn't blow out the bloom?"
- "Which script handles the camera nudge when the player enters the cellar?"
- "That batching gotcha on Android with the chairs — what was the exact draw-call count we couldn't cross?"
None of these fit cleanly into a generic memory schema. Thoughtline captures them as first-class memory types so search, recall, and cross-session context all stay sharp instead of being squeezed into a pattern bucket.
How it compares
There are several memory tools out there. Here's where Thoughtline sits:
TL;DR: if you ship games and your team uses MCP-capable tools, Thoughtline is the one shaped for you. If you don't ship games, Engram is the better generic choice — Thoughtline literally builds on it.
What it is — and isn't
If you are not a gamedev and want a generic memory MCP, use Engram directly — it is excellent. Thoughtline only exists because we wanted gamedev concepts at the schema level.
Architecture at a glance
graph LR
Client["AI client<br/>(Claude Code, Cursor, ...)"] -- "MCP / stdio JSON-RPC" --> Server["thoughtline<br/>MCP server"]
Server --> Tools["Tool layer<br/>tl_save · tl_search · tl_context · ..."]
Tools --> Domain["Memory domain<br/>(types, topic keys, scopes)"]
Domain --> Storage["Storage<br/>(SQLite + FTS5 / BM25)"]
Storage --> DB[("thoughtline.db<br/>local file")]
classDef ext fill:#1e1e2e,stroke:#7C3AED,color:#fff
classDef core fill:#181825,stroke:#00ADD8,color:#fff
classDef store fill:#11111b,stroke:#a6e3a1,color:#fff
class Client ext
class Server,Tools,Domain core
class Storage,DB store
Full breakdown in docs/ARCHITECTURE.md. The decisions behind it (and why we picked FTS5 over embeddings for v1) live in docs/decisions/.
The Thoughtline memory taxonomy (preview)
The full taxonomy lives in docs/design/memory-domain.md. Headline types:
Each memory carries the same envelope: topic_key, scope, project, created_at, revision_count, free-form content.
Roadmap
The work is sliced into milestones. Each one has a definition of done, so progress is unambiguous.
See docs/PROGRESS.md for the live milestone status and pre-publish TODOs.
Install
✅ As of M5, nine MCP tools + an interactive dashboard ship:
tl_save,tl_search,tl_get_observation,tl_context,tl_update,tl_delete,tl_session_start,tl_session_summary,tl_stats, plusthoughtline ui.
From source
git clone https://github.com/AgusLoza2021/Thoughtline.git
cd Thoughtline
go build ./cmd/thoughtline
This produces a thoughtline binary in the project root. Move it onto your PATH or reference it by absolute path in your MCP client config.
Once a release is tagged
go install github.com/AgusLoza2021/Thoughtline/cmd/thoughtline@latest
Wire it into your MCP client
Per-tool guides:
- Claude Code — see
docs/integrations/claude-code-protocol.md, or use the bundled plugin for one-line install - Cursor —
docs/integrations/cursor.md - Zed —
docs/integrations/zed.md - JetBrains Rider (Unity) —
docs/integrations/rider-unity.md - Visual Studio (Unreal) — see Cursor or Rider guides; same MCP shape
Generic MCP config (any client):
{
"mcpServers": {
"thoughtline": {
"command": "thoughtline",
"args": []
}
}
}
A complete example lives at examples/mcp-config.example.json.
Configuration (env vars)
Tool catalogue
All MCP tools share the tl_ prefix. The full reference — every parameter, every response shape, every edge case — lives in docs/TOOLS.md. Skim the table below; jump there when you need the details.
One concrete example — save & search
// tl_save — capture an inn-cellar scene pattern
{
"title": "Inn cellar entity hierarchy",
"type": "scene-pattern",
"topic_key": "scene/playcanvas/inn-cellar",
"tags": ["engine:playcanvas", "platform:android"],
"content": "**What**: cellar split into world/static and world/interactive. **Why**: keeps batching tight on Android. **Learned**: chairs in interactive caused +38 draw calls."
}
// Later — recall it
{ "query": "scene/playcanvas/*" } // topic-key GLOB, O(1)
{ "query": "lantern bloom android" } // FTS5 + BM25 keyword search
For ten more end-to-end examples — sessions, soft-delete, cross-project queries, sticky session_id — see docs/TOOLS.md.
Full architecture in docs/ARCHITECTURE.md. Memory taxonomy in docs/design/memory-domain.md. Tag conventions in docs/design/tag-conventions.md.
(Full parameter reference for every tool moved to docs/TOOLS.md.)
Interactive dashboard (thoughtline ui)
When you want a visual at-a-glance view of what's stored — without firing up the AI — Thoughtline ships an interactive terminal memory workspace (Bubbletea TUI). It is organised as six tabs reachable via the digit keys 1–6 or tab / shift+tab to cycle:
thoughtline ui # launch the workspace
📸 TODO: replace these placeholders with real PNGs/GIFs before launch.
Layout snapshots for every tab live under
internal/dashboard/testdata/*.golden(rendered at 100×30) and are the source of truth for visual contracts.
Global hotkeys (active when no input is focused): [S] save (CLI/MCP for now), [/] jump to Search, [M] jump to Memories, [I] jump to Inbox.
Navigation: 1-6 jump to tab · tab / shift+tab cycle · esc pop overlay · q / ctrl+c quit.
Memory Detail: ↑↓ scroll, [C] copy to OS clipboard (Windows clip.exe, macOS pbcopy, Linux wl-copy → xclip).
The Memories tab and the Detail view are read-only by design — no edit/delete from the TUI to prevent accidental data loss. The Inbox is the only mutation path, and it always promotes to a memory via the same save pipeline that CLI/MCP use.
For programmatic access from the AI, use the equivalent tl_stats MCP tool:
// Default: scoped to current project
{}
// Cross-project: see counts across the whole DB
{ "project": "*" }
// Specific project
{ "project": "sort-factory-v4" }
The text output mirrors the dashboard's stats panel so the AI can describe the state of memory back to you.
Repo layout
thoughtline/
├── cmd/thoughtline/ # binary entry point
├── internal/
│ ├── server/ # MCP server wiring (mark3labs/mcp-go)
│ ├── storage/ # SQLite persistence (modernc.org/sqlite)
│ └── memory/ # domain types: Memory, Type, Scope, TopicKey
├── docs/
│ ├── ARCHITECTURE.md # how the system fits together
│ ├── PROGRESS.md # live milestone status + pre-publish TODOs
│ ├── research/ # deep-dives into Engram (the reference architecture)
│ ├── design/ # taxonomies, schemas, vocabulary
│ └── decisions/ # ADRs — every load-bearing decision lives here
├── examples/ # MCP client config examples
├── .github/workflows/ # CI: build + vet on every push
├── go.mod
├── LICENSE # MIT (canonical — attribution is credited in the README)
├── CHANGELOG.md
├── CONTRIBUTING.md
└── README.md # you are here
Documentation index
Credits and lineage
Thoughtline would not exist without Engram by Alan Buscaglia and the Gentleman-Programming community. We read its source carefully (see docs/research/), credit the design choices we keep, and stay MIT-compatible so improvements can flow back upstream.
Thoughtline now ships a first-class migration path for users coming from Engram: the cmd/migrate binary reads your Engram database, maps types and columns to Thoughtline's format, and writes through the same storage.Save() path the MCP server uses — FTS5 indexing, sync_id preservation, and all validation included. See cmd/migrate/README.md.
If you are evaluating memory tools for a non-gamedev team, use Engram directly — it is more general and more battle-tested. Thoughtline is a gamedev-flavored sibling, not a competitor.
License
MIT — see LICENSE.
Contributing
PRs, issues, and design feedback welcome. See CONTRIBUTING.md. Be kind, be precise, cite source lines.