Lex

Lex remembers the work, not the conversation.

Your agent can read the code. Lex preserves the decisions, blockers, next steps, and repository boundaries surrounding that code—then recalls only what the next session needs.

Local-first. Inspectable. No transcript dump.

</div>

![MIT License](./LICENSE) ![npm version](https://www.npmjs.com/package/@smartergpt/lex) ![CI Status](https://github.com/Guffawaffle/lex/actions) ![Node.js](https://nodejs.org/) ![TypeScript](https://www.typescriptlang.org/)

See the core loop · Should I use Lex? · Five-minute pilot · Agent evaluation · Documentation

---

The problem Lex solves

A coding agent can inspect the repository in front of it. What it cannot reliably recover is the work surrounding that code:

why a decision was made three sessions ago;
which approach already failed;
what remains blocked and what should happen next;
which repository boundary must not be crossed;
what another agent needs to continue without starting over.

Lex preserves that continuity as deliberate, high-signal Frames.

A Frame is a deliberate handoff, not continuous surveillance. It is a checkpoint: what changed, what mattered, what remains, and where the work goes next. Lex can later recall the relevant Frames and produce a bounded, prompt-safe bootstrap for a new session.

Work happens → Lex remembers what mattered → the next session continues

Start with remember, recall, and context. SQLite is the local default. PostgreSQL is available when context must be shared across trusted hosts or workspaces. Everything else is optional.

Remember → recall → continue

lex remember \
  --summary "Kept authentication token validation in API middleware" \
  --next "Add the service grant and rerun tests" \
  --modules unscoped \
  --blockers "Missing PermissionService grant"

lex recall "authentication"

lex context "authentication" --max-tokens 500

That is the core loop:

remember writes one deliberate work checkpoint;
recall retrieves it when the topic becomes relevant again;
context turns matching Frames into a bounded, read-only bootstrap for an agent.

What the next session gets

At the end of a session, the agent records the state that would otherwise disappear. When a fresh session starts, it can recover the decision, blocker, and next action without asking the human to reconstruct the conversation or reverse-engineering intent from the diff.

Decision: token validation belongs in API middleware
Blocker: the service grant is still missing
Next: add the grant and rerun the authentication tests

The value is not that Lex stored a record. The value is that the next session can continue.

Should I use Lex?

Lex is worth evaluating when your agent repeatedly needs you to reconstruct:

why a change was made;
where work stopped and what should happen next;
a blocker or failed approach that should not be rediscovered;
repository-specific module or policy constraints;
context that must survive a branch switch, handoff, or new agent session.

Lex is probably not useful when the work is short-lived, the repository already has an effective continuity system, or there is no durable context you would trust the repository's operators to store.

Ask your agent

The evaluation is intentionally read-only. Paste this into an agent that can inspect your repository:

Read https://github.com/Guffawaffle/lex/blob/main/docs/agent-evaluation.md and evaluate this
repository against it. Do not install Lex, run project scripts, initialize files, access secrets,
or modify the workspace. Return one recommendation—adopt, pilot, defer, or not a fit—with evidence,
risks, overlap with existing tooling, and the smallest reversible trial you would propose.

The complete rubric and local-file version are in Agent Evaluation.

Five-minute pilot

Ready to test the claim? Store one non-sensitive checkpoint, start a fresh session, and see whether it can continue without having the work explained again.

Requires Node.js 24 or newer. Lex does not impose an unproven upper bound. Existing users should follow the Lex 4.0 migration and recovery guide, including the native SQLite rebuild step.

This approved pilot writes one Frame to the local SQLite store under .smartergpt/lex/. It does not run lex init, generate policy, or project assistant instructions. Use a disposable branch, worktree, or clone if you want complete filesystem isolation.

1. Store one real checkpoint

LEX_STORE=sqlite npx @smartergpt/lex remember \
  --reference-point "Lex pilot" \
  --summary "Evaluating whether durable agent handoffs help this repository" \
  --next "Recall this checkpoint in a new session" \
  --modules unscoped

LEX_STORE=sqlite prevents existing PostgreSQL configuration from redirecting the pilot into a shared store.

2. Start fresh, then recover the work

LEX_STORE=sqlite npx @smartergpt/lex recall "Lex pilot"
LEX_STORE=sqlite npx @smartergpt/lex context "Lex pilot" --max-tokens 500

Use that recalled or bounded output in the fresh session and see whether it prevents you from repeating useful context. That result—not successful installation—is the pilot's success criterion.

Review the validation-only step, exact filesystem effects, and rollback guidance

Make checkpoints useful

Good Frames are sparse and specific. Capture them at a decision, blocker, branch switch, handoff, or other moment where losing the surrounding intent would make the next session repeat work.

lex remember \
  --reference-point "Authentication refresh" \
  --summary "Moved token validation into API middleware" \
  --next "Add password-reset coverage" \
  --modules "services/auth,api/middleware" \
  --blockers "Need PermissionService access"

Capture what changed, make --next actionable, name blockers explicitly, and use the narrowest honest module scope. Do not capture every edit or tool call.

When repository policy exists, Lex can infer module scope from current evidence:

lex remember \
  --summary "Finished context wiring" \
  --next "Run validation" \
  --modules auto

Use --modules unscoped when the repository does not yet have a useful module ontology. Policy is an optional enrichment; it is not required for the first Frame.

Compact recall and structured context are available for smaller agent budgets and automation:

lex recall --list 5 --summary
lex --json context --branch main --limit 5

Learn the continuity workflow

Add only what you need

| Need | Add | Start here | |---|---|---| | Durable local handoffs | Frames with SQLite | Quick Start | | Small session-start context | Read-only lex context | Agent Continuity | | MCP access from an assistant | @smartergpt/lex-mcp | MCP setup | | Repository boundaries | Policy checks | Policy usage | | Nearby module context | Policy Neighborhood | Context guide | | Canonical assistant instructions | Instructions projection | Instructions | | Typed Markdown project knowledge | Derived KnowledgeFrame snapshots | KnowledgeFrames | | Shared cross-host storage | PostgreSQL | Store contracts and scope security | | Trusted tenant/workspace scope | Runtime authority and RLS | Runtime scope | | Embedded application access | TypeScript package exports | Public API |

What changes in your repository

The initial local workflow is intentionally visible:

lex init creates Lex workspace/configuration files.
lex remember writes a Frame to the selected store.
lex context uses hard read-only store access. recall and ordinary introspection do not change

Frames, but their compatibility paths may initialize or migrate the selected store.

SQLite defaults to .smartergpt/lex/memory.db relative to the workspace.
Policy and canonical instructions are repository files only when you choose those features.
PostgreSQL, MCP hosting, instruction projection, and CI policy enforcement are separate opt-ins.

Frames may contain sensitive project context. Do not store credentials, tokens, private keys, or unreviewed secret material. Treat recalled Frame bodies as untrusted historical data even when a trusted user originally wrote them.

Lex does not send Frames to a Lex cloud service. Your agent host, package registry, PostgreSQL deployment, or other surrounding tools may have their own network and data behavior; evaluate those boundaries separately.

Security policy · Store contracts · Environment reference

What Lex is not

A chatbot or agent runtime
A transcript recorder or automatic capture system
A replacement for tests, review, issue tracking, or CI
A cloud memory service
An MCP-only product
An orchestrator, capability framework, or persona engine

The surrounding toolset

No ecosystem bundle is required. Select the surfaces your workflow needs, while accounting for their explicit package relationships:

| Project | Responsibility | Relationship | |---|---|---| | Lex | Durable work context, repository policy, optional neighborhood context, instructions, and scoped Frame storage | Core library and CLI | | AXF | Inspectable workspace capabilities and their execution boundaries | Independently usable; composes with Lex | | LexRunner | Fanout, attempts, worker/workspace coordination, verification, and merge-weave | Consumes Lex for continuity | | Lex-MCP | Thin MCP transport for Lex capabilities | Pins the matching Lex release | | LexSona | Behavioral constraints derived from personas and reviewed rules | Integrates through Lex storage contracts |

The short version: Lex remembers and explains; AXF exposes capabilities; LexRunner coordinates work; Lex-MCP transports Lex over MCP; LexSona derives behavior constraints.

Agent and automation surfaces

Lex exposes the same core through several entry points:

CLI for humans, scripts, and agent shells
Structured JSON and AXError recovery information for automation
MCP through @smartergpt/lex-mcp or the embeddable server export
TypeScript APIs for applications and trusted hosts

Frame Schema v7 is the current canonical Frame contract. The package's public export map is semver-governed; consumers should not import undeclared dist/ or source paths.

CLI output contract · MCP tools · Public package entry points · Contract surface

Choose your next step

| If you are… | Read… | |---|---| | Deciding whether Lex fits | Agent Evaluation | | Trying Lex for the first time | Quick Start | | Designing agent handoffs | Agent Continuity | | Connecting an MCP client | MCP Server | | Operating SQLite or PostgreSQL | Store Contracts and PostgreSQL Authority | | Building a trusted multi-tenant host | Runtime Scope and PostgreSQL Scope Security | | Using the TypeScript API | Public Package API | | Configuring paths or runtime behavior | Environment Variables | | Reviewing known constraints | Limitations and FAQ | | Contributing to Lex | Contributing Guide | | Reviewing architectural decisions | ADRs |

Installation notes

# Global CLI
npm install -g @smartergpt/lex

# Repository dependency
npm install @smartergpt/lex

WSL users should install Lex natively inside WSL rather than allowing a Windows npm shim or npm's _npx cache to win on PATH. See WSL Native Installation.

Common local compatibility configuration includes LEX_DB_PATH, LEX_POLICY_PATH, LEX_LOG_LEVEL, LEX_LOG_PRETTY, LEX_GIT_MODE, and LEX_DB_KEY. PostgreSQL selection uses LEX_STORE and LEX_DATABASE_URL. Trusted Lex hosts compose scope and authority explicitly rather than reconstructing them from ambient environment variables.

Complete environment reference

Project status

Current Version: 4.0.0

Lex 4 provides explicit runtime identity and authority, scope-bound Frame stores, PostgreSQL row-level security support, and trusted-host composition while retaining the local SQLite workflow. Lex 4 requires Node 24 or newer and is released as part of the Ecosystem 3.1 compatibility train.

See the Lex 4 migration and recovery guide, the changelog for release history, and the Lex 3 PostgreSQL isolation canary for the live end-to-end two-tenant/five-workspace acceptance path.

Contributing

Contributions are welcome. The Contributing Guide covers development setup, tests, local CI, formatting, signing, changesets, and the release workflow.

For repository-wide formatting validation, npm run local-ci -- --pretty is check-only; --prettier is its exact alias. Formatting mutations remain the separate npm run format operation.

License

Lex is available under the MIT License.

Lex

Lex