⌬ Lexicon Guard

Local knowledge guardian for AI agents — preferences, code styles, decisions, lessons, and user config, all stored in a local SQLite database.

Lexicon Guard is an MCP (Model Context Protocol) server written in Go that acts as a persistent memory layer for AI coding agents. It captures user preferences, coding style conventions, architectural decisions, technical lessons learned, and user configuration — surfacing them to the agent as discoverable MCP tools.

Local-first: All data lives in ~/.lexicon/lexicon.db. No cloud, no telemetry.
Zero CGO: Uses modernc.org/sqlite, a pure-Go SQLite driver.
Dual transport: Supports both stdio (default) and HTTP transport.
Toolbelt layer: Lightweight tool discovery mechanism with categories.
Engram-compatible: Can optionally sync observations to the Engram memory server.

> 💡 Recommended: Use Lexicon Guard alongside Engram for full-spectrum memory. Engram handles project-level observations; Lexicon Guard adds user-level persistent knowledge (preferences, styles, decisions, lessons). Together they cover everything your agent needs to remember. See Relationship with Engram for details.

Quick Start

Install

# macOS / Linux (recommended)
brew install seinra/lexicon-guard/lexicon-guard

# Windows
winget install Seinra.lexicon-guard

# Cross-platform (from source)
go install github.com/Seinra/lexicon-guard/cmd/lexicon@latest

> Tip: For a real version string instead of dev: > > bash > go install -ldflags="-X main.version=v0.1.0" github.com/Seinra/lexicon-guard/cmd/lexicon@latest >

Setup Your Agent

# Install for all detected agents (Pi, VS Code, Cursor, Codex, etc.)
lexicon setup --all

# Or install for specific agents
lexicon setup --agent pi --agent vscode --agent cursor

# List supported agents
lexicon setup --list-agents

Agent	One-liner
Pi	`lexicon setup pi`
VS Code (Copilot)	`lexicon setup vscode`
Cursor	`lexicon setup cursor`
Codex	`lexicon setup codex`
OpenCode	`lexicon setup opencode`
Gemini CLI	`lexicon setup gemini-cli`
Windsurf	`lexicon setup windsurf`
Claude Code	`lexicon setup claude-code`
Antigravity CLI	`lexicon setup antigravity-cli`
Qwen Code	`lexicon setup qwen`
Kiro IDE	`lexicon setup kiro`
Kilo Code	`lexicon setup kilocode`
Any other MCP client	See Agent Setup

What lexicon setup does — writes MCP config and instruction files for the chosen agent. After setup, restart your agent and it's ready. No server to start manually.

> Do I need to run lexicon --http or lexicon myself? > > For most agents (VS Code, Cursor, Codex, Gemini CLI, Windsurf) — no. Your agent launches lexicon automatically as a short-lived stdio subprocess whenever it starts a session. You never run it manually. > > lexicon --http is only needed when you want the REST API or OpenAPI spec available on a port.

No Node.js, no Python, no Docker. One binary, one SQLite file.

Features

16 MCP tools covering preferences, coding styles, design decisions, lessons learned, context, web requests, and Engram sync — all auto-discoverable by the agent.
Toolbelt discovery layer — agent explores available tools without loading all schemas at once (tools loaded on demand).
Cross-platform installer — lexicon setup works on macOS, Linux, and Windows, supporting 12 agents.
Dual transport — stdio (default, automatic) and HTTP (opt-in with --http).
REST API — Create and read operations over HTTP at /api/v1/*, plus OpenAPI 3.1 spec.
FTS5 full-text search over lessons learned.
Engram sync — push, pull, or bidirectional sync with the Engram memory server. Also serves as a failover mechanism: if Engram is down, save to Lexicon Guard's local DB and sync push when it recovers.
Engram proxy — direct lexicon_mem_search / lexicon_mem_get_observation with a 3s timeout. Returns a degraded-mode response (not an error) when Engram is unreachable, so the agent knows to use local tools instead.
Rate limiting — 100 req/min per IP on REST routes.
Audit logging — every write operation is logged internally.
Graceful shutdown — handles SIGINT/SIGTERM.

Tools Reference

Lexicon Guard exposes 16 MCP tools that the agent uses automatically. The Toolbelt is a lightweight discovery layer that lets the agent explore what tools exist without loading all their schemas — loads on demand only what it needs.

Available Tools (16)

Tool	Purpose
`lexicon_preference_set`	Create or update a user preference
`lexicon_preference_get`	Get a user preference by key
`lexicon_preference_list`	List preferences, optionally filtered by category
`lexicon_style_set`	Set coding style for a language
`lexicon_style_get`	Get coding style for a language
`lexicon_decision_save`	Save an architecture or design decision
`lexicon_decision_list`	List recent decisions
`lexicon_context_set`	Create or update a context entry (key/value with scope: global/project/session)
`lexicon_context_get`	Get context entries, optionally filtered by scope
`lexicon_lesson_save`	Save a technical lesson learned
`lexicon_lesson_search`	Search lessons by text or tags (FTS5 full-text search)
`lexicon_lesson_list`	List recent lessons
`lexicon_webrequest`	Make HTTP/HTTPS requests (API docs, etc.)
`lexicon_sync_engram`	Sync observations with an Engram server (push/pull/both)
`lexicon_mem_search`	Search Engram observations directly (proxy, 3s timeout)
`lexicon_mem_get_observation`	Get an Engram observation by ID directly (proxy)

Toolbelt: Discovery Layer

The Toolbelt prevents overwhelming the agent with 16 full schemas at once:

Tool	Description
`toolbelt/list`	All tools with name, description, category (no inputSchema)
`toolbelt/schema`	Full inputSchema for a specific tool (on-demand)
`toolbelt/categories`	Available categories

Categories: preferences, styles, decisions, lessons, context, system, engram.

How it works: Agent calls toolbelt/list → sees categories → toolbelt/categories → filters → toolbelt/schema for specific tool → calls the tool.

The agent calls these tools automatically when relevant — you don't invoke them manually.

Relationship with Engram

Lexicon Guard is complementary to Engram, not a replacement.

Dimension	Engram	Lexicon Guard
Scope	Project-level memory (observations per project)	User-level memory (global preferences, styles, decisions, lessons)
Focus	General-purpose observation store	Structured knowledge domains with typed schemas
Transport	HTTP server	stdio (default) + HTTP (optional)
Search	Basic query	FTS5 full-text search over lessons + structured queries
Setup	Run as a standalone HTTP service	Agent launches automatically via MCP config
Sync	—	Can push/pull observations to/from Engram

Use Engram for project-level ephemeral observations. Use Lexicon Guard for user-level persistent knowledge that survives across projects. Together they cover the full memory spectrum.

Lexicon Guard can sync with Engram via lexicon_sync_engram (push, pull, or bidirectional), and also provides lexicon_mem_search / lexicon_mem_get_observation as proxy tools with a longer timeout for when the agent's health check is too strict. This sync also acts as a failover mechanism: if Engram is unreachable, save data locally via lexicon_* tools and sync push when Engram recovers.

Documentation

Doc	Description
Installation	All install methods + platform support
Agent Setup	Per-agent configuration + Memory Protocol
Architecture	How it works, REST endpoints, OpenAPI spec, project structure
Usage Instructions	MCP tool reference, sync configuration + conflict resolution

Architecture

┌────────────────────┐     ┌────────────────────────┐
│  Agent / Client    │     │   HTTP (optional)      │
│  (Claude, Cline,   │     │   POST /mcp/server     │
│   custom MCP host) │     │   + REST API           │
└────────┬───────────┘     └───────────┬────────────┘
         │ stdio (JSON-RPC 2.0)        │ HTTP
         ▼                              ▼
┌────────────────────┐     ┌────────────────────────┐
│    StdioServer     │     │      MCPServer         │
│  (internal/server/)│     │  (internal/server/)    │
└────────┬───────────┘     └───────────┬────────────┘
         │                              │
         └──────────────┬───────────────┘
                        ▼
         ┌────────────────────────┐
         │     ServerManager      │
         │   (internal/tools/)    │
         │  Business logic +      │
         │  audit logging         │
         └────────────┬───────────┘
                      ▼
         ┌────────────────────────┐
         │     Store Interface    │
         │   (internal/db/)       │
         │  SQLite persistence    │
         └────────────────────────┘

Layers:

Transport (internal/server/) — StdioServer + MCPServer handle JSON-RPC 2.0
Business logic (internal/tools/) — ServerManager, handlers, validation, audit
Persistence (internal/db/) — Store interface backed by SQLite (pure Go, no CGO)
Engram sync (internal/engram/) — Optional client to sync observations

Project Structure

cmd/lexicon/
├── main.go              # CLI entry, flag parsing, server selection
├── setup.go             # `lexicon setup` command
├── uninstall.go         # `lexicon uninstall` command

internal/
├── db/                  # SQLite persistence, types, CRUD
├── engram/              # Engram HTTP client, mapping, config
├── server/              # Stdio/HTTP transport, REST, toolbelt
├── testutil/            # Mock store for tests
└── tools/               # Business logic, handlers, schema

Configuration

Zero config by default. Database auto-created at ~/.lexicon/lexicon.db.

CLI Flags

Flag	Default	Description
`--http`	`""`	HTTP listen address (e.g. `:50051`). Empty = stdio-only.

Engram Sync (Environment Variables)

See Usage Instructions — Engram Sync Details for full reference.

Database

Engine: SQLite via modernc.org/sqlite (pure Go, no CGO)
Location: ~/.lexicon/lexicon.db
Tables: preferences, styles, decisions, context, lessons_learned, audit_logs
Schema: Auto-created on first run — no migrations needed

Acknowledgments

Built with gratitude to the Gentleman Programming community for Engram — the peer memory system Lexicon Guard was designed to complement — and to the Gentle-AI ecosystem that made development a joy.

Special thanks to The Gentleman for creating and maintaining Engram, whose design inspired Lexicon Guard's sync capabilities and whose existence as a complementary project shaped its architecture from day one.

Contributing

Contributions welcome! Open an issue or submit a PR on GitHub.

License

MIT License — see LICENSE for details.

lexicon-guard Seinra

README