Fieldnote MCP

# Fieldnote MCP Local‑first memory and a symmetrical knowledge graph you can clone, start, and use in minutes. This repo gives any agent or app three superpowers: * **Auto‑store memory** — drop text in, it’s embedded and saved locally. * **Auto‑recall & inject** — retrieve relevant memories and assemble a ready‑to‑paste context block. * **Symmetrical Knowledge Graph** — every memory can mirror into Neo4j with inverse edges for clean traversal. It’s portable, version‑pinned, works on macOS/Linux/WSL/Windows, and never asks for root. --- ## What’s inside * **Qdrant** (vector DB) + **Neo4j** (graph) via Docker Compose * **Cross‑platform shims** so the same commands work everywhere: * `memory-store`, `memory-search`, `context-inject`, `mcp-health`, `qdrant-run` * **Hybrid retrieval** (dense + optional sparse) * Dense: MiniLM (pinned) * Sparse (optional): BGE‑M3 if available, with hashing fallback so demos never block * **Health gate** to verify services before use * **.env overrides** to configure without touching code --- ## Requirements * **Docker Desktop** (macOS/Windows) or Docker Engine (Linux) * **Python 3.11+** (for local CLI tools) * \~2GB free disk space for local data > No sudo needed. Everything lives in `~/dev/mcp` by default. --- ## Quickstart (copy/paste) ### macOS / Linux / WSL ```bash # 0) place the repo at the expected path mkdir -p ~/dev && cd ~/dev # if you downloaded an archive, extract it to ~/dev/mcp; if using git: # git clone <your-repo-url> mcp cd ~/dev/mcp # 1) bootstrap local env & command shims (idempotent) ./mcp-init.sh # 2) env config (optional; overrides defaults) cp .env.example .env # edit .env as needed # 3) start services docker compose up -d # 4) verify make health # 5) try the demo make demo ``` ### Windows (PowerShell) ```powershell cd $HOME\dev\mcp .\mcp-init.ps1 Copy-Item .env.example .env # Edit .env if you want to change ports/creds docker compose up -d make health make demo ``` Expected demo output: * `memory-store` responds with `{ "status": "ok", "id": "…" }` * `memory-search` prints top hits (hybrid if enabled) * `context-inject` prints a compact block of the highest‑scoring memories (ready to paste into an agent prompt) --- ## Everyday commands * `make compose-up` / `make compose-down` / `make compose-logs` – manage services * `make health` – confirm Qdrant + Neo4j are reachable (and collection exists) * `make demo` – store → search → inject in one go * `make clean-data` – wipe Qdrant storage; `make clean-compose` also wipes Neo4j * `qdrant-run` – portable runner if you’re not using Compose (Linux/Docker fallback) CLI shims installed to `~/dev/mcp/bin`: * `memory-store` — embed + upsert to Qdrant, then mirror to KG * `memory-search` — dense (and sparse if enabled) retrieval with optional KG symmetry expansion * `context-inject` — assembles a ready‑to‑paste context block from top memories * `mcp-health` — sanity check for Qdrant/Neo4j Registered in `plugins.json` so orchestrators can discover them. --- ## Configure All defaults live in `config/memory.config.json`. Anything in **.env** overrides it at runtime. **.env keys** (see `.env.example`): | Key | Meaning | Default | | --------------------------- | ----------------------------- | ---------------------------------------- | | `QDRANT_URL` | Qdrant HTTP endpoint | `http://127.0.0.1:6333` | | `QDRANT_COLLECTION` | Collection name | `fieldnote_memory` | | `DENSE_MODEL` | SentenceTransformer model | `sentence-transformers/all-MiniLM-L6-v2` | | `TOP_K` | Search results to return | `8` | | `NEO4J_URI` | Bolt URI | `bolt://127.0.0.1:7687` | | `NEO4J_USER` / `NEO4J_PASS` | Neo4j credentials | `neo4j` / `password` | | `INJ_MAX_TOKENS` | Max tokens to inject | `2000` | | `INJ_SCORE_THRESHOLD` | Minimum similarity to include | `0.75` (recommended) | | `SPARSE_ENABLED` | Enable sparse lane | `true` | | `SPARSE_MODEL` | Sparse model | `bge-m3` | | `SPARSE_HASH_DIM` | Hashing fallback dim | `32768` | > Tip: If you enable sparse on an existing collection created without it, start fresh (rename the collection or run `make clean-compose`). --- ## How it works ``` Store text ──▶ memory-store ──▶ Qdrant (dense [+ sparse]) │ └─▶ GraphSync hook ──▶ Neo4j (symmetrical edges) Query ──▶ memory-search ──▶ Qdrant hybrid search │ └─▶ optional KG symmetry expansion Assemble ──▶ context-inject ──▶ compact, thresholded context block ``` * **Symmetry**: When a relation has a defined inverse (e.g., `depends_on ↔ supports`), both directions are stored so traversals stay consistent. * **Hybrid**: If `SPARSE_ENABLED=true`, sparse vectors are stored alongside dense. If BGE‑M3 isn’t installed, a hashing fallback keeps hybrid functional. Open Neo4j Browser at `http://localhost:7474` to explore the graph. Qdrant Console is available via the API (`:6333`). --- ## Data & paths * Qdrant data: `qdrant/storage/` * Neo4j data: `neo4j/data/` * Local venvs: `venv/` (Linux/macOS/WSL), `win-venv/` (Windows) * PATH shims: `~/dev/mcp/bin` All are git‑ignored by default. --- ## Troubleshooting **"connection refused" on health check** * Ensure Docker is running and `docker compose up -d` completed. **Ports already in use** * Change ports in `.env` / `docker-compose.yml` or stop the conflicting service. **Windows symlink errors** * Enable Developer Mode, or replace symlinks with tiny `.cmd` wrappers that call `python`. **KG looks empty** * Run the demo (`make demo`) or start storing memories. Graph is populated by the post‑store hook. **Sparse/hybrid isn’t kicking in** * Confirm `SPARSE_ENABLED=true`. If BGE‑M3 isn’t available, the hashing fallback still enables hybrid queries. --- ## Extend * **Typed relations**: Enrich `hooks/graphsync_post_store.py` with light keyword rules or your own IE pipeline. * **Keep models hot**: Wrap store/search in a small FastAPI service (you already have `uvicorn` + `fastapi`). * **Provenance**: Add `source_id`, `confidence` to edges for auditing. --- ## Security * Don’t commit real credentials. `.env` is git‑ignored. * Everything runs locally by default; expose ports only if you know why. --- ## License Project Navi - Dual License This software is dual-licensed: Option A: GNU Affero General Public License v3.0 (AGPL-3.0) - For open source use - See https://www.gnu.org/licenses/agpl-3.0.html Option B: Commercial License (PNEUL-D v2.2) - For proprietary/closed-source use - Contact legal@projectnavi.ai for licensing Full license terms: /docs/legal/ --- ## Support If something feels off, run: ```bash make health ``` Then check `docker compose logs` for `qdrant` and `neo4j`. Open an issue or ping your team with the logs.