Lex

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:

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:

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:

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:

{
  "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:

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:

# 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

# 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/WSLNATIVEINSTALL.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

# 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

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

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:

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

# Or run directly
npx @smartergpt/lex-mcp

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

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

Claude Desktop configuration:

{
  "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.

# 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

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/APIUSAGE.md) | | @smartergpt/lex/cli | Programmatic CLI access | [CLI Output](./docs/CLIOUTPUT.md) | | @smartergpt/lex/cli-output | CLI JSON utilities | [CLI Output](./docs/CLIOUTPUT.md) | | @smartergpt/lex/store | Direct database operations | [Store Contracts](./docs/STORECONTRACTS.md) | | @smartergpt/lex/types | All shared types | [API Usage](./docs/APIUSAGE.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/APIUSAGE.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/APIUSAGE.md) | | @smartergpt/lex/memory | Frame payload validation | [API Usage](./docs/APIUSAGE.md) | | @smartergpt/lex/logger | NDJSON logging | [API Usage](./docs/APIUSAGE.md) | | @smartergpt/lex/lexsona | Behavioral memory socket (v2.0+) | [Control Stack](./docs/control-stack/index.md) | | @smartergpt/lex/prompts | Template system | [Canon Architecture](./docs/CANONARCHITECTURE.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
• Source: Guffawaffle/lex
• License: MIT

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