knowledge

Documentation

Overview

MCP subprocess client for mcp-neo4j-cypher (Pattern 3). Aura never links a native Go Neo4j driver (CLAUDE.md §Project scope discipline ban); every Cypher call rides a stdio JSON-RPC 2.0 channel to the subprocess, which holds the only bolt connection. Requests are serialized through mu since a single stdio pipe pair cannot interleave. D-06: a subprocess crash is unrecoverable — we surface a wrapped error and let the caller fail the Aura process; no restart, no graceful degrade.

Package knowledge is the graph + vector substrate: an MCP-subprocess Cypher client (no native Go Neo4j driver per CLAUDE.md §Project scope discipline ban), a Cypher migration runner that audits applied versions in Postgres aura.knowledge_migrations, and the embedding-sidecar dim self-test that makes the AURA_EMBED_DIMENSIONS=384 contract operational (Amendment #18 / Pitfall #5).

Config is pure data, populated by internal/config from the environment. It carries everything the MCP client and embed self-test need; no methods.

Cypher migration runner (Pattern 4). .cypher files numbered like SQL migrations are embedded into the binary; applied versions are audited in the Postgres aura.knowledge_migrations table (created by Slice 0.5), consumed here via the sqlc-generated bindings. New migrations execute statement-by-statement through the driver-backed SchemaExecutor (auto-commit — see schema.go for why MCP cannot run schema DDL); on success an audit row is written. Re-running is idempotent: already-applied versions are skipped, and a checksum drift on an applied version is a hard error (history corruption).

Health probes for the graph substrate (Pattern 5). Ping runs two checks: the MCP/Neo4j liveness call (dbms.components, asserts a 5.26.x kernel) and the embed-sidecar dim self-test. The dim self-test is the ONLY place the AURA_EMBED_DIMENSIONS=384 contract becomes operational (Amendment #18 / Pitfall #5): a sidecar returning the wrong dimension would silently corrupt the HNSW index, so we refuse to start on mismatch with a load-bearing error.

Connectivity probe for the Neo4j graph substrate, used by the serve daemon's /readyz readiness endpoint (O-05/AP-14). It dials bolt with the native driver, forces a real connection via VerifyConnectivity, and closes — no long-lived handle, no MCP subprocess. A connectivity failure is returned so the readiness endpoint can answer 503 when the required graph backend is unreachable.

Reset is the dev-only destructive teardown behind `aura neo4j reset --yes`. It drops the D-08 schema objects, deletes all nodes, clears the Postgres audit trail so versions re-apply, then re-runs Migrate to a clean baseline. Schema DROPs and the bulk delete both go through the driver-backed SchemaExecutor (auto-commit) for the same reason migrate does — MCP cannot run schema DDL. Never wire this into a non-dev path; the CLI dispatcher owns the --yes + AURA_RESET_YES guard.

Schema DDL executor backed by the official Neo4j Go driver. This is the CLAUDE.md-sanctioned "Go driver native (fallback se mcp-neo4j-cypher non sufficiente)" path, used ONLY for schema operations (CREATE/DROP CONSTRAINT|INDEX). The MCP subprocess (client.go) remains the LLM-facing runtime interface for data reads/writes.

Why a separate path: Neo4j forbids schema commands inside an explicit transaction, and mcp-neo4j-cypher's write tool always wraps queries in a managed write-tx — so it rejects schema DDL ("Only write queries are allowed"). The industrial pattern (golang-migrate's neo4j driver, Neo4j-Migrations) runs schema via the driver in AUTO-COMMIT mode: session.Run, never ExecuteWrite. D-06 spirit is preserved: a connectivity failure errors out (no restart, no graceful degrade).

Status reads the applied-Cypher-migration audit trail from Postgres (aura.knowledge_migrations) via the Slice 0.5 sqlc bindings, for `aura neo4j status` tabulation. Postgres is the source of truth for migration history; Neo4j Community has no migration tracker of its own.

Index

• Constants
• func Migrate(ctx context.Context, schema *SchemaExecutor, pool *pgxpool.Pool) (int, error)
• func Reset(ctx context.Context, schema *SchemaExecutor, pool *pgxpool.Pool) error
• func VerifyConnectivity(ctx context.Context, cfg *Config) error
• type Client
  • func Open(ctx context.Context, cfg *Config) (*Client, error)
  • func (c *Client) Close() error
  • func (c *Client) Cypher(ctx context.Context, query string, params map[string]any, write bool) (json.RawMessage, error)
  • func (c *Client) Read(ctx context.Context, query string, params map[string]any) ([]map[string]any, error)
  • func (c *Client) Write(ctx context.Context, query string, params map[string]any) ([]map[string]any, error)
• type Config
• type MigrationRow
  • func Status(ctx context.Context, pool *pgxpool.Pool) ([]MigrationRow, error)
• type PingResult
  • func Ping(ctx context.Context, mcp *Client, cfg *Config) (*PingResult, error)
• type SchemaExecutor
  • func OpenSchema(ctx context.Context, cfg *Config) (*SchemaExecutor, error)
  • func (s *SchemaExecutor) Close(ctx context.Context) error
  • func (s *SchemaExecutor) Exec(ctx context.Context, stmt string) error

Constants

const DefaultEmbedDimensions = 384

DefaultEmbedDimensions is the vector width emitted by the repo's default Granite embedding sidecar and encoded in the initial Neo4j HNSW index.

Functions

func Migrate

func Migrate(ctx context.Context, schema *SchemaExecutor, pool *pgxpool.Pool) (int, error)

Migrate applies every embedded .cypher migration not yet recorded in aura.knowledge_migrations and returns the count newly applied. Idempotent.

func Reset

func Reset(ctx context.Context, schema *SchemaExecutor, pool *pgxpool.Pool) error

Reset drops indexes/constraints + all nodes, clears the audit table, and re-applies migrations. Dev only.

func VerifyConnectivity

func VerifyConnectivity(ctx context.Context, cfg *Config) error

VerifyConnectivity dials Neo4j over bolt and confirms the server is reachable, then releases the driver. The supplied ctx bounds the dial+verify (the caller passes a short readiness timeout). It does NOT assert a kernel version (that is the boot-time Ping's job, ping.go) — readiness is a liveness signal for traffic routing, not a version gate.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client wraps the mcp-neo4j-cypher subprocess. The zero value is unusable; use Open.

func Open

func Open(ctx context.Context, cfg *Config) (*Client, error)

Open spawns mcp-neo4j-cypher in stdio transport mode against cfg's bolt endpoint. On spawn failure the error carries the literal install hint so an operator missing the binary on PATH gets an actionable message.

func (*Client) Close

func (c *Client) Close() error

Close shuts the subprocess down by closing its stdin and waiting for exit.

func (*Client) Cypher

func (c *Client) Cypher(ctx context.Context, query string, params map[string]any, write bool) (json.RawMessage, error)

Cypher sends one read or write Cypher call and returns the raw MCP result. Serialized via mu. Send/recv failures wrap crashHint (D-06) with redacted stderr so a dead subprocess fails Aura with an actionable, secret-free error.

func (*Client) Read

func (c *Client) Read(ctx context.Context, query string, params map[string]any) ([]map[string]any, error)

func (*Client) Write

func (c *Client) Write(ctx context.Context, query string, params map[string]any) ([]map[string]any, error)

type Config

type Config struct {
	BoltURL           string // bolt://host:7687 — passed to mcp-neo4j-cypher --db-url
	User              string // Neo4j auth user (default neo4j)
	Password          string // Neo4j auth password (NEO4J_PASSWORD; never logged unredacted)
	Database          string // Community edition is single-DB; always "neo4j" (Pitfall #8)
	MCPBinary         string // mcp-neo4j-cypher executable on PATH
	ConnectTimeoutSec int    // first-call connect/retry budget
	EmbedURL          string // OpenAI-compat embeddings base URL (sidecar)
	EmbedDimensions   int    // contract dim; boot self-test refuses a mismatch
}

Config holds the Neo4j + mcp-neo4j-cypher + embed-sidecar wiring. Populated by internal/config.Load from NEO4J_*, AURA_NEO4J_*, AURA_MCP_NEO4J_*, AURA_EMBED_*.

type MigrationRow

type MigrationRow struct {
	Version   int32
	Name      string
	Checksum  string
	AppliedAt time.Time
}

MigrationRow is one applied-migration audit record for CLI display.

func Status

func Status(ctx context.Context, pool *pgxpool.Pool) ([]MigrationRow, error)

Status returns the applied Cypher migrations ordered by version ascending.

type PingResult

type PingResult struct {
	ServerVersion string
	EmbedDim      int
}

PingResult carries what the CLI prints on a healthy ping.

func Ping

func Ping(ctx context.Context, mcp *Client, cfg *Config) (*PingResult, error)

Ping verifies the MCP/Neo4j channel then the embed sidecar dimension.

type SchemaExecutor

type SchemaExecutor struct {
	// contains filtered or unexported fields
}

SchemaExecutor runs Cypher schema DDL via auto-commit driver sessions.

func OpenSchema

func OpenSchema(ctx context.Context, cfg *Config) (*SchemaExecutor, error)

OpenSchema dials Neo4j over bolt and verifies connectivity. Caller must Close.

func (*SchemaExecutor) Close

func (s *SchemaExecutor) Close(ctx context.Context) error

Close releases the driver connection pool.

func (*SchemaExecutor) Exec

func (s *SchemaExecutor) Exec(ctx context.Context, stmt string) error

Exec runs one schema statement in an auto-commit transaction. Using session.Run (NOT ExecuteWrite) is mandatory: schema DDL is rejected inside an explicit tx.