gingugu/gingugu

**Your AI forgets everything between sessions. Gingugu fixes that.**
Gingugu is a local MCP server that gives AI coding assistants a real long-term
brain — persistent, structured, searchable memory that survives across
sessions, repos, and projects. No cloud, no API keys, no telemetry. One SQLite
file on your machine.
---
📋 Table of Contents
- Why Gingugu
- FAQ
- Features
- Architecture
- Setup
- Configure Your MCP Client
- Configure Your AI Agent
- Memory Explorer UI
- Configuration
- Usage
- Development
- Troubleshooting
---
Why Gingugu
Every session with an AI assistant starts from zero. The decisions you made
yesterday, the bug you fixed last week, the architecture you settled on a
month ago — gone. Existing memory tools dump observations into a flat pile
with no structure, no staleness tracking, no relationships, and no sense of
what's relevant *right now*.
Gingugu is designed to be a **structured long-term brain** — not a junk drawer:
- **Remembers** across sessions, repos, and projects
- **Organizes** knowledge by namespace, type, and relationships
- **Ranks** memories by relevance, freshness, and confidence
- **Auto-surfaces** relevant context when you start working
- **Consolidates** duplicate and related knowledge on demand
The protocol ships with it
Storage is the easy half. A memory server that an agent never writes to is an
empty database, and an agent left to its own judgement will save almost
nothing worth keeping — the failure mode isn't retrieval, it's discipline.
So Gingugu ships the discipline too. gingugu init wires a repo in one
command and installs a **SessionStart hook** that injects the memory protocol
at the top of every session: load these namespaces, check memory before asking
a question already answered, save at the moment of observation rather than
batching to the end, build a relation only when it records something search
cannot infer. There is no rules file to paste and nothing to remember to do —
the harness runs it whether or not the agent feels like it. A **stop hook**
then checks that a session with real work in it actually wrote something down.
Three more hooks bring memory to you: **involuntary recall** surfaces what your
prompt woke, **tripwires** stop a tool call that a memory says must not be
missed, before it runs, and **warm minions** hand a subagent a fenced,
pre-loaded brain of its own.
That is the part that makes the memory worth having, and it is in the box.
Retrieval quality
Hybrid retrieval (BM25 over FTS5 + local embeddings, fused with Reciprocal
Rank Fusion) measured with the in-repo bench/
toolset — **MRR 0.828, recall@1 0.611, recall@5 0.983**.
Measured over 30 labeled questions against a real working brain (~1,100
memories), not a public benchmark suite, so read it as a regression baseline
for this workload rather than a cross-product comparison. The runner is
deterministic and committed, so you can point it at your own store and get
your own numbers: python -m bench --help.
The benchmark can also **build its own labeled question set** from your store
(python -m bench --db --generate-probes ), by picking questions
whose answer is provable rather than hand-judged: a phrase that occurs in
exactly one memory has exactly one correct answer. That gives you a golden set
sized to your own brain without labeling anything by hand, and it stays local.
Where this goes long-term — federated, org-wide agent memory — lives in
docs/enterprise-vision.md.
---
FAQ
Why not just use Claude Projects / Cursor @memories / Windsurf Memories?
Those are great if you live in one tool. The moment you switch between
Claude Code in the morning and Cursor in the afternoon, the memory is gone.
Gingugu's memory follows you across every MCP client, lives on your machine,
and is programmable (21 tools, structured types, relationships, confidence
levels). The built-ins are convenience features. Gingugu is infrastructure.
Why SQLite + FTS5 instead of a vector database?
Both, actually. **We do hybrid retrieval out of the box:** BM25 over FTS5 +
local semantic embeddings, fused with Reciprocal Rank Fusion. No vector DB
server required.
Why this stack:
1. **No deployment.** One SQLite file holds memories, FTS5 index, *and*
embeddings. No Postgres, no Pinecone, no Chroma server.
2. **Two embedding backends — pick one:**
- **fastembed** (default) — ONNX-based, no PyTorch, ~80MB model download
to ~/.cache/fastembed. Works fully offline after first use.
- **Ollama** — delegates to your already-running Ollama process via its
HTTP API. Zero extra memory footprint. Set