https://github.com/thedeutschmark/forgetmenot

AI personality with persistent memory for Twitch streams. Remembers your chatters, stream lore, & inside jokes - from stream to stream.
https://github.com/thedeutschmark/forgetmenot

Last synced: 2 months ago
JSON representation

AI personality with persistent memory for Twitch streams. Remembers your chatters, stream lore, & inside jokes - from stream to stream.

Host: GitHub
URL: https://github.com/thedeutschmark/forgetmenot
Owner: thedeutschmark
License: mit
Created: 2026-02-17T23:33:35.000Z (5 months ago)
Default Branch: main
Last Pushed: 2026-04-14T05:11:53.000Z (3 months ago)
Last Synced: 2026-04-14T05:31:11.688Z (3 months ago)
Language: TypeScript
Homepage:
Size: 544 KB
Stars: 2
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

ForgetMeNot

A Twitch chat bot that actually remembers your regulars — names, inside jokes, the callback from three weeks ago. Runs locally on your machine with your own AI key.

---

## What it does

- **Remembers chatters across streams** — names, running jokes, callbacks, channel lore. Context lives in a local SQLite database on your machine, not on anyone else's server.
- **Configurable persona** — bot name, tone, and reply policy set from the toolset dashboard. Safe mode enforces stricter filters; shows terminal or runs silently in the background.
- **Reply modes** — mentions-only (default), shadow (generates replies without posting, for review), or live (replies to the chat stream directly). Switchable without a restart.
- **Moderation actions** — timeout proposals with configurable allow-lists and a shadow mode so no action fires without explicit policy opt-in.
- **Eval suite** — fixture-based regression runner catches behavior drift before each release.

## How it works

1. The engine connects to Twitch chat via [tmi.js](https://github.com/tmijs/tmi.js).
2. Incoming messages are evaluated against reply policy and cooldown rules.
3. Relevant context (chatter notes, episode recaps, channel lore) is read from a local SQLite database.
4. A reply is generated by calling Gemini or OpenAI directly from your machine using your own API key.
5. Post-generation filters apply (safe mode, budget, tone) before anything is posted.
6. Memory is compacted periodically — the current session is summarised on shutdown so recall survives across streams.

Nothing passes through a shared backend. LLM calls travel from your machine directly to the AI provider you chose.

## Getting started

The full distributable (Windows executable + system tray app) ships from [Releases](https://github.com/thedeutschmark/forgetmenot/releases). Configuration, personality templates, and the review dashboard live at [toolkit.deutschmark.online](https://toolkit.deutschmark.online/tools/chat-bot) — the toolset drives the initial pairing and wizard flow.

**To run from source** (Node.js 22+ required):

```bash
npm install
npm run dev # tsx watch — live reload
```

```bash
npm run build:exe # packages the engine into a standalone executable
```

The runtime expects credentials supplied by the toolset pairing flow (stored locally). An LLM API key (Gemini or OpenAI) must be set — either through the toolset wizard or via the `BOT_LLM_API_KEY` environment variable. Without an API key the reply engine starts in disabled mode.

**Eval suite** (regression checks before release):

```bash
npm run eval # run fixtures against current engine
npm run eval:gate # pass/fail against baseline scores
npm run eval:baseline # write a new baseline from current results
```

## Project structure

| Path | What it is |
| --- | --- |
| `src/` | Engine source — Twitch chat ingest, SQLite memory, LLM calls, action evaluation, post-gen filters |
| `src/gateway/` | Twitch connection (tmi.js wrapper) |
| `src/memory/` | SQLite read/write, session compaction, chatter notes, episode recaps |
| `src/reply/` | LLM provider adapter, reply engine, budget, post-processing |
| `src/actions/` | Moderation action proposals and executor |
| `src/runtime/` | Config loading, credential management, config refresh loop |
| `src/api/` | Local health API, pairing endpoints, setup wizard endpoints |
| `eval/` | Fixtures and rubric runner used to catch behaviour regressions before release |
| `scripts/` | Build helpers — packages the engine into a single-file executable |

## Privacy

Local-first: all chat memory lives in a SQLite file on the broadcaster's machine. LLM calls go from your machine directly to Gemini or OpenAI — no shared server ever holds your chat data. Credentials are not stored in plaintext on disk.

---

## License

[MIT](LICENSE)

---

## deutschmark's other apps

Alert! Alert!
Stream-alert clips from any video source.
Clipline
Livestream VODs → shortform clips with auto-captions.
The Stream Toolset
OBS overlays + companion apps. One login, no subscriptions.
Collab Planner
Finds collab windows from streamers' broadcast history.
P.A.T.H.O.S.
AI career platform — resume tailoring + ATS scoring.