{
  "markdown": "<div align=\"center\">\n\n# Lex\n\n## Lex remembers the work, not the conversation.\n\nYour agent can read the code. Lex preserves the decisions, blockers, next steps, and repository\nboundaries surrounding that code—then recalls only what the next session needs.\n\n**Local-first. Inspectable. No transcript dump.**\n\n</div>\n\n[![MIT License](https://img.shields.io/badge/License-MIT-green)](./LICENSE)\n[![npm version](https://img.shields.io/npm/v/@smartergpt/lex)](https://www.npmjs.com/package/@smartergpt/lex)\n[![CI Status](https://img.shields.io/badge/CI-passing-success)](https://github.com/Guffawaffle/lex/actions)\n[![Node.js](https://img.shields.io/badge/Node.js-24%2B-339933)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-6-3178C6)](https://www.typescriptlang.org/)\n\n[See the core loop](#remember--recall--continue) · [Should I use Lex?](#should-i-use-lex) · [Five-minute pilot](#five-minute-pilot) · [Agent evaluation](./docs/agent-evaluation.md) · [Documentation](#choose-your-next-step)\n\n---\n\n## The problem Lex solves\n\nA coding agent can inspect the repository in front of it. What it cannot reliably recover is the\nwork surrounding that code:\n\n- why a decision was made three sessions ago;\n- which approach already failed;\n- what remains blocked and what should happen next;\n- which repository boundary must not be crossed;\n- what another agent needs to continue without starting over.\n\nLex preserves that continuity as deliberate, high-signal **Frames**.\n\nA Frame is a deliberate handoff, not continuous surveillance. It is a checkpoint: what changed,\nwhat mattered, what remains, and where the work goes next. Lex can later recall the relevant\nFrames and produce a bounded, prompt-safe bootstrap for a new session.\n\n```text\nWork happens → Lex remembers what mattered → the next session continues\n```\n\nStart with `remember`, `recall`, and `context`. SQLite is the local default. PostgreSQL is\navailable when context must be shared across trusted hosts or workspaces. Everything else is\noptional.\n\n## Remember → recall → continue\n\n```bash\nlex remember \\\n  --summary \"Kept authentication token validation in API middleware\" \\\n  --next \"Add the service grant and rerun tests\" \\\n  --modules unscoped \\\n  --blockers \"Missing PermissionService grant\"\n\nlex recall \"authentication\"\n\nlex context \"authentication\" --max-tokens 500\n```\n\nThat is the core loop:\n\n- `remember` writes one deliberate work checkpoint;\n- `recall` retrieves it when the topic becomes relevant again;\n- `context` turns matching Frames into a bounded, read-only bootstrap for an agent.\n\n### What the next session gets\n\nAt the end of a session, the agent records the state that would otherwise disappear. When a fresh\nsession starts, it can recover the decision, blocker, and next action without asking the human to\nreconstruct the conversation or reverse-engineering intent from the diff.\n\n```text\nDecision: token validation belongs in API middleware\nBlocker: the service grant is still missing\nNext: add the grant and rerun the authentication tests\n```\n\nThe value is not that Lex stored a record. The value is that the next session can continue.\n\n## Should I use Lex?\n\nLex is worth evaluating when your agent repeatedly needs you to reconstruct:\n\n- why a change was made;\n- where work stopped and what should happen next;\n- a blocker or failed approach that should not be rediscovered;\n- repository-specific module or policy constraints;\n- context that must survive a branch switch, handoff, or new agent session.\n\nLex is probably not useful when the work is short-lived, the repository already has an effective\ncontinuity system, or there is no durable context you would trust the repository's operators to\nstore.\n\n### Ask your agent\n\nThe evaluation is intentionally read-only. Paste this into an agent that can inspect your\nrepository:\n\n```text\nRead https://github.com/Guffawaffle/lex/blob/main/docs/agent-evaluation.md and evaluate this\nrepository against it. Do not install Lex, run project scripts, initialize files, access secrets,\nor modify the workspace. Return one recommendation—adopt, pilot, defer, or not a fit—with evidence,\nrisks, overlap with existing tooling, and the smallest reversible trial you would propose.\n```\n\nThe complete rubric and local-file version are in\n[Agent Evaluation](./docs/agent-evaluation.md).\n\n## Five-minute pilot\n\nReady to test the claim? Store one non-sensitive checkpoint, start a fresh session, and see whether\nit can continue without having the work explained again.\n\nRequires Node.js 24 or newer. Lex does not impose an unproven upper bound. Existing users should\nfollow the [Lex 4.2 migration and recovery guide](docs/releases/lex-4.2-migration.md), including the\nnative SQLite rebuild step.\n\nThis approved pilot writes one Frame to the local SQLite store under `.smartergpt/lex/`. It does\nnot run `lex init`, generate policy, or project assistant instructions. Use a disposable branch,\nworktree, or clone if you want complete filesystem isolation.\n\n### 1. Store one real checkpoint\n\n```bash\nLEX_STORE=sqlite npx @smartergpt/lex remember \\\n  --reference-point \"Lex pilot\" \\\n  --summary \"Evaluating whether durable agent handoffs help this repository\" \\\n  --next \"Recall this checkpoint in a new session\" \\\n  --modules unscoped\n```\n\n`LEX_STORE=sqlite` prevents existing PostgreSQL configuration from redirecting the pilot into a\nshared store.\n\n### 2. Start fresh, then recover the work\n\n```bash\nLEX_STORE=sqlite npx @smartergpt/lex recall \"Lex pilot\"\nLEX_STORE=sqlite npx @smartergpt/lex context \"Lex pilot\" --max-tokens 500\n```\n\nUse that recalled or bounded output in the fresh session and see whether it prevents you from\nrepeating useful context. That result—not successful installation—is the pilot's success\ncriterion.\n\n[Review the validation-only step, exact filesystem effects, and rollback guidance](./QUICK_START.md)\n\n## Make checkpoints useful\n\nGood Frames are sparse and specific. Capture them at a decision, blocker, branch switch, handoff,\nor other moment where losing the surrounding intent would make the next session repeat work.\n\n```bash\nlex remember \\\n  --reference-point \"Authentication refresh\" \\\n  --summary \"Moved token validation into API middleware\" \\\n  --next \"Add password-reset coverage\" \\\n  --modules \"services/auth,api/middleware\" \\\n  --blockers \"Need PermissionService access\"\n```\n\nCapture what changed, make `--next` actionable, name blockers explicitly, and use the narrowest\nhonest module scope. Do not capture every edit or tool call.\n\nWhen repository policy exists, Lex can infer module scope from current evidence:\n\n```bash\nlex remember \\\n  --summary \"Finished context wiring\" \\\n  --next \"Run validation\" \\\n  --modules auto\n```\n\nUse `--modules unscoped` when the repository does not yet have a useful module ontology. Policy is\nan optional enrichment; it is not required for the first Frame.\n\nCompact recall and structured context are available for smaller agent budgets and automation:\n\n```bash\nlex recall --list 5 --summary\nlex --json context --branch main --limit 5\n```\n\n[Learn the continuity workflow](./docs/AGENT_CONTINUITY.md)\n\n## Add only what you need\n\n| Need | Add | Start here |\n|---|---|---|\n| Durable local handoffs | Frames with SQLite | [Quick Start](./QUICK_START.md) |\n| Small session-start context | Read-only `lex context` | [Agent Continuity](./docs/AGENT_CONTINUITY.md) |\n| MCP access from an assistant | `@smartergpt/lex-mcp` | [MCP setup](./README.mcp.md) |\n| Repository boundaries | Policy checks | [Policy usage](./docs/API_USAGE.md) |\n| Nearby module context | Policy Neighborhood | [Context guide](./docs/atlas/README.md) |\n| Canonical assistant instructions | Instructions projection | [Instructions](./docs/INSTRUCTIONS.md) |\n| Typed Markdown project knowledge | Derived KnowledgeFrame snapshots | [KnowledgeFrames](./docs/KNOWLEDGE_FRAMES.md) |\n| Shared cross-host storage | PostgreSQL | [Store contracts](./docs/STORE_CONTRACTS.md) and [scope security](./docs/POSTGRES_SCOPE_SECURITY.md) |\n| Trusted tenant/workspace scope | Runtime authority and RLS | [Runtime scope](./docs/RUNTIME_SCOPE_CONTRACT.md) |\n| Embedded application access | TypeScript package exports | [Public API](./docs/PUBLIC_API.md) |\n\n## What changes in your repository\n\nThe initial local workflow is intentionally visible:\n\n- `lex init` creates Lex workspace/configuration files.\n- `lex remember` writes a Frame to the selected store.\n- `lex context` uses hard read-only store access. `recall` and ordinary introspection do not change\n  Frames, but their compatibility paths may initialize or migrate the selected store.\n- SQLite defaults to `.smartergpt/lex/memory.db` relative to the workspace.\n- Policy and canonical instructions are repository files only when you choose those features.\n- PostgreSQL, MCP hosting, instruction projection, and CI policy enforcement are separate opt-ins.\n\nFrames may contain sensitive project context. Do not store credentials, tokens, private keys, or\nunreviewed secret material. Treat recalled Frame bodies as untrusted historical data even when a\ntrusted user originally wrote them.\n\nLex does not send Frames to a Lex cloud service. Your agent host, package registry, PostgreSQL\ndeployment, or other surrounding tools may have their own network and data behavior; evaluate\nthose boundaries separately.\n\n[Security policy](./SECURITY.md) · [Store contracts](./docs/STORE_CONTRACTS.md) · [Environment reference](./docs/ENVIRONMENT.md)\n\n## What Lex is not\n\n- A chatbot or agent runtime\n- A transcript recorder or automatic capture system\n- A replacement for tests, review, issue tracking, or CI\n- A cloud memory service\n- An MCP-only product\n- An orchestrator, capability framework, or persona engine\n\n## The surrounding toolset\n\nNo ecosystem bundle is required. Select the surfaces your workflow needs, while accounting for\ntheir explicit package relationships:\n\n| Project | Responsibility | Relationship |\n|---|---|---|\n| **Lex** | Durable work context, repository policy, optional neighborhood context, instructions, and scoped Frame storage | Core library and CLI |\n| [**AXF**](https://github.com/Guffawaffle/axf) | Inspectable workspace capabilities and their execution boundaries | Independently usable; composes with Lex |\n| [**LexRunner**](https://github.com/Guffawaffle/lexrunner) | Fanout, attempts, worker/workspace coordination, verification, and merge-weave | Consumes Lex for continuity |\n| [**Lex-MCP**](https://github.com/Guffawaffle/lex-mcp) | Thin MCP transport for Lex capabilities | Pins the matching Lex release |\n| [**LexSona**](https://github.com/Guffawaffle/lexsona) | Behavioral constraints derived from personas and reviewed rules | Integrates through Lex storage contracts |\n\nThe short version: Lex remembers and explains; AXF exposes capabilities; LexRunner coordinates\nwork; Lex-MCP transports Lex over MCP; LexSona derives behavior constraints.\n\n## Agent and automation surfaces\n\nLex exposes the same core through several entry points:\n\n- **CLI** for humans, scripts, and agent shells\n- **Structured JSON** and AXError recovery information for automation\n- **MCP** through `@smartergpt/lex-mcp` or the embeddable server export\n- **TypeScript APIs** for applications and trusted hosts\n\nFrame Schema v8 is the current canonical Frame contract. The package's public export map is\nsemver-governed; consumers should not import undeclared `dist/` or source paths.\n\n[CLI output contract](./docs/CLI_OUTPUT.md) · [MCP tools](./README.mcp.md) · [Public package entry points](./docs/PUBLIC_API.md) · [Contract surface](./docs/CONTRACT_SURFACE.md)\n\n## Choose your next step\n\n| If you are… | Read… |\n|---|---|\n| Deciding whether Lex fits | [Agent Evaluation](./docs/agent-evaluation.md) |\n| Trying Lex for the first time | [Quick Start](./QUICK_START.md) |\n| Designing agent handoffs | [Agent Continuity](./docs/AGENT_CONTINUITY.md) |\n| Connecting an MCP client | [MCP Server](./README.mcp.md) |\n| Operating SQLite or PostgreSQL | [Store Contracts](./docs/STORE_CONTRACTS.md) and [PostgreSQL Authority](./docs/POSTGRES_AUTHORITY.md) |\n| Building a trusted multi-tenant host | [Runtime Scope](./docs/RUNTIME_SCOPE_CONTRACT.md) and [PostgreSQL Scope Security](./docs/POSTGRES_SCOPE_SECURITY.md) |\n| Using the TypeScript API | [Public Package API](./docs/PUBLIC_API.md) |\n| Compiling typed normative declarations | [Normative Policy Compiler](./docs/normative-policy-compiler.md) |\n| Configuring paths or runtime behavior | [Environment Variables](./docs/ENVIRONMENT.md) |\n| Reviewing known constraints | [Limitations](./docs/LIMITATIONS.md) and [FAQ](./docs/FAQ.md) |\n| Contributing to Lex | [Contributing Guide](./CONTRIBUTING.md) |\n| Reviewing architectural decisions | [ADRs](./docs/adr/) |\n\n## Installation notes\n\n```bash\n# Global CLI\nnpm install -g @smartergpt/lex\n\n# Repository dependency\nnpm install @smartergpt/lex\n```\n\nWSL users should install Lex natively inside WSL rather than allowing a Windows npm shim or npm's\n`_npx` cache to win on `PATH`. See [WSL Native Installation](./docs/WSL_NATIVE_INSTALL.md).\n\nCommon local compatibility configuration includes `LEX_DB_PATH`, `LEX_POLICY_PATH`,\n`LEX_LOG_LEVEL`, `LEX_LOG_PRETTY`, `LEX_GIT_MODE`, and `LEX_DB_KEY`. PostgreSQL selection uses\n`LEX_STORE` and `LEX_DATABASE_URL`. Trusted Lex hosts compose scope and authority explicitly\nrather than reconstructing them from ambient environment variables.\n\n[Complete environment reference](./docs/ENVIRONMENT.md)\n\n## Project status\n\n**Current Version:** `4.2.0`\n\nLex 4.2 combines the library-only normative-policy compiler and resolver. See the\n[4.2 release notes](./docs/releases/lex-4.2.md) and\n[migration guide](./docs/releases/lex-4.2-migration.md). Candidate metadata is not\npublication evidence; retain verified 4.1.0 runtimes until the exact new pair is verified.\n\nLex 4 provides explicit runtime identity and authority, scope-bound Frame stores, PostgreSQL\nrow-level security support, and trusted-host composition while retaining the local SQLite\nworkflow. Lex 4 requires Node 24 or newer and is released as part of the\n[Ecosystem 3.1 compatibility train](./docs/releases/ecosystem-3.1.md).\n\nSee the [Lex 4 migration and recovery guide](./docs/releases/lex-4.2-migration.md), the\n[changelog](./CHANGELOG.md) for release history, and the\n[Lex 3 PostgreSQL isolation canary](./docs/LEX3_POSTGRES_DOGFOOD.md) for the live end-to-end\ntwo-tenant/five-workspace acceptance path.\n\n## Contributing\n\nContributions are welcome. The [Contributing Guide](./CONTRIBUTING.md) covers development setup,\ntests, local CI, formatting, signing, changesets, and the release workflow.\n\nFor repository-wide formatting validation, `npm run local-ci -- --pretty` is check-only;\n`--prettier` is its exact alias. Formatting mutations remain the separate `npm run format`\noperation.\n\n## License\n\nLex is available under the [MIT License](./LICENSE).\n",
  "bytes": 14863,
  "sha": "6d3732632fffe55d1528aa3e96ede51db59a54dbc9c762145271628adc207c54",
  "repo_slug": "guffawaffle/lex",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_guffawaffle_lex_c6f37e34/readme"
}