${baseMsg} Tree exceeds the server's --max-files limit of ${

Error message

${baseMsg} Tree exceeds the server's --max-files limit of ${upper}; batch by subdirectory (run import-jsonl once per project under ~/.claude/projects).

What it means

Post-import warning when the JSONL import hit the file-scan cap AND the tree itself exceeds the server's hard --max-files limit (or the walker reported it was capped). The CLI explains that raising --max-files alone cannot help and recommends batching imports per subdirectory.

Source

Thrown at src/cli.ts:3803

      process.exit(1);
    }
    spinner.stop(
      `imported ${json.imported ?? 0} file(s), ${json.observations ?? 0} observation(s) across ${json.sessionIds?.length || 0} session(s)`,
    );
    if (json.truncated) {
      const cap = json.maxFiles ?? 200;
      const upper = json.maxFilesUpperBound ?? 1000;
      const discovered = json.discovered ?? 0;
      const skipped = discovered - (json.imported ?? 0);
      const discoveredLabel = json.traversalCapped
        ? `${discovered}+ (traversal halted at safety cap)`
        : String(discovered);
      const baseMsg = `Hit the ${cap}-file scan cap; ${skipped} of ${discoveredLabel} discovered file(s) were skipped.`;
      // If we already saw more than the server's hard cap (or the
      // walker stopped early), bumping --max-files won't help on its
      // own — recommend batching by subdirectory.
      if (discovered > upper || json.traversalCapped) {
        p.log.warn(
          `${baseMsg} Tree exceeds the server's --max-files limit of ${upper}; ` +
            `batch by subdirectory (run import-jsonl once per project under ~/.claude/projects).`,
        );
      } else {
        const suggested = Math.min(
          Math.max((discovered || cap) + 100, cap * 2),
          upper,
        );
        p.log.warn(
          `${baseMsg} Re-run with --max-files=${suggested} (max ${upper}) or batch by subdirectory.`,
        );
      }
    }
    if (json.sessionIds && json.sessionIds.length > 0) {
      p.log.info(`View at ${getViewerUrl()} → Replay tab`);
    }
  } catch (err) {
    spinner.stop("failed");

View on GitHub (pinned to e04ba88819)

Solutions

Run import-jsonl once per project directory under ~/.claude/projects instead of the whole tree
Restart the server with a higher --max-files if you truly need a single big scan
Prune/archive old session JSONL files to shrink the tree

Example fix

// before
$ agentmemory import-jsonl ~/.claude/projects
warn: Hit the 500-file scan cap... Tree exceeds the server's --max-files limit...
// after
$ for d in ~/.claude/projects/*/; do agentmemory import-jsonl "$d"; done

Defensive patterns

Strategy: fallback

Validate before calling

count=$(find ~/.claude/projects -name '*.jsonl' | wc -l); echo "discovered=$count — batch per project if count exceeds server --max-files"

Prevention

Import per project directory, not the whole projects root
Size the server's --max-files to your largest tree
Archive old session files periodically

When it happens

Trigger: import-jsonl reports json.traversalCapped, or discovered file count > server upper bound, after hitting the scan cap.

Common situations: Very large ~/.claude/projects trees with thousands of session files; running against the whole projects root instead of per project; server started with a low max-files while the tree is huge.

Related errors

${baseMsg} Re-run with --max-files=${suggested} (max ${upper

AI-assisted analysis of rohitg00/agentmemory@e04ba88819 (2026-08-30). Data as JSON: /api/errors/a4dfc993987d0ef0. Report an issue: GitHub.