# Graphmind

> GraphMind v2 — постоянная общая память для ИИ-агентов по MCP (Rust): граф знаний с причинными связями, семантический поиск, персист между сессиями

- **Type:** MCP server
- **Install:** `agentstack add mcp-kostya-pakhomov-graphmind`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kostya-pakhomov](https://agentstack.voostack.com/s/kostya-pakhomov)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kostya-pakhomov](https://github.com/kostya-pakhomov)
- **Source:** https://github.com/kostya-pakhomov/graphmind

## Install

```sh
agentstack add mcp-kostya-pakhomov-graphmind
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# GraphMind v2

Постоянная общая память для ИИ-агентов, подключается по **MCP** (Model Context Protocol). Один Rust-бинарь: граф знаний с причинными связями, семантический поиск, персист между сессиями. Работает с любым MCP-совместимым агентом — **Kodik, Cursor, Claude Code, Codex, OpenCode**.

**Живое демо:** [gm.bcode.guru](https://gm.bcode.guru) · интерактивная витрина памяти — [gm.bcode.guru/speech](https://gm.bcode.guru/speech).
**Плагин для Kodik** (MCP + правило + навык + суб-агент + хуки) — в [`kodik-plugin/`](kodik-plugin/).

## Что даёт

- **Память между сессиями** — агент стартует с накопленным контекстом проекта.
- **Общий граф на несколько агентов и людей** — один накопил знание, остальные им пользуются.
- **50 MCP-инструментов**: слои памяти S0→L2→L1→L0 с консолидацией, воркспейсы, семантический поиск (эмбеддинги + косинусная близость), причинный слой на LLM (`find_contradictions`, `predict_risks`, `propose_causal_link`), фильтр доверия (`verify_input`), любопытство, ось планирования (`plan_*`).
- **Персист** между перезапусками (RocksDB) + семантический recall из накопленного.

Полный каталог инструментов — [`docs/TOOLS/README.md`](docs/TOOLS/README.md). Архитектура — [`docs/TECH-SPEC.md`](docs/TECH-SPEC.md). Часть документов в [`docs/`](docs/) описывает возможности «на будущее» (маркетплейс, самоподдерживающиеся доки, аналогии) — это концепции, в коде их пока нет.

## Требования сборки

- **Rust** — свежий stable (rustup); сборка проверена на 1.96. Пин 1.85 уже не собирается — часть зависимостей требует новее.
- **protoc** (protobuf) — генерация Rust из `.proto`
- **cmake**, **C++-компилятор** (g++/clang), **libclang** — для нативных зависимостей (RocksDB bindgen)

```bash
# macOS
brew install rustup protobuf cmake      # libclang идёт с Xcode CommandLineTools
# Debian/Ubuntu
sudo apt-get install -y protobuf-compiler g++ cmake clang libclang-dev
```

## Быстрый старт

### 1. Сборка

```bash
cargo build --release --features mcp-server,rocksdb
# бинарь: target/release/graphmind-v2
```

`rocksdb` даёт персист; без фичи бэкенд файловый. `mcp-server` включён по умолчанию.

### 2. Конфиг

Бинарь читает `.env` **рядом с собой** (dotenvy из каталога бинаря, не из cwd) — положите `.env` в `target/release/`. За основу возьмите `config.example.env` — в нём рабочие примеры для RouterAI, локальной Ollama/LM Studio и полностью офлайн-режима (`cp config.example.env .env` и впишите свои endpoint'ы + ключи).

**Зависимость от моделей.** Семантический поиск и причинный слой требуют внешних endpoint'ов (OpenAI-совместимый API):
- **LLM** — любой `/v1/chat/completions` (RouterAI, локальная Ollama/LM Studio, vLLM).
- **Эмбеддинги** — отдельный `/v1/embeddings`: локальная Ollama `bge-m3` (1024d, многоязычная) или RouterAI `multilingual-e5-large` (для e5 нужны префиксы `query:`/`passage:`). `GRAPHMIND_EMBEDDING_DIM` должен совпадать с моделью (bge-m3 → 1024).

Без LLM/эмбеддингов сервер поднимется, но поиск деградирует до ключевых слов, а причинный слой — до эвристики.

### 3. Запуск (HTTP-сервер MCP)

```bash
GRAPHMIND_MCP_HTTP=1 ./target/release/graphmind-v2
# слушает 0.0.0.0:50052 (переопределить: GRAPHMIND_MCP_HTTP_ADDR)
curl -s http://127.0.0.1:50052/health
```

Транспорты одного сервера: `POST /mcp` (Streamable HTTP — Cursor/Codex/OpenCode), `GET /sse` + `/message` (Claude Code), а также **stdio** (без `GRAPHMIND_MCP_HTTP`). Модель работы — **один HTTP-сервер владеет данными, много клиентов** (RocksDB держит эксклюзивный lock на data_dir, поэтому два серверных процесса на одну папку поднять нельзя).

Turnkey в контейнере — [`docker-compose.yml`](docker-compose.yml): `docker compose up -d` (сервер на :50052, том для данных, env из `.env`).

## Подключить агента

Полный гайд на все 5 агентов (регистрация, прокси для stdio-only клиентов вроде Kodik, launchd/Docker) — **[`SHARED-MEMORY-MVP.md`](SHARED-MEMORY-MVP.md)**. Кратко:

| Агент | Транспорт | Как |
|---|---|---|
| Claude Code | SSE | `claude mcp add --transport sse graphmind http://127.0.0.1:50052/sse` |
| Cursor | Streamable HTTP | `.cursor/mcp.json` → `http://127.0.0.1:50052/mcp` |
| Codex | Streamable HTTP | `~/.codex/config.toml` → `/mcp` |
| OpenCode | Streamable HTTP | `opencode.json` → `type: remote`, `/mcp` |
| Kodik | stdio → прокси | `gm_stdio_proxy.py` (мост к общему HTTP-серверу) |

Готовые правила/хуки автоматизации памяти для Cursor — [`templates/`](templates/). Собранный **плагин для Kodik** (MCP + правило + навык + суб-агент-куратор + хуки) — [`kodik-plugin/`](kodik-plugin/): установка через `Ctrl+Shift+X` или из этого репозитория.

## Проверить память

```bash
python3 gm.py list          # последние карточки памяти
python3 gm.py find "запрос"  # семантический поиск
python3 gm.py add "текст"    # записать карточку
```

## Структура

```
.
├── src/                    # Rust: mcp_server/ (handler, http_server, protocol), actors/, persistence/, queue/, grpc/ (легаси)
├── proto/memory.proto      # protobuf-схема
├── tests/                  # интеграционные тесты
├── docs/                   # документация (TOOLS, TECH-SPEC, MECHANISMS, MEMORY, STEPS)
├── templates/              # правила/хуки автоматизации памяти (Cursor)
├── kodik-plugin/           # готовый плагин для Kodik (MCP + правило + навык + суб-агент + хуки)
├── Dockerfile, docker-compose.yml
├── config.example.env
├── gm.py, gm_stdio_proxy.py    # клиент просмотра памяти; stdio-прокси к общему серверу
├── LICENSE                 # MIT
└── SHARED-MEMORY-MVP.md    # гайд подключения агентов
```

## Разработка

```bash
cargo test
cargo clippy -- -D warnings && cargo fmt -- --check
```

`mcp_client.py` — внутренний smoke-харнесс (поднимает свой процесс, конфликтует с общим сервером; не для пользователей).

> gRPC-сервер (:50051, `GRAPHMIND_GRPC_ADDR`) — легаси/вторичный путь; актуальный контур — MCP по HTTP/stdio выше.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kostya-pakhomov](https://github.com/kostya-pakhomov)
- **Source:** [kostya-pakhomov/graphmind](https://github.com/kostya-pakhomov/graphmind)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kostya-pakhomov-graphmind
- Seller: https://agentstack.voostack.com/s/kostya-pakhomov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.