Lex

Install

Config snippet generator goes here (5 client tabs)

README

<div align="center">

# Lex

### **Episodic Memory & Architectural Policy for AI Agents**

[![MIT License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)
[![npm version](https://img.shields.io/npm/v/@smartergpt/lex)](https://www.npmjs.com/package/@smartergpt/lex)
[![CI Status](https://img.shields.io/badge/CI-passing-success)](https://github.com/Guffawaffle/lex/actions)
[![Node.js](https://img.shields.io/badge/Node.js-20+-339933)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-3178C6)](https://www.typescriptlang.org/)

**Stop losing context. Start building agents that remember.**

[Quick Start](#-quick-start) · [Documentation](#-documentation) · [Examples](./examples/) · [API Reference](#-api-reference) · [Contributing](./CONTRIBUTING.md)

</div>

---

## 📖 What is Lex?

**Lex** is a TypeScript framework that gives AI agents **episodic memory** and **architectural awareness**. It solves the fundamental problem of context loss in long-running development workflows.

### The Problem

You're working with an AI coding assistant on a complex feature. You stop for the day. When you return:
- The assistant has no memory of what you were doing
- It can't recall why you made certain architectural decisions
- It doesn't know which modules are safe to modify
- You spend 30 minutes re-explaining context every session

### The Solution

Lex provides three capabilities:

1. **📸 Episodic Memory (Frames)** — Capture work snapshots with context, blockers, and next actions
2. **🗺️ Spatial Memory (Atlas)** — Navigate module dependencies without overwhelming token budgets
3. **🛡️ Architectural Policy** — Enforce boundaries, permissions, and deprecation patterns in CI

**Result:** Your AI assistant recalls exactly where you left off, understands your architecture, and respects your constraints.

---

## 🎯 Core Capabilities

### 🧠 Frames: Work Session Memory

Capture meaningful moments in your 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"
```

Later, instantly recall:

```bash
lex recall "authentication"
# Returns: Your exact context, blockers, next action, and relevant module neighborhood
```

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

### 🗺️ Atlas Frames: Architectural Context

When you recall a Frame, Lex doesn't dump your entire codebase into context. Instead, it provides an **Atlas Frame**: the modules you touched plus their immediate neighborhood (dependencies, dependents, permissions).

This "fold radius" approach gives AI assistants exactly the architectural context they need—nothing more, nothing less.

**Token efficiency:** 10-module project → ~500 tokens (not 50,000)

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

### 🛡️ Policy Enforcement

Define architectural 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 Generation

Maintain a single source of truth for AI assistant guidance:

```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
```

**Benefits:**
- Single source → Multiple hosts (Copilot, Cursor, etc.)
- Safe updates via marker system (human content preserved)
- Deterministic output (same input = same output)

[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+** (tested through Node.js 22, see `.nvmrc`)

**Lex 2.0.0 is AX-native** with structured output (`--json`), recoverable errors (AXError), and Frame Schema v3 for orchestrator integration. All commands provide both human-readable and machine-parseable output.

### Initialize

```bash
# Zero-to-value initialization (new in v2.1.0!)
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