echovault AGENTS.md

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Project Overview

EchoVault is a local memory system for coding agents. It persists decisions, bugs, patterns, and context across sessions in a SQLite database (with FTS5 full-text search and sqlite-vec vector embeddings) and exposes them through a CLI binary (memory) and an MCP (Model Context Protocol) stdio server.

Build & Development Commands

All builds, tests, and linting MUST be run through the Makefile. Do NOT run go build, go test, golangci-lint, or other tools directly — always use the corresponding make target.

# Build for current platform (optimised)
make build

# Build without cross-compile flags (fastest local build)
make build-native

# Run all tests (CGO_CFLAGS set automatically for FTS5)
make test

# Run a single test (exception: no make target, use go test directly)
CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" go test -run TestName ./path/to/package

# Run all linters (nolintguard, qtlint, golangci-lint) — must pass before commit
make lint

# Run linters with auto-fix
make lint-fix

# Install/tidy dependencies
make deps

# Clean build artifacts
make clean

# See all available targets
make help

CGO Requirements

This project requires CGO throughout — CGO_ENABLED=1 is always set by the Makefile. Two C-backed SQLite extensions are in use:

• github.com/mattn/go-sqlite3 — SQLite driver compiled via CGO
• github.com/asg017/sqlite-vec-go-bindings — vector similarity search extension via CGO

When running tests directly (not via make test), always set:

CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" go test ./...

Omitting CGO_CFLAGS="-DSQLITE_ENABLE_FTS5" causes "no such module: fts5" errors at runtime.

Code Style (golangci-lint)

The following rules are enforced by .golangci.yml. Code MUST comply to pass CI.

Import Organization (gci formatter)

Imports must be organized in three groups, separated by blank lines:

1. Standard library
2. Third-party packages
3. Local packages (github.com/go-ports/echovault/...)