Continual Learning (pi)

Automatically and incrementally keeps the current checkout’s AGENTS.md up to date from pi session transcripts for a workspace.

A workspace is the parent git repo when present (shared across branches, worktrees, and other checkouts of the same origin), otherwise the current directory.

The package combines:

• An extension that decides when to trigger learning (agent_settled cadence + /learn)
• A continual-learning skill that orchestrates the learning flow
• An agents-memory-updater skill that mines new or changed sessions and updates AGENTS.md

It avoids noisy rewrites by:

• Reading existing AGENTS.md first and updating matching bullets in place
• Processing only new or changed session files (shared incremental index)
• Writing plain bullet points only (no evidence/confidence metadata)

Installation

pi install https://github.com/sudokai/pi-continual-learning

Or add to ~/.pi/agent/settings.json / .pi/settings.json:

{
  "packages": ["https://github.com/sudokai/pi-continual-learning"]
}

Quick test without installing:

pi -e https://github.com/sudokai/pi-continual-learning

From a local clone:

pi install /path/to/pi-continual-learning

How it works

On eligible agent_settled events (agent fully idle — no retry, compaction, or queued continuation), the extension may queue a follow-up user message (deliverAs: "followUp") that asks the agent to run the continual-learning skill.

Effective auto learning requires both:

1. User preference (per workspace, default on / opt-out) — stored in config.json; toggle with /autolearn.
2. Subagent gate — at session_start, the extension checks active tools for a subagent-like tool (name exactly subagent, agent-start, or task, or a description that says spawn/launch/start/delegate with child/sub-agent as the object — bare “subagent” mentions alone do not count). Detection runs once per session (no mid-session re-check).

• If no subagent is found, automatic continual learning does not queue for that session: cadence still counts turns but never queues a learning follow-up. The UI gets one warning: automatic continual learning is disabled and /learn can run in-session.
• If the user turns auto off via /autolearn off (or disable), cadence still counts turns but never queues; there is no session_start notify for user-off (status via /autolearn).
• Auto follow-ups require a subagent and tell the skill not to mine in-session if that tool is missing.
• /learn always queues learning (ignores the user auto toggle). It prefers a subagent; when none was detected at session start, the UI gets an info notify that work will run in this session, and the follow-up message permits in-session fallback.

The orchestrator skill is marked disable-model-invocation: true, so it is not auto-selected during normal turns. Follow-up messages include a Trigger: auto (cadence). or Trigger: /learn. marker so the skill can refuse in-session mining on auto and allow it on /learn.

Learning follow-ups are guarded so they are not counted as normal cadence turns and do not immediately re-trigger learning.

Best-effort queue: cadence//learn commit lastRunAtMs and related counters before pi.sendUserMessage. That API is synchronous void (runtime fire-and-forget); async queue/auth failures are not observable at the call site, so a failed inject can still reset turn/minute gates without a learning run. The in-memory pending flag is cleared on the next agent_settled (or on a synchronous throw), so permanent stall is unlikely.

Workspace scoping

Situation	Same workspace id?	Sessions pooled?
Branch switch, same cwd	Yes	Yes
Git worktree of same repo	Yes (origin or common-dir)	Yes
Second clone, same origin	Yes (canonical origin)	Yes, when header cwd maps to the id
Unrelated project	No	No
Non-git directory	Id from cwd only	Current folder only

Identity resolve order: canonical origin URL → git rev-parse --git-common-dir → cwd.
Id format: sha256(source)[:12]_safeName.

AGENTS.md is written only in the current checkout (git rev-parse --show-toplevel when available, else cwd). Other checkouts pick up changes via git merge/rebase or their own later runs against the shared index.

State and index paths

Shared per workspace id under:

• ~/.pi/agent/continual-learning/<workspaceId>/state.json — cadence state
• ~/.pi/agent/continual-learning/<workspaceId>/index.json — incremental session index
• ~/.pi/agent/continual-learning/<workspaceId>/config.json — user auto-learning preference

Config shape (v1; missing file or invalid config ⇒ auto enabled):

{
  "version": 1,
  "autoLearningEnabled": true
}

Cadence and /autolearn read config.json for the workspace id of the current cwd (so a mid-session cwd change uses that workspace’s preference). If a config file exists but is unreadable or invalid, the extension fails open to enabled and warns once at session_start (and notes it on /autolearn status).

Index shape (Cursor-compatible):

{
  "version": 1,
  "transcripts": {
    "/Users/you/.pi/agent/sessions/--Users-you-Developer-proj--/abc.jsonl": {
      "mtimeMs": 1784537177825
    }
  }
}

Session discovery always uses ~/.pi/agent/sessions/ (custom sessionDir / PI_CODING_AGENT_SESSION_DIR are not supported), in directories encoded from cwd the same way pi does (/, \, and : → -, wrapped as --…--). Membership uses the session JSONL header cwd resolved to the same workspace id.

Trigger cadence

A turn here means one settled agent run (agent_settled): retries and compaction recovery do not inflate the counter.

Default cadence:

• minimum 10 settled turns
• minimum 120 minutes since the last run
• max mtime among sessions for this checkout and its linked git worktrees must advance since the previous run

Cadence mtime checks are checkout/worktree-local (cwd + git worktree list session dirs) so the hot path stays cheap. Independent clones of the same origin are not consulted for that gate; when a learning run does fire, mining still discovers those clones via workspace-id membership. Day-to-day same-checkout use is unaffected because the active session’s mtime usually advances every turn.

Trial mode (env-enabled only):

• minimum 3 settled turns
• minimum 15 minutes
• expires after 24 hours, then falls back to default cadence

Optional env overrides

Both CONTINUAL_LEARNING_* and legacy CONTINUOUS_LEARNING_* are accepted:

Env	Role
CONTINUAL_LEARNING_MIN_TURNS	default min turns (10)
CONTINUAL_LEARNING_MIN_MINUTES	default min minutes (120)
CONTINUAL_LEARNING_TRIAL_MODE	enable trial
CONTINUAL_LEARNING_TRIAL_MIN_TURNS	trial turns (3)
CONTINUAL_LEARNING_TRIAL_MIN_MINUTES	trial minutes (15)
CONTINUAL_LEARNING_TRIAL_DURATION_MINUTES	trial window (1440)

Output format in AGENTS.md

The memory updater writes only:

• ## Learned User Preferences
• ## Learned Workspace Facts

Each item is a plain bullet point (at most 12 per section). If nothing durable is found, the agent responds exactly:

No high-signal memory updates.

(and still refreshes the index).

Commands

Command	Description
/learn	Run continual learning now (bypass cadence; shared index still applies; in-session fallback when no subagent tool; ignores /autolearn off)
/autolearn / status / show	Show status from config.json: user setting + whether auto cadence is allowed to queue this session (subagent gate)
/autolearn on / enable	Enable automatic continual learning for this workspace (immediate; persists to config.json)
/autolearn off / disable	Disable automatic continual learning for this workspace (cadence still counts; never queues; /learn still works)

License

MIT