MCP 服务器

Fieldnote MCP

Provides local-first memory storage and retrieval with automatic embedding, vector search, and knowledge graph capabilities. Enables agents to store memories locally and retrieve relevant context through hybrid search with optional Neo4j graph traversal.

README

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.