agentleFS
Sign inStart free
facebookfacebook/memlab/AGENTS.md

memlab

AGENTS.md5.1k starsChanged 19 months agoMITView on GitHub

Instructions for AI coding agents working on the memlab source code. To use memlab rather than change it (write a leak test scenario, analyze a heap snapshot, set up the MCP server), read AI.md and the Agent Skills under plugins/memlab/skills/ instead. memlab is an npm workspaces monorepo. Each package under packages/ is published to npm separately: Each package depends only on packages earlier in this order: core, lens, e2e, heap-analysis, api, cli, memlab. mcp-server depends only on core and heap-analysis.…

  • Installs packages

We split this AGENTS.md into the rules it gives an agent

4 rules. About 0 are common, 2 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use Node.js 18 or later (@memlab/mcp-server requires it).

    line 34
  2. Distinctive:

    Every source file starts with the MIT license header.

    line 55
  3. Very specific:

    If you change a public API or CLI option, update README.md, AI.md and the affected package README in the same change.

    line 63
  4. Distinctive:

    When a CLI flag, API or MCP tool changes, update the skills that mention it.

    line 96

≈ “Common” is an estimate: at least 1 in 5 of the 36,368 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

Instructions for AI coding agents working on the memlab source code.

To use memlab rather than change it (write a leak test scenario, analyze a heap snapshot, set up the MCP server), read AI.md and the Agent Skills under plugins/memlab/skills/ instead.

Repository layout

memlab is an npm workspaces monorepo. Each package under packages/ is published to npm separately:

Directorynpm packageWhat it contains
packages/core@memlab/coreHeap snapshot parser, the IHeapSnapshot/IHeapNode/IHeapEdge API, leak trace clustering, config
packages/e2e@memlab/e2eBrowser automation with Puppeteer: runs test scenarios and takes heap snapshots
packages/heap-analysis@memlab/heap-analysisBuilt-in analyses behind memlab analyze <plugin>
packages/api@memlab/apiProgrammatic API: run, takeSnapshots, findLeaks, analyze
packages/cli@memlab/cliThe memlab command line commands
packages/memlabmemlabUmbrella package that installs the memlab CLI
packages/lens@memlab/lensIn-browser overlay that highlights detached DOM and unmounted React components (webpack bundle)
packages/mcp-server@memlab/mcp-serverMCP server for AI assistants, plus the memlab-cli command

Each package depends only on packages earlier in this order: core, lens, e2e, heap-analysis, api, cli, memlab. mcp-server depends only on core and heap-analysis. Don't add an import that goes the other way.

website/ is the Docusaurus site published at https://meta.github.io/memlab. docs/ is a symlink to website/docs/.

Build, test, run

Use Node.js 18 or later (@memlab/mcp-server requires it).

npm install
npm run build              # compiles every package to packages/*/dist
npm test                   # runs each package's tests
npm run memlab -- help     # run the CLI built from this checkout
  • Build before you test. Jest runs the compiled tests in packages/*/dist/**/__tests__/, not the TypeScript sources, so a test run without a fresh build tests old code.
  • To work on one package: npm run build-pkg -w packages/core, then npm run test-pkg -w packages/core.
  • npm run dev runs tsc -b -w for incremental rebuilds.
  • Website: cd website && yarn install && yarn start serves it locally; yarn build is what the GitHub Pages deploy runs.

Conventions

  • TypeScript in strict mode. Put tests next to the code in src/**/__tests__/*.test.ts.
  • Every source file starts with the MIT license header; copy it from an existing file in the same package.
  • Public APIs are documented with TSDoc comments. The pages under website/docs/api/ are generated from those comments; change the comment, not the generated markdown.
  • website/docs/cli/CLI-commands.md is generated from the CLI command definitions in packages/cli/src/commands/; change the command, not the markdown.
  • If you change a public API or CLI option, update README.md, AI.md and the affected package README in the same change.

MCP server (packages/mcp-server)

  • A tool lives in its own file under src/tools/ and is registered with the server by a register...(server) call in src/index.ts. Also list it in a group in src/tools/tools-index.ts, the catalog that memlab_tools serves. The tool tables in packages/mcp-server/README.md are generated from that catalog: run npm run sync-catalog in the package after adding or renaming a tool.
  • npm run test-pkg in the package checks that every tool is in the index, that no tool description asks for a parameter its schema lacks, that the README tables are current, and that src/server-version.ts matches package.json.
  • A tool that runs caller-supplied JavaScript goes in RUNS_CODE in src/tool-annotations.ts, which sets its MCP annotations and hides it under MEMLAB_DISABLE_CODE_TOOLS=1. Also list it in the README under "Tools that execute JavaScript".
  • .mcp.json runs the server from this checkout (packages/mcp-server/bin/memlab-mcp.js), so build first.

Agent Skills and the Claude Code plugin (plugins/memlab)

  • Each skill is a directory under plugins/memlab/skills/ with a SKILL.md that follows the Agent Skills specification: name matches the directory, description says what the skill does and when to use it (at most 1024 characters), and the body stays under 500 lines. Skills are copied out of the repo when installed, so link only to files inside the skill directory or to absolute URLs.
  • skills/memlab-analyze-heap-snapshot/references/investigation-paths.md repeats the investigation paths in packages/mcp-server/MCP_SKILL.md. Update both together.
  • When a CLI flag, API or MCP tool changes, update the skills that mention it.
  • Validate with claude plugin validate plugins/memlab, claude plugin validate --strict plugins/memlab/skills and claude plugin validate . (the marketplace in .claude-plugin/).

Pull requests

See CONTRIBUTING.md. Make sure the build and tests pass, and update the documentation when you change behavior.

Download now (ZIP)

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 28,693 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free