LoveSpark

Sparky & SparkyBrain

Two separate pieces with two different jobs. Sparky is a Mac app for one person. SparkyBrain is the plain-text memory that my AI agents share across machines. They are kept apart on purpose, and they are not wired together yet.

Sparky ✨: the app
macOS · SwiftUI · in development

Storage

One SQLite database (GRDB, WAL mode) in the app's Application Support folder. Nothing is synced to a server, and there are no accounts.

Knowledge graph

  • 12 object types: conversation, memory, note, decision, commitment, person, topic, project, source, digest, goal, plan.
  • Typed edges between objects, an immutable revision history, and an evidence trail that records where each fact came from.

Retrieval

Hybrid search: SQLite FTS5 (BM25) for words, plus vector embeddings computed on the Mac with Apple's NaturalLanguage framework. The two rankings are merged into one list.

Agents

sparky-mcp serve is an MCP server over stdio that opens the same database as the app (WAL makes that safe across processes). It makes no model calls of its own: the agent brings its own model. Anything an agent captures is marked local_only by default.

Chat and the rest

Chat runs through the Claude Code CLI by default; opencode is an opt-in backend. The app also has a focus timer, habits, study, notes and a medication logger.

SparkyBrain 🜁: shared agent memory
Markdown + git · Python · Mac mini

Storage

A folder of markdown files with front matter, tracked in git, on a Mac mini that is always on. Any editor or Obsidian can open it.

  • profile.md: who I am; agents read this first.
  • notes/, knowledge/<type>/, projects/ (one note per code repository), inbox/ (dated facts agents save), chats/ (private).
  • ledgers/: four append-only JSONL files (see below).

Server

One Python file, brain.py, with no dependencies beyond Python itself. It builds a SQLite FTS5 index from the files; the index can be deleted and rebuilt at any time, because the markdown is the source of truth. It answers over:

  • MCP over stdio, for agents on the Mac mini;
  • MCP and plain HTTP on the home network, behind a bearer token, for the other machines;
  • a command line for me.

Claude Code, Codex and Hermes (running a local Qwen model) are registered as clients.

Writes are commits

Every agent write is a git commit named after the client that made it, for example claude-code: write projects/tongue-mac.md. git log shows which agent changed what, and git revert undoes it. A scheduled job pushes a snapshot to a private repository every night.

Privacy

A note with private: true in its front matter never appears in MCP or HTTP results; only the owner's command line sees it. Chat transcripts are private.

Project notes from coding sessions

  1. When a Claude Code session starts in a repository, a hook loads that project's note into the session.
  2. When the session ends, a background job reads the transcript and folds it into the note under What it is, Current state, Decisions, Open threads and Log. It uses claude -p, or a local Qwen model through Ollama if the CLI isn't signed in.
  3. The result is committed as claude-code.

Ledgers

Four append-only files, written through ledger.py, which rejects an entry with a missing field:

  • failures: each bug or false "done", with root cause, why it was missed, the prevention, and whether that prevention is enforced in code or only written down;
  • jobs: long-running work and its state;
  • decisions: my calls, in my words;
  • deliveries: what shipped and how it was checked.

Before an agent starts work it reads the failures that are still open; afterwards it checks its work against them and logs what it delivered.

Why they're separate

The heavy version didn't hold up

SparkyBrain was rebuilt on 6 October 2026. Before that, agent memory went through a Swift brain service with its own database schema and migrations, and an earlier design on Temporal and PostgreSQL. Both took more running and upkeep than one person's memory needs. They were replaced with a markdown folder, git and one Python file.

Different jobs, different machines

Sparky is an app I use on my MacBook, with a typed schema and a UI. SparkyBrain is read and written by agents on several machines, so it has to stay on, be reachable over the network, and be readable by anything that can open a text file, including small local models.

Code and notes apart

The SparkyBrain code and the notes live in separate repositories, so the code can be shared without exposing personal notes.

The trade-off

SparkyBrain only has keyword search: no typed graph and no vectors. Sparky has both, but it lives on one Mac.

Not built yet

The Sparky app does not read SparkyBrain today. A shared contract between Sparky and the other LoveSpark apps (SparkyBridge) is planned, but it has no code yet.