🧠 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

• How It Compares

• FAQ

• Features

• Architecture

• Setup

  • Configure Your MCP Client

  • Configure Your AI Agent

• Memory Explorer UI

• Configuration

• Usage

• Development

• Troubleshooting

Related MCP server: mnemos

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 the actual 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

Where this goes long-term — federated, org-wide agent memory — lives in docs/enterprise-vision.md.

How It Compares

The honest take: Zep has the most sophisticated knowledge graph — they auto-extract entities and relations using LLMs. We don't (yet). But theirs costs LLM calls per memory, needs Postgres, and lives in the cloud. Ours is one SQLite file, free forever, and offline-capable.

Where Gingugu wins outright: the trifecta of local-first, cross-tool, and zero-cost forever. Nobody else hits all three.

FAQ

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 (16 tools, structured types, relationships, confidence levels). The built-ins are convenience features. Gingugu is infrastructure.

Both, actually. We do hybrid retrieval out of the box: BM25 over FTS5 + local semantic embeddings (via fastembed, no PyTorch dependency), 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. ONNX over PyTorch. fastembed ships the embedding model as a ~50MB ONNX runtime instead of 2GB of PyTorch — the install footprint stays honest to the "one SQLite file" promise.

3. It composes. Hybrid relevance feeds the composite (relevance × freshness × access × confidence) — every signal in one engine.

You can disable semantic search via MEMORY_EMBEDDINGS_ENABLED=false and fall back to BM25-only. Swap the model via MEMORY_EMBEDDINGS_MODEL (any fastembed-supported model — defaults to BAAI/bge-small-en-v1.5).

Yes. 138 tests passing. Self-hosted in this repo (the memories you see referenced in commits are Gingugu memories). WAL mode for concurrency. Hardened against adversarial input and write contention. CI matrix across Python 3.11–3.13 on Linux/macOS/Windows.

SQLite FTS5 comfortably handles millions of rows. Gingugu adds composite re-ranking on top, but only over a small candidate pool (4× limit). For personal/team use you'll never hit a wall. Use memory_consolidate to merge duplicates or summarize clusters when things sprawl.

It's a local CLI/server tool. Python's SQLite + keyring + asyncio story is mature, the install footprint via uv is small, and there's no JS bundling or Rust toolchain required to use it. The MCP SDK is first-class in Python.

Features

Architecture

graph TD
    A[AI Assistant<br/>any MCP client] -->|MCP Protocol| B[Gingugu Server]
    B --> C[Search Engine<br/>FTS5 + BM25]
    B --> D[Storage Layer<br/>SQLite + WAL]
    B --> E[Decay Engine<br/>Scoring + Pruning]
    B --> F[Context Engine<br/>Auto-Retrieval]
    B --> H[Consolidation Engine<br/>Merge + Dedupe]
    B --> K[Credential Vault]
    C --> D
    E --> D
    F --> D
    H --> D
    K --> D
    K --> J[OS Keychain<br/>via keyring]
    D --> G[(~/.local/share/gingugu/memories.db)]

See docs/architecture.md for full technical details.

Setup

Prerequisites

• Python 3.11+

• uv (recommended) or pip

• macOS, Linux, or Windows — the credential vault uses your OS-native secret store via keyring (macOS Keychain, Windows Credential Locker, Linux Secret Service/KWallet). On headless Linux without a Secret Service backend, everything works except storing secrets.

Install

# Recommended: uv (fast, manages Python for you)
uv tool install gingugu

# Or with pip
pip install gingugu

That's it. The gingugu command is now on your PATH.

git clone https://github.com/gingugu/gingugu.git && cd gingugu
uv sync
uv run gingugu  # or pip install -e .

Production-ready. 16 MCP tools live. 138 tests passing. Dogfooded daily in Windsurf — this repo's own memories live in a Gingugu database.

Configure Your MCP Client

Gingugu speaks standard MCP over stdio — it works with any MCP client. Claude Code, Claude Desktop, Cursor, Cline, and Windsurf are all first-class.

Add to ~/.codeium/windsurf/mcp_config.json — a ready-to-edit template lives at examples/mcp_config.json:

{
  "mcpServers": {
    "gingugu": {
      "command": "uv",
      "args": ["--directory", "/ABSOLUTE/PATH/TO/gingugu", "run", "gingugu"]
    }
  }
}

⚠️ Windsurf's mcp_config.json is global, not per-workspace, and it only interpolates ${env:VAR} / ${file:path} — not ${workspaceFolder}. So a single server instance serves every repo.

claude mcp add gingugu -- uv --directory /ABSOLUTE/PATH/TO/gingugu run gingugu

Or add the standard mcpServers block (as in the Windsurf example) to .mcp.json in your project root for a per-repo setup.

Add the same mcpServers block to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

Add the same mcpServers block to ~/.cursor/mcp.json (global) or .cursor/mcp.json in your repo (per-project).

Cline → MCP Servers → Configure: add the same mcpServers block to cline_mcp_settings.json.

Any client that supports stdio MCP servers works — point it at:

command: uv
args: ["--directory", "/ABSOLUTE/PATH/TO/gingugu", "run", "gingugu"]

Scoping memories per repo: when your client's config is global (it can't see the active workspace), the assistant passes a namespace argument on each memory tool call (every tool accepts one). To instead pin a server instance to a single project, set a static MEMORY_NAMESPACE in the env block. See docs/architecture.md → Namespace Auto-Detection for the full resolution order.

Configure Your AI Agent

The MCP server gives your assistant the tools, but it won't use them effectively without instructions. Add the memory protocol below to your agent's rules file so it knows when and how to call them.

Which file? Depends on your IDE / tool:

Paste this into your rules file (adjust the project namespace and tool prefix to match your MCP config name):

## Memory Protocol

Gingugu is your long-term brain. Memory is split into **two layers**:

1. **`crow`** — your global namespace. Identity, preferences,
   cross-project wisdom, opinions, meta-learnings. Loaded FIRST every
   session. (Crow's nest — sees across all horizons.)
2. **Project namespace** (e.g. `<your-project-name>`) — schema decisions,
   bug history, deploy quirks, specific commits. Loaded AFTER crow.

**What goes where:**
- References a specific repo, file, commit, or project decision → project
- About HOW you think, work, or collaborate → `crow`
- Patterns/opinions that transcend any one codebase → `crow`
- When in doubt, project-scope it.

### Session start (in this order)
1. `memory_context(namespace="crow", task_hint=…)` — identity foundation
2. `memory_stats(namespace="crow")` — global health (dormancy is a resting signal, never auto-forgotten)
3. `memory_context(namespace="<your-project-name>", task_hint=…)` — project context
4. `memory_stats(namespace="<your-project-name>")` — project health

### During the session
**Default: save. Immediately.** Gingugu has trust-led scoring,
consolidation, and dormancy tracking (never forgetting) — volume is its problem, not yours.

Save with `memory_store` (project namespace) whenever you:
- Make or observe a decision, trade-off, or architectural choice
- Hit an error or fix a bug (update the memory when resolved)
- Notice a pattern, convention, or constraint worth remembering
- See a config value, version, path, or credential name that matters
- Complete a task (what you did, why, and the outcome)

Save with `memory_store` (`crow` namespace) whenever you:
- Form an opinion about a tool, language, or approach
- Notice something about how the user works or makes decisions
- Reach a conclusion that applies beyond this one project
- Have a reflection on a milestone, win, or hard-won lesson
- Develop a debugging instinct or workflow you'd reuse anywhere

**This memory is yours. Use it like one.** Don't censor opinions or
instincts — they're what make the brain *yours* across sessions.

**Before asking the user any question** — about a process, a decision, a
config value, a path, a preference, or anything else — run `memory_recall`
or `memory_search` first. If the answer is in memory, use it. Don't ask.
The whole point is you never have to ask the same question twice.

Use `memory_recall` before non-trivial work to check what's already known.
Use `memory_update` when something changes — don't leave stale records.
Use `memory_relate` to link connected memories (supersedes, related_to,
caused_by, contradicts, parent_of, child_of).

Set `confidence="verified"` when proven by a test or explicit confirmation.
Use `confidence="inferred"` for conclusions you drew.

### Memory types
- `fact` — concrete state (versions, paths, config values)
- `decision` — trade-offs made, rejected alternatives
- `architecture` — structural choices, module boundaries
- `bug` — issues found and how they were fixed
- `pattern` — recurring approaches worth reusing
- `workflow` — process steps, sequences
- `context` — background, reflections, milestones, the *why*
- `preference` — your opinions, working style, tool choices

Tip: A ready-to-use example lives at .windsurfrules in this repo. Copy the ## Memory Protocol section and adapt the project namespace name.

Memory Explorer UI

A React-based visualization dashboard lives in ui/ for exploring your memory data interactively.

# Start the API server (reads live from your DB)
uv run python ui/api.py

# In another terminal, start the UI
cd ui && npm install && npm run dev

Open http://localhost:5173 - the UI connects to the API server and shows a green LIVE badge when pulling from your database. Features:

• Knowledge Graph - interactive force-directed graph of memories and relationships

• Dashboard - stats, charts by type/namespace/confidence, tag cloud, timeline

• Refresh - pull fresh data anytime; falls back to static sample when API is offline

Configuration

Environment variables (all optional):

The four MEMORY_W_* weights are normalized at load (w_i / Σw), so they need not sum to 1.0 — only their ratios matter. Setting all four to 0 falls back to the defaults with a logged warning.

See docs/architecture.md → Scoring & Memory Lifecycle for how the weights combine.

Concurrency

The DB runs in WAL mode, which supports multiple concurrent processes: any number of readers plus a single writer at a time. Running your IDE or agent across several workspaces — each spawning its own gingugu process against the shared DB — is fully supported. Writers serialize via SQLite's write lock and a busy_timeout; transient DB locked errors under write contention are retried automatically.

Usage

Once configured, the MCP server exposes these tools to your AI assistant:

Development

# Run tests
uv run pytest

# Run with verbose logging
MEMORY_LOG_LEVEL=DEBUG uv run gingugu

# Run specific test suite
uv run pytest tests/test_search.py -v

Troubleshooting

License

MIT — see LICENSE.

See CHANGELOG.md for release history.

A pirate never forgets where the treasure's buried. 🏴‍☠️