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

# 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)

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:

make health

Then check docker compose logs for qdrant and neo4j. Open an issue or ping your team with the logs.