Content
# MCP Shared Memory Server (Go) 🧠⚡
[](https://golang.org)
[](https://modelcontextprotocol.io)
[](LICENSE)
A ultra-fast, local-first Model Context Protocol (MCP) server written in pure Go. Enables seamless session handover and persistent cross-client knowledge sharing between AI Coding Agents (such as **Smara CLI**, **Antigravity**, **Claude Code**, **Cursor**, and **Windsurf**).
---
## 🚀 Quick One-Liner Installer
Running this command will automatically download the pre-built binary, install it to `~/.local/bin`, and configure your AI Agent hooks:
```bash
curl -sSL https://raw.githubusercontent.com/gede-cahya/mcp-shared-memory/master/install-hooks.sh | bash
```
---
## 🌟 Key Features & Advantages
- **Zero-Dependency SQLite Engine**: Built using `modernc.org/sqlite` (CGO-free pure Go), ensuring painless cross-platform compilation and instant startup time (<5ms).
- **Concurrent-Safe Architecture**: WAL (Write-Ahead Logging) mode and busy timeout configuration guarantee zero database lock contention when multiple AI agents write/read simultaneously across different terminal sessions.
- **Cross-Session Auto Handover**: Seamlessly transition tasks, code context, and key decisions between different AI clients or sessions.
- **Persistent Knowledge Graph**: Store long-term project architecture, conventions, and configuration snippets accessible via fuzzy tag searches.
- **Local-First & Private**: Data stays 100% on your local machine (`~/.mcp-shared-memory/db.sqlite`).
---
## 🛠️ MCP Tools Reference
The server exposes 4 standard MCP tools:
### 1. `save_session_handover`
Saves current session progress, context, and remaining tasks to transfer to the next session.
- **Arguments**:
- `project_name` *(string, required)*: Identifier for the workspace/project.
- `summary` *(string, required)*: Concise recap of completed actions.
- `remaining_tasks` *(array of strings)*: Action items for the next session.
- `key_decisions` *(array of strings)*: Architectural or setup decisions made.
- `code_context` *(string)*: Relevant file paths, signatures, or diff summaries.
### 2. `get_session_handover`
Retrieves the most recent session handover entry for a given project.
- **Arguments**:
- `project_name` *(string, required)*: Identifier for the workspace/project.
### 3. `store_knowledge`
Stores long-term facts, conventions, environment configurations, or design decisions.
- **Arguments**:
- `category` *(string, required)*: E.g., `architecture`, `config`, `credential_reference`, `convention`.
- `title` *(string, required)*: Short title.
- `content` *(string, required)*: Markdown or plain text body.
- `tags` *(array of strings)*: List of searchable tags (e.g., `["db", "sqlite"]`).
### 4. `query_knowledge`
Queries knowledge nodes by keyword matching across titles, contents, and tags.
- **Arguments**:
- `query` *(string)*: Search text.
- `tag` *(string)*: Specific tag filter.
- `limit` *(int, default=10)*: Maximum items returned.
---
## 🏷️ Tags & Categories Taxonomy Guide
Organizing memory with standardized tags ensures high retrieval accuracy across AI agents:
| Category | Example Tags | Typical Use Case |
| :--- | :--- | :--- |
| `architecture` | `backend`, `frontend`, `db`, `service-map` | System topology, DB schemas, component flows |
| `config` | `env`, `ports`, `nginx`, `docker` | Local dev setup, port bindings, config paths |
| `convention` | `formatting`, `git`, `linter`, `rules` | Team coding standards, branch rules |
| `decisions` | `adr`, `migration`, `tech-stack` | Architectural Decision Records (ADRs) |
---
## 🚀 How It Works (Multi-Agent Lifecycle)
```
+------------------+ +----------------------------+ +--------------------+
| Claude Code | | mcp-shared-memory | | Antigravity / |
| (Session A) | | SQLite Engine | | Smara CLI |
+--------+---------+ +-------------+--------------+ +---------+----------+
| | |
| --- 1. store_knowledge -------> | [Writes to ~/.mcp-shared-memory] |
| --- 2. save_session_handover -> | |
| | |
| | <--- 3. get_session_handover --- |
| | <--- 4. query_knowledge -------- |
```
1. **Before Session Closes (Agent A)**: Calls `save_session_handover` to freeze state.
2. **On New Session Start (Agent B)**: Automatically calls `get_session_handover` to restore state and pick up where Agent A left off.
3. **During Execution**: Agents store and query reusable facts via `store_knowledge` and `query_knowledge`.
---
## 📦 Installation & Setup
### Automated Quick Install
Run the single command below to install automatically:
```bash
curl -sSL https://raw.githubusercontent.com/gede-cahya/mcp-shared-memory/master/install-hooks.sh | bash
```
### Manual Build
```bash
go build -o bin/mcp-shared-memory-go ./cmd/server
```
### Client Manual Configurations
<details>
<summary><b>Claude Code (~/.claude.json)</b></summary>
```json
{
"mcpServers": {
"mcp-shared-memory": {
"command": "/absolute/path/to/bin/mcp-shared-memory-go"
}
}
}
```
</details>
<details>
<summary><b>Smara CLI / Antigravity (~/.smara/mcp.json)</b></summary>
```json
{
"mcpServers": {
"mcp-shared-memory": {
"command": "/absolute/path/to/bin/mcp-shared-memory-go"
}
}
}
```
</details>
---
## 🏷️ Latest Release Notes (v1.0.0)
### Version 1.0.0 (Initial Production Release)
- **Features**:
- Implemented 4 core MCP tools (`save_session_handover`, `get_session_handover`, `store_knowledge`, `query_knowledge`).
- Added WAL mode & busy handler lock mitigation for concurrent agent access.
- Automated installer script `install-hooks.sh` for global agent system prompt integration.
- **Compatibility**: Standard MCP Protocol JSON-RPC over `stdio`.
---
## 📄 License
Distributed under the MIT License. See `LICENSE` for details.
