pi-lore

pi-lore gives Pi agents GHC-aware tools for Haskell codebases. In large projects, ordinary code discovery often means reading whole files, chasing imports by hand, and filling the model context with definitions that are unrelated or already known. Lore changes that interaction: the agent can ask about symbols directly.

Instead of treating the repository as plain text, pi-lore starts a compatible lore-mcp server and exposes tools for symbol search, definition lookup, reference search, exported-symbol browsing, instance lookup, expression typing, compilation, and test execution. The result is less redundant context and more precise edits, especially when a task spans many modules.

pi-lore also adds Pi-specific context management. It remembers definitions returned on the current branch, restores that memory across Pi forks and resumes, and compresses failed compile/test repair sessions after validation succeeds.

The shared Lore tool behavior is documented in the tool guide. This README covers the Pi package: installation, managed server setup, commands, configuration, recovery, and troubleshooting.

What You Get

• Symbol-level discovery: search symbols, inspect definitions, find references, list exports, resolve instances, and type expressions without forcing broad file reads.
• Compiler-backed validation: run reloadHomeModules, executeCode, and runTestSuite through the same Lore session the agent uses for analysis.
• Definition memory: omit unchanged definitions already returned in the current session.
• Recovery summaries: when a compile or test run fails, pi-lore tracks the "repair" actions and summarizes them after validation succeeds, so future context uses the summary instead of the full repair transcript.

Requirements

• Pi with package support.
• Node.js 24 or newer.
• A Cabal or Stack project whose compiler can be detected locally.

pi-lore needs a lore-mcp server built with the exact full GHC version used by the target project. For Linux x86-64 with GNU libc, some matching servers are published on the Lore releases page. When a release asset matches the project compiler and current platform, pi-lore downloads it automatically.

If no matching prebuilt server is available, clone the Lore repository and build lore-mcp locally, then configure that executable in /lore-settings. Build instructions are in the lore-mcp README.

The root GHC compatibility section explains why exact compiler matching is required.

Install

Install for the current user:

pi install npm:pi-lore

Or install only for the current project:

pi install npm:pi-lore -l

Start Pi from the root of a Haskell project. On first use, pi-lore starts an already cached server or opens the setup menu.

Commands

| Command | Purpose | | --- | --- | | /lore-settings | Open the project settings menu. | | /lore-settings show | Show effective settings. | | /lore-status | Show startup mode, command, GHC version, and server state. | | /lore-restart | Restart the server, or reopen setup if it is not configured. | | /lore-stats | Show estimated tool-context and recovery statistics. | | /lore-recovery-abandon | Stop the active recovery and keep the original conversation entries. |

After changing startup or tool-registration settings, run /reload or restart Pi.

Configuration

pi-lore has one Pi-side config file and one Lore server config file:

• .pi/lore.config.json configures the Pi extension: server startup, timeouts, proxied Lore tools, recovery behavior, and Pi-side state paths.
• lore.yaml configures the Haskell session and lore-mcp: project root, GHC loading, MCP tool enablement, and tool-owned settings.

The /lore-settings menu writes .pi/lore.config.json. Use the root quick start for a first lore.yaml, and the lore-mcp configuration guide for full configuration mechanics.

A typical .pi/lore.config.json is small:

{
  "enabled": true,
  "tools": {
    "disabled": ["executeCode"]
  },
  "recovery": {
    "compilation": true,
    "tests": true
  }
}

Common settings:

• enabled: enables or disables Lore for the project.
• command and args: run a custom lore-mcp binary instead of managed selection.
• env: adds environment variables to the server process.
• cwd: sets the server working directory; relative paths resolve from the Pi project directory.
• tools.disabled: disables selected public Lore tools in Pi.
• recovery.compilation and recovery.tests: control recovery after failed compile or test validation.

By default, pi-lore enables definition caching and hides the public reset tool, because it tracks summarization and branch changes itself:

{
  "env": {
    "LORE_MCP_ENABLE_DEFINITION_KNOWLEDGE_CACHE": "true",
    "LORE_MCP_TOOL_ENABLED_NOTIFY_KNOWLEDGE_RESET": "false"
  }
}

Values from .pi/lore.config.json are merged with these defaults. Host-level Pi configuration, when supplied by the host, takes precedence. Project configuration is not loaded until the project is trusted.

Advanced settings include startup and tool timeouts, recovery summary timeout, maximum inline diff size, tool override behavior, and stateDir for persistent Pi-side state.

Use a JSON patch for non-interactive tool and recovery changes:

/lore-settings set {"recovery":{"tests":false}}

Edit other advanced values directly in .pi/lore.config.json.

Server Selection

When command is not configured, pi-lore detects the project provider, reads the project GHC version, and selects a server binary with the exact same GHC version when one is available.

Downloaded binaries are shared by all projects and stored under $XDG_CACHE_HOME/pi-lore when XDG_CACHE_HOME is set, otherwise ~/.cache/pi-lore.

There is no nearest-version fallback. When the project changes compiler or resolver, reload Pi so the extension can select the corresponding server.

For local Lore development, unsupported platforms, or missing binary builds, set a custom command:

{
  "command": "/home/me/src/lore/dist/lore-mcp",
  "args": []
}

Open /lore-settings, choose Set command to run Lore, and enter a command on PATH or an executable path. Before saving, pi-lore verifies the binary identity against the expected Lore version, exact GHC version, and target platform.

Build instructions and --version-json verification are maintained in the lore-mcp README.

Recovery

Recovery starts when reloadHomeModules or runTestSuite returns a failed structured result. pi-lore records a project baseline, keeps repair work in a distinct section, and tracks which validation steps still need to pass.

After compilation and test checks succeed, pi-lore captures the resulting diff and asks Pi to summarize failed approaches, useful findings, and applied fixes. Future context uses that summary instead of the full repair transcript.

Disable compilation and test recovery independently under /lore-settings -> Recovery. /lore-recovery-abandon stops recovery without replacing the original entries.

Troubleshooting

Lore Cannot Detect The Project

Start Pi at the project root. Provider detection and supported manifest order are documented in the lore-mcp configuration guide.

No Binary Is Available For This GHC Version

Choose Build instructions in the setup menu, build lore-mcp with the exact project compiler, and configure the resulting executable as a custom command.

The Configured Binary Is Rejected

Run:

/path/to/lore-mcp --version-json

Its loreVersion, ghcVersion, and target must match the extension release, project compiler, and current platform.

Settings Appear Unchanged

Run /reload or restart Pi. Startup settings and MCP tool registration are established when the server starts.

Development

pi-lore is a TypeScript Pi package and does not use Cabal. From pi-lore/:

npm test
npm run validate:package

The Haskell server it launches is built separately with Cabal as described in the lore-mcp README.