# Lex

> Episodic memory and architectural policy for AI agents. Frames, Atlas, and Policy.

- **Type:** MCP server
- **Install:** `agentstack add mcp-guffawaffle-lex`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Guffawaffle](https://agentstack.voostack.com/s/guffawaffle)
- **Installs:** 1
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 2.1.2
- **License:** MIT
- **Upstream author:** [Guffawaffle](https://github.com/Guffawaffle)
- **Source:** https://github.com/Guffawaffle/lex

## Install

```sh
agentstack add mcp-guffawaffle-lex
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Lex

**Local memory and policy context for AI coding agents.**

**Don't trust the README. Ask your agent.**

> "Would repo-local memory and policy context help you work in this codebase with fewer repeated explanations, fewer forgotten constraints, and better handoffs between sessions?"

If the answer is yes, Lex is the layer that gives your agent somewhere durable to put that context.

[](./LICENSE)
[](https://www.npmjs.com/package/@smartergpt/lex)
[](https://github.com/Guffawaffle/lex/actions)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)

[60-second test](#the-60-second-test) | [Quick Start](#quick-start) | [Agent Integration](#agent-integration) | [Documentation](#documentation) | [API Reference](#api-reference) | [Contributing](./CONTRIBUTING.md)

---

## What Lex gives your agent

Lex is repo-local memory and policy context for AI coding agents. It stores structured work snapshots, recalls relevant prior context, and connects that context to repository policy when a policy file is available.

Agents get:

- Durable Frames for reference points, summaries, blockers, next actions, branches, tickets, and module scope
- Policy-aware recall that can surface nearby module context instead of asking the human to restate it
- Structured CLI and MCP responses that are easier for tools to parse
- Stable tool names and explicit error codes for recovery
- Repo-local context stored in SQLite and repository files, not a cloud memory service
- CLI, MCP, and TypeScript API surfaces for different agent runtimes

Humans do not need to understand the whole framework before adoption. The first useful question is simply whether your agent keeps asking you to repeat context the repository could remember.

---

## The 60-second test

Paste this into Copilot, Claude, Cursor, or another coding agent while it has access to your repository:

```text
Look at this repository. Would a repo-local memory and policy layer help you avoid repeated context setup, forgotten project constraints, or poor handoffs? If yes, where would Lex help first?
```

A useful answer usually names a recurring handoff problem: interrupted feature work, architecture-sensitive modules, policy constraints, release workflows, or places where agents repeatedly need the same explanation.

---

## How it works

### Frames: work memory

Frames capture meaningful moments in a development workflow:

```bash
lex remember \
  --reference-point "Implementing user authentication" \
  --summary "Added JWT validation to API middleware" \
  --next "Wire up password reset flow" \
  --modules "services/auth,api/middleware" \
  --blockers "Need PermissionService access - forbidden edge in policy" \
  --jira "AUTH-123"
```

Frames are meant for durable agent context: what changed, what remains, where it happened, and what should be respected next time.

[Learn more about Frames](./docs/MIND_PALACE.md)

### Recall: prior context on demand

Later, an agent can recall relevant context by topic:

```bash
lex recall "authentication"
# Returns matching context, blockers, next action, and relevant module neighborhood.
```

Recall is the everyday adoption path: before changing code, ask Lex what prior work, blockers, and nearby boundaries matter.

### Atlas: nearby repository context

When a Frame is recalled, Lex can provide an Atlas Frame: the touched modules plus their immediate neighborhood, including dependencies, dependents, and permissions.

This fold-radius approach keeps recall focused on nearby repository context instead of flooding the agent with the whole codebase.

[Learn more about Atlas](./docs/ARCHITECTURE.md)

### Policy: architectural boundaries

Lex policy files define repository boundaries as code:

```json
{
  "modules": {
    "ui/components": {
      "owns": ["src/ui/components/**"],
      "mayCall": ["services/auth", "ui/shared"],
      "forbidden": [
        {
          "target": "database/queries",
          "reason": "UI must not access database directly. Use API layer."
        }
      ]
    }
  }
}
```

Enforce in CI:

```bash
lex check merged-facts.json
# Violation: ui/components -> database/queries (forbidden edge)
# Reason: UI must not access database directly. Use API layer.
```

[Learn more about Policy](./docs/API_USAGE.md)

### Instructions: project assistant guidance

Lex can project canonical assistant instructions into host-specific files:

```bash
# Your canonical instructions live in one place
.smartergpt/instructions/lex.md

# Project them to host-specific files
lex instructions generate
# Creates: .github/copilot-instructions.md, .cursorrules
```

The marker system preserves human content while keeping generated agent guidance deterministic.

[Learn more about Instructions](./docs/INSTRUCTIONS.md)

---

## Quick Start

### Installation

```bash
# Install globally (recommended)
npm install -g @smartergpt/lex

# Or locally in your project
npm install @smartergpt/lex
```

Requires Node.js 20+ and currently supports Node.js 20 through 24, matching the package engine range.

WSL users should use a native WSL install on `PATH`, not Windows npm shims or npm's `_npx` cache. See [WSL Native Lex Install](./docs/WSL_NATIVE_INSTALL.md) for the recommended user-local install, checkout symlink bridge, and native SQLite build requirements.

Lex supports structured output (`--json`), recoverable errors (AXError), and Frame Schema v3 for orchestrator integration. Commands provide both human-readable and machine-parseable output where supported.

### Initialize

```bash
# Zero-to-value initialization
npx @smartergpt/lex init --yes
# Auto-detects project type (Node.js, Python, Rust, Go, etc.)
# Creates:
#   .smartergpt/ - Workspace with prompts, policy, and instructions
#   .github/copilot-instructions.md - IDE instructions with LEX markers
#   .cursorrules - Cursor IDE instructions (if Cursor detected)
#   lex.yaml - Configuration with sensible defaults
#   .smartergpt/lex/memory.db - SQLite database (initialized on first use)
# Shows MCP server configuration guidance
# Idempotent: safe to run multiple times

# Interactive mode (prompts for first Frame)
lex init --interactive

# Generate seed policy from directory structure
lex init --policy
# Scans src/ for TypeScript/JavaScript modules
# Generates .smartergpt/lex/lexmap.policy.json with discovered modules
# Example: src/memory/store/ -> memory/store module with src/memory/store/** match pattern

# Force reinitialize (overwrite existing files)
lex init --force
```

During init, Lex detects common project types, creates IDE instruction files with LEX markers, writes `lex.yaml`, initializes `.smartergpt/lex/memory.db`, and prints MCP server configuration guidance.

### Capture the first useful Frame

```bash
lex remember \
  --reference-point "Refactoring payment processing" \
  --summary "Extracted validation logic to PaymentValidator" \
  --next "Add unit tests for edge cases" \
  --modules "services/payment"
```

### Recall it later

```bash
lex recall "payment"
# Shows your context, blockers, and architectural neighborhood.
```

[Full Quick Start Guide](./QUICK_START.md)

### MCP setup

Use Lex with any MCP-compatible AI assistant, including VS Code and Claude Desktop:

```bash
# Install the MCP wrapper
npm install -g @smartergpt/lex-mcp

# Or run directly
npx @smartergpt/lex-mcp
```

VS Code configuration (`.vscode/mcp.json`):

```json
{
  "servers": {
    "lex": {
      "command": "npx",
      "args": ["@smartergpt/lex-mcp"],
      "env": {
        "LEX_WORKSPACE_ROOT": "${workspaceFolder}"
      }
    }
  }
}
```

Claude Desktop configuration:

```json
{
  "mcpServers": {
    "lex": {
      "command": "npx",
      "args": ["@smartergpt/lex-mcp"]
    }
  }
}
```

[MCP Server Documentation](./README.mcp.md)

---

## Agent Integration

Lex is designed to be consumed by agents and tools, not only read by humans.

- CLI: `lex remember`, `lex recall`, `lex check`, `lex timeline`, `lex instructions`, and database maintenance commands are scriptable entry points.
- MCP: `@smartergpt/lex-mcp` exposes Lex through Model Context Protocol for assistants that support MCP.
- Structured JSON: supported commands can emit machine-parseable output for orchestration and recovery.
- Recoverable errors: AXError includes `code`, `message`, `context`, and `nextActions[]` fields.
- Stable tool names: MCP tools have explicit names rather than relying on prose prompts.

The MCP server exposes 14 tools for episodic memory, policy validation, and architectural analysis:

- `frame_create`, `frame_search`, `frame_get`, `frame_list`, `frame_validate`
- `policy_check`, `timeline_show`, `atlas_analyze`
- `system_introspect`, `help`, `hints_get`
- `contradictions_scan`, `db_stats`, `turncost_calculate`

MCP is an adapter surface. Lex itself is the memory and policy core.

---

## Where agents use Lex

- Before editing: recall prior work, blockers, and relevant module boundaries.
- During handoff: store the current branch, next action, and unresolved constraints.
- During review: check policy facts against repository boundaries.
- During onboarding: inspect focused Atlas context instead of asking for a full codebase tour.
- During orchestration: emit structured output for runners and other tools.

Dogfooding examples are available in [examples/dogfood/](./examples/dogfood/). They show real Frames from building Lex with Lex.

---

## Human/operator view

Humans see a local, inspectable record instead of an opaque assistant memory:

- Frames are stored in SQLite at `.smartergpt/lex/memory.db` by default.
- Policy files live in the repository and can be reviewed in code review.
- NDJSON logs are written to `.smartergpt/lex/logs/lex.log.ndjson` with structured fields such as `timestamp`, `level`, `operation`, `duration_ms`, `metadata`, and `error`.
- Policy checks can run in CI with `lex check merged-facts.json`.
- Database maintenance commands support backups, rotation, and vacuuming.

```bash
# Create a timestamped backup (memory-20251123.sqlite)
lex db backup --rotate 7
# Keeps last 7 backups, stored in .smartergpt/lex/backups/

# Optimize database (rebuild and compact)
lex db vacuum

# Set backup retention via environment variable
export LEX_BACKUP_RETENTION=14  # Keep 14 most recent backups
```

Logs rotate automatically at 100MB and are silent in test mode unless `LEX_LOG_NDJSON=1` is set.

---

## Lex is not

- Lex is not a cloud memory service.
- Lex is not a chatbot.
- Lex is not a replacement for tests, code review, or CI.
- Lex is not an MCP-only project.
- Lex is not AXF, LexRunner, or LexSona.

---

## Relationship to AXF, LexRunner, and LexSona

Lex is the memory and policy core.

- Lex remembers and explains project context through Frames, recall, Atlas, policy, instructions, and structured output.
- AXF is the inspectable capability/control-plane layer for agent-operable tooling: manifests, routing, execution surfaces, scaffolding, and lifecycle gates.
- LexRunner composes work over capabilities and runpaths, including parallel PR workflows and merge planning.
- LexSona consumes the public behavioral memory socket (`@smartergpt/lex/lexsona`) for persona and guardrail integration. Lex core remains persona-agnostic.

A useful mental model: Lex remembers and explains context; AXF exposes bounded capabilities; LexRunner coordinates work; LexSona derives behavioral constraints.

---

## Documentation

### Getting Started

- [Quick Start Guide](./QUICK_START.md) - Get up and running in 5 minutes
- [Installation and Setup](./docs/ADOPTION_GUIDE.md) - Detailed installation guide
- [Core Concepts](./docs/OVERVIEW.md) - Understanding Frames, Atlas, and Policy

### Guides

- [Frame Recall Guide](./docs/MIND_PALACE.md) - Using Frames for reference-point recall
- [Code Atlas Guide](./docs/atlas/README.md) - Spatial memory and architectural context
- [Policy Enforcement](./docs/API_USAGE.md) - Setting up architectural boundaries
- [Instructions Generation](./docs/INSTRUCTIONS.md) - Sync AI instructions across IDEs
- [CLI Reference](./docs/CLI_OUTPUT.md) - Command-line usage and output modes
- [MCP Server Documentation](./README.mcp.md) - Using Lex with Model Context Protocol
- [OAuth2/JWT Authentication](./docs/AUTH.md) - Multi-user authentication setup

### Security

- [Security Policy](./SECURITY.md) - Security posture and best practices
- [OAuth2/JWT Guide](./docs/AUTH.md) - Authentication and user isolation

### Advanced

- [Architecture](./docs/ARCHITECTURE.md) - System layers and module context
- [Architecture Loop](./docs/ARCHITECTURE_LOOP.md) - How Frames, Atlas, and Policy interact
- [API Reference](#api-reference) - TypeScript API documentation
- [Limitations](./docs/LIMITATIONS.md) - Known constraints and future work
- [FAQ](./docs/FAQ.md) - Common questions

### Development

- [Contributing Guide](./CONTRIBUTING.md) - How to contribute
- [Release Process](./RELEASE.md) - Versioning and publishing
- [ADRs](./docs/adr/) - Architectural decision records

---

## API Reference

Lex provides multiple entry points for agents, tools, and application code:

### Core API

```typescript
import { saveFrame, searchFrames, getDb, closeDb } from '@smartergpt/lex';

const db = getDb(); // Uses .smartergpt/lex/memory.db

await saveFrame(db, {
  referencePoint: 'authentication flow',
  summaryCaption: 'Added password validation',
  statusSnapshot: { nextAction: 'Wire up permission check' },
  moduleScope: ['services/auth', 'services/password'],
  branch: 'feature/auth',
  jira: 'AUTH-123'
});

const results = await searchFrames(db, { referencePoint: 'authentication' });
closeDb(db);
```

### Subpath exports

| Import | Purpose | Documentation |
|--------|---------|---------------|
| `@smartergpt/lex` | Core API + store operations | [API Usage](./docs/API_USAGE.md) |
| `@smartergpt/lex/cli` | Programmatic CLI access | [CLI Output](./docs/CLI_OUTPUT.md) |
| `@smartergpt/lex/cli-output` | CLI JSON utilities | [CLI Output](./docs/CLI_OUTPUT.md) |
| `@smartergpt/lex/store` | Direct database operations | [Store Contracts](./docs/STORE_CONTRACTS.md) |
| `@smartergpt/lex/types` | All shared types | [API Usage](./docs/API_USAGE.md) |
| `@smartergpt/lex/errors` | AXError schema and utilities (v2.0+) | [AX Contract](./docs/specs/AX-CONTRACT.md) |
| `@smartergpt/lex/policy` | Policy loading & validation | [API Usage](./docs/API_USAGE.md) |
| `@smartergpt/lex/atlas` | Atlas Frame generation | [Architecture](./docs/ARCHITECTURE.md) |
| `@smartergpt/lex/atlas/code-unit` | Code unit schemas | [Atlas](./docs/atlas/README.md) |
| `@smartergpt/lex/atlas/schemas` | Atlas schemas | [Atlas](./docs/atlas/README.md) |
| `@smartergpt/lex/aliases` | Module alias resolution | [Aliases](./src/shared/aliases/README.md) |
| `@smartergpt/lex/module-ids` | Module ID validation | [API Usage](./docs/API_USAGE.md) |
| `@smartergpt/lex/memory` | Frame payload validation | [API Usage](./docs/API_USAGE.md) |
| `@smartergpt/lex/logger` | NDJSON logging | [API Usage](./docs/API_USAGE.md) |
| `@smartergpt/lex/lexsona` | Behavioral memory socket (v2.0+) | [Control Stack](./docs/control-stack/index.md) |
| `@smartergpt/lex/prompts` | Template system | [Canon Architecture](./docs/CANON_ARCHITECTURE.md) |

[Full API Documentation](./docs/API_USAGE.md)

---

## Project status

**Current Version:** `2.7.1` ([Changelog](./CHANGELOG.md))

Current Lex releases include structured output, recoverable errors, and Frame Schema v3 for agent and orchestrator integration.

Commonly used for:

- Personal projects and local dev tools
- Private MCP servers
- CI/CD policy enforcement
- LexRunner and other orchestrator integrations
- Documented multi-user authentication and encrypted database setup paths for deployments that need them

Current capability highlights:

- Structured output contract (v0.1): machine-parseable output, recoverable errors, and recall-focused events ([AX Contract](./docs/specs/AX-CONTRACT.md))
- Frame Schema v3: runner fields such as `runId`, `planHash

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Guffawaffle](https://github.com/Guffawaffle)
- **Source:** [Guffawaffle/lex](https://github.com/Guffawaffle/lex)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v2.1.2 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **2.1.2** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-guffawaffle-lex
- Seller: https://agentstack.voostack.com/s/guffawaffle
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.