goldfishh 0.11.0

Persistent memory for Claude Code — installs and wires GitNexus, OMEGA, and Semble

goldfishh

Persistent memory for Claude Code agents.
One command installs and wires together GitNexus, OMEGA, and Semble so your AI agent
never starts a session from scratch again.

---

Quick start

Prerequisites: Python 3.13 (pinned — see note below), Node.js 18+, uv (curl -LsSf https://astral.sh/uv/install.sh | sh)

uvx goldfishh init

Or install as a persistent tool:

uv tool install goldfishh
goldfishh init

Python 3.13 required. goldfishh pins to Python 3.13 because chonkie (a required dependency) is incompatible with Python 3.14. uvx and uv tool install both respect this constraint automatically.

The init wizard detects and installs all dependencies, indexes your codebase, scaffolds your memory vault, and registers Claude Code hooks. Re-running is safe — it reports health and skips what's already installed.

If you have prior Claude Code sessions in this project, seed OMEGA with their history:

goldfishh mine

---

The problem

Claude Code agents are stateless. Every session starts from zero. You spend 10–30 minutes re-explaining context that was established yesterday. The agent repeats mistakes it already made, asks questions already answered, and changes a function without knowing 47 others depend on it.

The tools to fix this exist. Nothing connects them. That's the gap goldfish fills.

Failure	Cause	Solution
Session amnesia	Agent starts blank every session	OMEGA episodic memory mines JSONL logs
Codebase blindness	Agent doesn't know the shape of the code	GitNexus code knowledge graph
Decision blindness	Agent doesn't know why things are built this way	Vault markdown notes + OMEGA
Impact blindness	Agent doesn't know what breaks when it changes something	GitNexus blast-radius analysis
Prompt deafness	Agent gets generic context, not prompt-specific context	Chonkie + Semble + OMEGA fan-out

---

How it works

goldfish installs four layers of intelligence into Claude Code — each maintained by a dedicated open-source tool or human maintainer.

Layer	Installed by	What it provides
Layer 0 — Memory	You	User preferences, behavioral feedback, reference pointers (plain markdown)
Layer 1 — Tool-native	GitNexus, OMEGA, Semble (via goldfishh init)	Each tool's own hooks, MCP server, and agent instructions
Layer 2 — Coordination	goldfish	Cross-tool orchestration — tells agents to query all three tools before acting
Layer 3 — Project-specific	You (or your agent)	Codebase-specific guardrails, architecture context, contributor workflow

goldfish itself is ~500 lines of Python — a thin orchestration layer with no search, embedding, or graph code. Every function is a subprocess call, a file write, or a config read.

How the tools connect

Claude Code JSONL logs         ← source of truth
       ↓ mined by OMEGA
SQLite episodic store          ← past decisions, lessons, errors
       ↓ written by goldfish
~/.goldfishh/vaults/{project}/  ← plain markdown vault (human-readable)
       ↑ indexed by GitNexus
Code knowledge graph           ← symbols, callers, execution flows
       ↑ searched by Semble
Prompt enrichment              ← context injected before every task
       ↑ decomposed by Chonkie

Hook lifecycle

Event	What happens
SessionStart	Drains queue, generates wake-up context from vault + OMEGA
UserPromptSubmit	Decomposes prompt → fans out to Semble (code + vault) + OMEGA → injects context
PreCompact	Drains queue, writes checkpoint note to vault
TaskCreated / TaskCompleted	Writes task notes to vault
Stop / SessionEnd	Advances JSONL offset in manifest

All async events write to ~/.goldfishh/queue.jsonl first and return in <10ms so Claude never blocks.

---

Vault

All knowledge is plain markdown — readable with cat, searchable with grep, versionable with git.

~/.goldfishh/vaults/{project}/
├── .manifest.toml           ← sync state (byte offset, timestamps)
├── Memory/
│   ├── Decisions/           ← architectural choices and rationale
│   ├── Lessons/             ← patterns learned across sessions
│   ├── Errors/              ← bugs and fixes
│   └── Checkpoints/        ← pre-compaction snapshots
├── Specs/                   ← feature specs referenced by tasks
├── Tasks/                   ← task notes (created/completed events)
└── _context/
    └── wake-up.md           ← refreshed every session

Each note uses temporal frontmatter so agents can tell what's current and what's superseded:

---
id: decision-jwt-auth-2026-05-24
type: decision
valid_from: 2026-05-24
superseded_by: null
confidence: 0.94
source_session: abc123
---

Want a visual graph of the knowledge store? See docs/obsidian.md.

---

CLI reference

goldfishh init              Run the setup wizard
goldfishh mine              Seed OMEGA from historical JSONL session logs (run once on onboarding)
goldfishh status            Show queue depth, manifest state, and sync timestamps
goldfishh doctor            Check all dependencies and report with fix instructions
goldfishh register-hooks    Re-register hooks with the correct binary path
goldfishh replay            Rebuild vault from JSONL transcripts (resumable)
goldfishh hook              Handle a hook event from stdin (called by Claude Code)
goldfishh drain             Process queued events from ~/.goldfish/queue.jsonl

---

Platform support

Linux + macOS (primary): tested on Ubuntu 26.04 LTS; macOS expected to work.
Windows (beta): CI passes on Windows; clean-install verification pending.

---

Development

git clone https://github.com/miztertea/goldfish
cd goldfish
uv sync
uv run pytest

Tests stub all subprocess calls and run without live tool installations. ~100 tests, ~0.3s.

uv run pytest -v          # verbose test output
uv run goldfishh --help   # run CLI from source

---

Contributing

Human contributors: CONTRIBUTING.md
AI agent contributors: AGENTS.md

---

License

MIT — see LICENSE.