📑 Index
📖 Overview
getMe is a persistent, embeddable key-value store written in Go. It is inspired by the design of Bitcask and is optimized for high write throughput and low-latency reads.
It uses a log-structured storage approach, ensuring that all data is appended sequentially. It uses Unix Domain Sockets (UDS) for incredibly fast local inter-process communication, alongside several interfaces like an HTTP proxy, a CLI, and a Model Context Protocol (MCP) server for LLMs.
🏗 Project Structure
This project is a monorepo containing the core storage server, multiple client interfaces, and tools.
server/: The core storage daemon and engine. Implements the log-structured hash table for persistent storage. See server/README.md for architectural deep-dives.cli/: A command-line interface for interacting with the getMe server for testing and debugging.sdks/: Client libraries (goSdk, javaSdk, jsSdk, pythonSdk) to integrate getMe into your applications.http-proxy-go/: An HTTP server built using the goSdk that exposes the core engine's Unix Domain Socket connection over standard HTTP routes.mcp-server/: A Model Context Protocol (MCP) server that exposes the getMe database as tools to Large Language Models (like Claude or Cursor).commons/: Shared code, socket paths, types, and constants used across the monorepo to ensure consistency.utils/: Shared utility packages, including logging stack configurations (Loki + Alloy + Grafana).
Spotlight: The curated inner docs are the quickest way to understand the system end-to-end. Start with server/README.md for architecture fundamentals, then explore the cli and mcp-server modules for integrations.
🧠 Core Architecture
The storage engine relies on a few core principles:
- Log-Structured Storage: All data is written to an append-only log file. This makes writes extremely fast as it avoids slow, random disk I/O.
- In-Memory Hash Index: A hash table is kept in memory, mapping each key to the exact location of its value on disk. This allows for very fast read operations (typically one disk seek).
- Compaction: A background process that periodically cleans up old, stale data from the log files to reclaim disk space.
- Fast Local Transport: Communication is done predominantly via Unix Domain Sockets, avoiding standard TCP overhead locally.
🚀 Getting Started
Running the Server
The repository ships with helper scripts to bootstrap the environment.
Option A: Local binaries + logging stack
Switch to the server module and run the local init script:
cd server
./init-server-local.sh
This script builds the Go binary into server/dist/, prepares data/log/socket directories, and starts the Loki + Alloy + Grafana logging stack via Docker Compose before launching the server in the foreground.
Warning: Do not prefix this script with sudo. It will invoke elevated privileges internally where needed. Using sudo at the top level causes permission errors for local development.
Option B: Full Docker Compose stack
From the same server directory run:
cd server
./init-server-docker.sh
This ensures host directories exist, exports your UID/GID, and invokes docker compose up --build to run everything in containers.
Using the CLI
Interact directly with the local server:
cd cli
go run . put mykey "hello world"
go run . get mykey
go run . delete mykey
HTTP Proxy
If you want standard HTTP REST endpoints instead of Unix Sockets, run the Go HTTP proxy:
cd http-proxy-go
go run main.go -port 8080
This will allow you to run curl http://localhost:8080/get?key=mykey.
MCP Server
getMe can be used by LLM clients (like Claude Desktop) through the Model Context Protocol.
cd mcp-server
uv run getme-mcp-server
(See mcp-server/README.md for configuration and integration instructions).
📊 Running Benchmarks & Tests
To ensure no performance regressions or to stress test the database:
- Navigate to the specific module (e.g.,
server).
- Run standard tests:
go test ./...
- Run benchmarks:
go test -bench . ./...
(Note: For heavier stress/correctness testing, look into server/tests/).
📦 SDKs
SDKs are available across different languages. Find them in the sdks/ directory:
All SDKs interface directly with the Unix Domain Socket to provide optimal latency.
⚠️ Note on SDK Releases: SDK versioning and publishing is managed automatically via an Ephemeral Release Structure. The CI/CD pipelines autonomously orchestrate the entire release lifecycle—from creating detached commits and tagging them, to generating changelogs and pushing builds to public registries—all from a single bump-type trigger. This keeps the main branch entirely clean of meaningless version-bump commits.
If you are exploring the code or contributing, do not manually bump versions in PRs. You can read more about this advanced architecture in the SDKs README.
📄 License
This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) - see the LICENSE file for details.
