pi-context-loader

Config-driven context injection for Pi agents. Loads files at session start and injects them as system prompt or message — the Pi equivalent of a sessionStart hook.

Install

From npm:

pi install npm:pi-context-loader

From git:

pi install git+https://github.com/juanje/pi-context-loader.git

Or load directly without installing:

pi -e /path/to/pi-context-loader/extensions/context-loader.ts

Quick start

Create .pi/context-loader.json in your project:

{
  "files": [
    "context/user-profile.md",
    "context/current-state.md"
  ]
}

Start Pi — the listed files are read at session start and injected into the agent's context (system prompt by default, or as a message with "inject": "message").

How it works

The extension hooks into two Pi events:

1. session_start — loads the config, reads all listed files and optional latest log, caches the combined context
2. before_agent_start — injects the cached context via the configured mode

Injection modes

The inject field controls how context reaches the agent:

Mode	Behavior	Frequency	Survives compaction	LLM weight
"systemPrompt" (default)	Appended to system prompt	Every turn	Yes — always present	High — treated as instructions
"message"	Injected as a conversation message	Once — first turn only	No — may be summarized	Normal — treated as context

Why the frequency differs: the system prompt is rebuilt fresh on every turn, so it must be re-appended each time or it would disappear. A message, once added, becomes a permanent part of conversation history — re-injecting it on every turn would just duplicate the same content across the transcript instead of refreshing anything (the file content itself is only read once, at session_start, either way).

When to use each:

• systemPrompt — for identity, rules, or context that must be present on every turn (e.g., user profile, agent guidelines)
• message — for operational state that's useful at the start of the session but shouldn't be duplicated turn after turn (e.g., active incidents, current sprint items)

Config format

Config file: .pi/context-loader.json

interface ContextLoaderConfig {
  files?: string[];        // paths relative to project root
  latestLog?: {
    index: string;         // path to an index file (e.g. "logs/index.md")
    dir: string;           // directory containing log files (e.g. "logs")
    marker: string;        // marker to match in index lines (e.g. "active")
  };
  separator?: string;      // join string (default: "\n\n---\n\n")
  inject?: "systemPrompt" | "message";  // injection mode (default: "systemPrompt")
}

files

Array of file paths relative to the project root. Each file is read and its content is included in the context. Missing files are silently skipped.

latestLog

Optional dynamic log finder. Scans the index file for lines matching marker (case-insensitive), extracts the last YYYY-MM-DD date found, and loads {dir}/{date}.md.

Useful for agents with session logs where you want to inject the most recent active log automatically.

separator

String used to join all loaded content. Defaults to "\n\n---\n\n" (markdown horizontal rule).

inject

How context is delivered to the agent. Either "systemPrompt" (default) or "message". See Injection modes for details.

Examples

Memory agent (Agentic Buddy-style)

{
  "files": [
    "agent_brain/identity/USER.md"
  ],
  "latestLog": {
    "index": "logs/index.md",
    "dir": "logs",
    "marker": "active"
  }
}

Diagnostic agent (active incidents as message)

{
  "files": ["kb/active/index.md"],
  "inject": "message"
}

Diagnostic agent (reference context in system prompt)

{
  "files": [
    "context/team-roster.md",
    "context/known-issues-summary.md"
  ]
}

Minimal

{
  "files": ["CONTEXT.md"]
}

Static context

This extension handles dynamic context — files that change between sessions. For static context, Pi has built-in support:

• .pi/SYSTEM.md — replaces the default system prompt (agent identity)
• AGENTS.md / CLAUDE.md — hierarchical context files loaded automatically

Use pi-context-loader for content that needs to be assembled from multiple files or includes dynamic elements like "latest active log."

Development

git clone https://github.com/juanje/pi-context-loader.git
cd pi-context-loader
npm install
npm run check    # typecheck + lint + test

License

MIT — see LICENSE.