spike: local legreffier MCP server with AxLearn self-improvement

[legreffier]

Summary

Build a local MCP server for legreffier that wraps AxLearn (@ax-llm/ax) with diary-backed storage. The server runs alongside Claude Code, keeps an AxLearn instance in memory with mode: 'continuous', and exposes MCP tools for asking questions, giving feedback, and triggering optimization.

This is the next evolution of legreffier: diary entries become the training signal for self-improvement. The agent gets better at answering codebase questions over time, and the entire learning chain is verifiable via diary provenance (CIDs, signatures, createdBy).

Motivation

• Diary entries record what happened but aren't used to improve agent behavior
• AxLearn's teacher-student pattern (opus teaches, sonnet runs) fits naturally with diary-backed storage
• MoltNet adds provenance, trust-weighted training, and cross-agent learning on top of raw AxLearn
• Local MCP server means native Claude Code integration — no custom skills or HTTP clients

Architecture

┌──────────────────────────────────────┐
│  legreffier local MCP server         │
│  (Fastify + @getlarge/fastify-mcp)   │
│                                      │
│  AxLearn instance (in memory)        │
│  ├── checkpoint from diary           │
│  ├── accumulated traces              │
│  ├── mode: 'continuous'              │
│  └── session: <uuid>                 │
│                                      │
│  AxStorage → diary entries via API   │
│  AxAIClaudeAgentSDK as LLM          │
│  Auto-kills after 2h idle            │
└──────────┬───────────────────────────┘
           │ MCP (stdio)
           │
  Claude Code (native MCP client)

MCP Tools

Tool	Input	Description
legreffier_ask	{ question, codeContext? }	agent.forward() — answer question, trace saved to diary
legreffier_feedback	{ traceIndex?, score, label?, comment? }	agent.addFeedback() + agent.applyUpdate() (continuous)
legreffier_traces	{ limit? }	Recent traces with short index numbers
legreffier_optimize	{ budget? }	Batch optimization with teacher model (opus)
legreffier_status	{}	Checkpoint version, trace count, avg score

AxStorage → Diary Mapping

AxStorage op	Diary API call	Tags
save trace	POST /diaries/:id/entries	axlearn:trace, axlearn:session:<uuid>, entry type: procedural
save checkpoint	POST /diaries/:id/entries	axlearn:checkpoint, axlearn:v:<N>, entry type: reflection
load traces	POST /diaries/search	Filter by axlearn:trace tags + date/limit
load checkpoints	GET /diaries/:id/entries	Filter by axlearn:checkpoint tags

What MoltNet adds beyond plain DB

1. Provenance chain — CID from improved output → checkpoint → training traces → original experiences
2. Trust-weighted training — vouch graph scores could weight traces during optimization
3. Cross-agent learning — diary shares let other agents' traces become training data
4. Signed checkpoints — learned behavior is content-addressed and verifiable
5. Semantic search — pgvector enables meaning-based trace retrieval, not just tag queries

Implementation plan

Phase 0: Spike (this issue)

• AxStorage adapter backed by diary entries (tools/src/legreffier-local/)
• Minimal Fastify + fastify-mcp server with 5 tools
• AxLearn wiring with AxAIClaudeAgentSDK (opus teacher, sonnet student)
• Register in .claude/settings.json for testing
• Verify roundtrip: ask → trace in diary → feedback → optimize → better answer

Phase 1: Polish

• SSE transport with idle auto-kill (2h)
• Session UUID + trace tagging
• Trace index numbering for feedback targeting
• Graceful shutdown + state persistence

Phase 2: Integration

• Connect to existing legreffier skill (trigger tools from skill context)
• axRAG adapter for on-demand deep retrieval (entries_search as overfetch)
• Seed with prod diary data for meaningful optimization

Future

• Local context pack creation with provenance (packType: 'local') — depends on [TRACK] Entry relations + DAG-CBOR pack provenance + context resource integration #396 Phase 2
• Trust-weighted trace scoring from vouch graph
• Cross-agent learning via diary shares

Key dependencies

• @ax-llm/ax (AxLearn, AxStorage, ax) — already in workspace
• @getlarge/fastify-mcp — already in workspace
• @moltnet/api-client — diary CRUD + search
• libs/context-evals/src/ax-claude-agent-sdk.ts — AxAIClaudeAgentSDK adapter

Research doc

Full brainstorming and design details: docs/research/local-context-packs-axrag-self-improvement.md

Related

• [TRACK] Entry relations + DAG-CBOR pack provenance + context resource integration #396 Entry relations + DAG-CBOR pack provenance
• [TASK] Automatic context injection via MCP resource (moltnet://context) #183 Automatic context injection via MCP resource
• feat: gpack — GEPA-driven context pack optimization pipeline #393 GEPA-driven context pack optimization
• feat: @themoltnet/eval — opinionated eval + optimization library #394 @themoltnet/eval library

[legreffier]

Implementation Plan

Moved from docs/superpowers/plans/2026-03-16-legreffier-local-mcp.md (removed from repo).

Click to expand full plan

Legreffier Local MCP Server — Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Build a local MCP server that wraps AxLearn with diary-backed storage, enabling self-improving codebase Q&A through MCP tools.

Architecture: A minimal Fastify + @getlarge/fastify-mcp server in tools/src/legreffier-local/ exposes 5 MCP tools (legreffier_ask, legreffier_feedback, legreffier_traces, legreffier_optimize, legreffier_status). An AxStorage adapter maps AxLearn traces/checkpoints to diary entries via @moltnet/api-client. The AxLearn instance stays in memory for incremental learning across Claude Code sessions.

Tech Stack: @ax-llm/ax (AxLearn), @getlarge/fastify-mcp, @moltnet/api-client, @anthropic-ai/claude-agent-sdk (AxAI adapter), TypeBox

Issue: #418
Research doc: docs/research/local-context-packs-axrag-self-improvement.md

---

File Structure

tools/src/legreffier-local/
├── main.ts              # Entry point — Fastify setup + MCP plugin + tool registration
├── ax-storage.ts        # AxStorage adapter backed by diary entries via API client
├── ax-agent-sdk.ts      # AxAIClaudeAgentSDK — AxBaseAI adapter for Claude Agent SDK
├── agent.ts             # AxLearn instance factory + session management
├── tools.ts             # MCP tool schemas + handler functions + registration
├── types.ts             # Shared types (config, deps, tool inputs)
└── __tests__/
    ├── ax-storage.test.ts   # AxStorage adapter unit tests (mocked API client)
    └── tools.test.ts        # Tool handler unit tests (mocked agent)

Existing files to reference (read-only):

• apps/mcp-server/src/app.ts — Fastify + fastify-mcp registration pattern
• apps/mcp-server/src/info-tools.ts — Simple tool registration example
• apps/mcp-server/src/utils.ts — textResult, errorResult helpers
• apps/mcp-server/src/schemas.ts — TypeBox schema patterns for MCP tools

Files to modify:

• tools/package.json — Add @getlarge/fastify-mcp, @anthropic-ai/claude-agent-sdk, fastify deps + legreffier-local script

---

Chunk 1: AxStorage Adapter + Types

Task 1: Add dependencies to tools/package.json

Files:

• Modify: tools/package.json

• Step 1: Add dependencies

Add to dependencies in tools/package.json:

{
  "@anthropic-ai/claude-agent-sdk": "catalog:",
  "@getlarge/fastify-mcp": "catalog:",
  "fastify": "catalog:"
}

Add to scripts:

{
  "legreffier-local": "tsx src/legreffier-local/main.ts"
}

• Step 2: Run pnpm install

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm install
Expected: Dependencies resolve successfully.

• Step 3: Commit

git add tools/package.json pnpm-lock.yaml
git commit -m "chore(tools): add fastify-mcp + claude-agent-sdk deps for legreffier-local"

Task 2: Create shared types

Files:

• Create: tools/src/legreffier-local/types.ts

• Step 1: Write types file

/**
 * Legreffier Local MCP — Shared Types
 */

import type { Client } from '@moltnet/api-client';
import type { AxAIService, AxLearn, AxGen } from '@ax-llm/ax';
import type { FastifyBaseLogger } from 'fastify';

/** Agent input/output signature. */
export interface AgentInput {
  question: string;
  codeContext?: string;
}

export interface AgentOutput {
  answer: string;
  confidence: 'high' | 'medium' | 'low';
}

/** Server configuration loaded from environment. */
export interface ServerConfig {
  /** MoltNet REST API base URL (default: http://localhost:8000) */
  apiBaseUrl: string;
  /** Diary ID to use for storage */
  diaryId: string;
  /** Bearer token for API auth */
  bearerToken: string;
  /** Port for MCP SSE transport (default: 0 = random) */
  port: number;
  /** Teacher model for optimization (default: claude-opus-4-6) */
  teacherModel: string;
  /** Student model for forward calls (default: claude-sonnet-4-6) */
  studentModel: string;
  /** Idle timeout in ms before auto-shutdown (default: 7200000 = 2h) */
  idleTimeoutMs: number;
}

/** Dependencies injected into tool handlers. */
export interface LocalMcpDeps {
  agent: AxLearn<AgentInput, AgentOutput>;
  gen: AxGen<AgentInput, AgentOutput>;
  studentAi: AxAIService;
  client: Client;
  config: ServerConfig;
  logger: FastifyBaseLogger;
  /** Current session UUID (generated on server start). */
  sessionId: string;
  /** Tracks trace index within session for easy feedback targeting. */
  traceCounter: number;
  /** Map of session-local index → trace ID for feedback targeting. */
  traceIndex: Map<number, string>;
  /** Last activity timestamp for idle shutdown. */
  lastActivity: number;
  /** Server start timestamp for uptime calculation. */
  startTime: number;
}

• Step 2: Commit

git add tools/src/legreffier-local/types.ts
git commit -m "feat(legreffier-local): add shared types"

Task 3: Implement AxStorage adapter (tests first)

Files:

• Create: tools/src/legreffier-local/__tests__/ax-storage.test.ts

• Create: tools/src/legreffier-local/ax-storage.ts

• Step 1: Write failing tests for AxStorage

/**
 * AxStorage diary adapter — unit tests
 *
 * Tests the mapping between AxLearn's AxStorage interface and MoltNet diary entries.
 * API client is fully mocked — no network calls.
 */
import { describe, it, expect, vi, beforeEach } from 'vitest';

import { createDiaryAxStorage } from '../ax-storage.js';

// Mock the API client functions
const mockCreateEntry = vi.fn();
const mockSearchDiary = vi.fn();
const mockListEntries = vi.fn();
const mockUpdateEntry = vi.fn();

vi.mock('@moltnet/api-client', () => ({
  createDiaryEntry: (...args: unknown[]) => mockCreateEntry(...args),
  searchDiary: (...args: unknown[]) => mockSearchDiary(...args),
  listDiaryEntries: (...args: unknown[]) => mockListEntries(...args),
  updateDiaryEntryById: (...args: unknown[]) => mockUpdateEntry(...args),
}));

describe('createDiaryAxStorage', () => {
  const client = {} as any;
  const diaryId = 'diary-uuid-123';
  const bearerToken = 'test-token';
  const sessionId = 'session-uuid-456';

  let storage: ReturnType<typeof createDiaryAxStorage>;

  beforeEach(() => {
    vi.clearAllMocks();
    storage = createDiaryAxStorage({ client, diaryId, bearerToken, sessionId });
  });

  describe('save', () => {
    it('saves a trace as a procedural diary entry with correct tags', async () => {
      mockCreateEntry.mockResolvedValue({ data: { id: 'entry-1' } });

      const trace = {
        type: 'trace' as const,
        id: 'trace-abc',
        name: 'test-agent',
        input: { question: 'how does auth work?' },
        output: { answer: 'JWT tokens', confidence: 'high' },
        startTime: new Date('2026-03-16T10:00:00Z'),
        endTime: new Date('2026-03-16T10:00:05Z'),
        durationMs: 5000,
      };

      await storage.save('test-agent', trace);

      expect(mockCreateEntry).toHaveBeenCalledOnce();
      const call = mockCreateEntry.mock.calls[0][0];
      expect(call.path.diaryId).toBe(diaryId);
      expect(call.body.entryType).toBe('procedural');
      expect(call.body.tags).toEqual(
        expect.arrayContaining([
          'axlearn:trace',
          'axlearn:agent:test-agent',
          'axlearn:session:session-uuid-456',
        ]),
      );
      // Content should be JSON-serialized trace
      const content = JSON.parse(call.body.content);
      expect(content.id).toBe('trace-abc');
      expect(content.input.question).toBe('how does auth work?');
    });

    it('saves a checkpoint as a reflection diary entry with version tag', async () => {
      mockCreateEntry.mockResolvedValue({ data: { id: 'entry-2' } });

      const checkpoint = {
        type: 'checkpoint' as const,
        name: 'test-agent',
        version: 3,
        createdAt: new Date('2026-03-16T12:00:00Z'),
        instruction: 'You are a helpful assistant.',
        examples: [{ input: { question: 'q' }, output: { answer: 'a' } }],
        score: 0.85,
      };

      await storage.save('test-agent', checkpoint);

      expect(mockCreateEntry).toHaveBeenCalledOnce();
      const call = mockCreateEntry.mock.calls[0][0];
      expect(call.body.entryType).toBe('reflection');
      expect(call.body.tags).toEqual(
        expect.arrayContaining([
          'axlearn:checkpoint',
          'axlearn:agent:test-agent',
          'axlearn:v:3',
        ]),
      );
      expect(call.body.importance).toBe(8); // Checkpoints are high importance
    });
  });

  describe('load', () => {
    it('loads traces via searchDiary with correct tag filters', async () => {
      const now = new Date();
      mockSearchDiary.mockResolvedValue({
        data: {
          entries: [
            {
              id: 'entry-1',
              content: JSON.stringify({
                type: 'trace',
                id: 'trace-abc',
                name: 'test-agent',
                input: { question: 'q' },
                output: { answer: 'a', confidence: 'high' },
                startTime: now.toISOString(),
                endTime: now.toISOString(),
                durationMs: 100,
              }),
              tags: ['axlearn:trace', 'axlearn:agent:test-agent'],
              createdAt: now.toISOString(),
            },
          ],
        },
      });

      const result = await storage.load('test-agent', {
        type: 'trace',
        limit: 5,
      });

      expect(mockSearchDiary).toHaveBeenCalledOnce();
      const call = mockSearchDiary.mock.calls[0][0];
      expect(call.body.tags).toEqual(
        expect.arrayContaining(['axlearn:trace', 'axlearn:agent:test-agent']),
      );
      expect(call.body.limit).toBe(5);
      expect(result).toHaveLength(1);
      expect(result[0].type).toBe('trace');
      expect((result[0] as any).id).toBe('trace-abc');
    });

    it('loads checkpoints via listDiaryEntries with tag filter', async () => {
      mockListEntries.mockResolvedValue({
        data: {
          entries: [
            {
              id: 'entry-2',
              content: JSON.stringify({
                type: 'checkpoint',
                name: 'test-agent',
                version: 3,
                createdAt: '2026-03-16T12:00:00Z',
                instruction: 'Be helpful.',
                score: 0.85,
              }),
              tags: [
                'axlearn:checkpoint',
                'axlearn:agent:test-agent',
                'axlearn:v:3',
              ],
              createdAt: '2026-03-16T12:00:00Z',
            },
          ],
        },
      });

      const result = await storage.load('test-agent', {
        type: 'checkpoint',
        limit: 1,
      });

      expect(mockListEntries).toHaveBeenCalledOnce();
      expect(result).toHaveLength(1);
      expect(result[0].type).toBe('checkpoint');
      expect((result[0] as any).version).toBe(3);
    });

    it('filters traces by hasFeedback when requested', async () => {
      mockSearchDiary.mockResolvedValue({ data: { entries: [] } });

      await storage.load('test-agent', {
        type: 'trace',
        hasFeedback: true,
      });

      const call = mockSearchDiary.mock.calls[0][0];
      expect(call.body.tags).toEqual(
        expect.arrayContaining(['axlearn:has-feedback']),
      );
    });

    it('returns empty array when API returns no entries', async () => {
      mockSearchDiary.mockResolvedValue({ data: { entries: [] } });

      const result = await storage.load('test-agent', { type: 'trace' });
      expect(result).toEqual([]);
    });
  });
});

• Step 2: Run tests to verify they fail

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm --filter @moltnet/tools vitest run src/legreffier-local/__tests__/ax-storage.test.ts
Expected: FAIL — createDiaryAxStorage does not exist.

• Step 3: Implement AxStorage adapter

/**
 * AxStorage adapter backed by MoltNet diary entries.
 *
 * Maps AxLearn's AxStorage interface to diary entry CRUD:
 * - Traces → procedural entries tagged axlearn:trace
 * - Checkpoints → reflection entries tagged axlearn:checkpoint
 * - Queries → searchDiary (traces) or listDiaryEntries (checkpoints)
 */

import type {
  AxCheckpoint,
  AxStorage,
  AxStorageQuery,
  AxTrace,
} from '@ax-llm/ax';
import {
  createDiaryEntry,
  listDiaryEntries,
  searchDiary,
  updateDiaryEntryById,
} from '@moltnet/api-client';
import type { Client } from '@moltnet/api-client';

export interface DiaryStorageOptions {
  client: Client;
  diaryId: string;
  bearerToken: string;
  sessionId: string;
}

export function createDiaryAxStorage(options: DiaryStorageOptions): AxStorage {
  const { client, diaryId, bearerToken, sessionId } = options;
  const auth = () => bearerToken;

  /** Map from trace ID to diary entry ID (for feedback updates). */
  const traceEntryMap = new Map<string, string>();

  const save = async (
    name: string,
    item: AxTrace | AxCheckpoint,
  ): Promise<void> => {
    if (item.type === 'trace') {
      const trace = item as AxTrace;
      const tags = [
        'axlearn:trace',
        `axlearn:agent:${name}`,
        `axlearn:session:${sessionId}`,
      ];
      if (trace.feedback) {
        tags.push('axlearn:has-feedback');
      }

      // Check if this trace already exists (feedback update)
      const existingEntryId = traceEntryMap.get(trace.id);
      if (existingEntryId) {
        await updateDiaryEntryById({
          client,
          auth,
          path: { entryId: existingEntryId },
          body: {
            content: JSON.stringify(trace),
            tags,
          },
        });
        return;
      }

      const { data } = await createDiaryEntry({
        client,
        auth,
        path: { diaryId },
        body: {
          content: JSON.stringify(trace),
          title: `axlearn trace: ${truncate(stringifyInput(trace.input), 80)}`,
          entryType: 'procedural',
          tags,
          importance: 5,
        },
      });
      if (data?.id) {
        traceEntryMap.set(trace.id, data.id);
      }
    } else {
      const checkpoint = item as AxCheckpoint;
      const tags = [
        'axlearn:checkpoint',
        `axlearn:agent:${name}`,
        `axlearn:v:${checkpoint.version}`,
      ];

      await createDiaryEntry({
        client,
        auth,
        path: { diaryId },
        body: {
          content: JSON.stringify(checkpoint),
          title: `axlearn checkpoint v${checkpoint.version} (score: ${checkpoint.score?.toFixed(2) ?? 'n/a'})`,
          entryType: 'reflection',
          tags,
          importance: 8,
        },
      });
    }
  };

  const load = async (
    name: string,
    query: AxStorageQuery,
  ): Promise<(AxTrace | AxCheckpoint)[]> => {
    if (query.type === 'trace') {
      const tags = ['axlearn:trace', `axlearn:agent:${name}`];
      if (query.hasFeedback) {
        tags.push('axlearn:has-feedback');
      }

      const { data } = await searchDiary({
        client,
        auth,
        body: {
          diaryId,
          tags,
          limit: query.limit ?? 50,
          offset: query.offset,
          entryTypes: ['procedural'],
        },
      });

      return parseEntries(data?.entries);
    }

    // Checkpoints: use list with tag filter
    const tags = [`axlearn:checkpoint`, `axlearn:agent:${name}`];
    if (query.version !== undefined) {
      tags.push(`axlearn:v:${query.version}`);
    }

    const { data } = await listDiaryEntries({
      client,
      auth,
      path: { diaryId },
      query: {
        tags: tags.join(','),
        limit: query.limit ?? 10,
      },
    });

    return parseEntries(data?.entries);
  };

  return { save, load };
}

function parseEntries(
  entries: Array<{ content: string }> | undefined,
): (AxTrace | AxCheckpoint)[] {
  if (!entries?.length) return [];
  return entries
    .map((e) => {
      try {
        const parsed = JSON.parse(e.content);
        // Restore Date objects from ISO strings
        if (parsed.type === 'trace') {
          parsed.startTime = new Date(parsed.startTime);
          parsed.endTime = new Date(parsed.endTime);
        }
        if (parsed.type === 'checkpoint' && parsed.createdAt) {
          parsed.createdAt = new Date(parsed.createdAt);
        }
        return parsed;
      } catch {
        return null;
      }
    })
    .filter(Boolean);
}

function stringifyInput(input: Record<string, unknown>): string {
  const question = input.question;
  if (typeof question === 'string') return question;
  return JSON.stringify(input);
}

function truncate(s: string, max: number): string {
  return s.length <= max ? s : s.slice(0, max - 3) + '...';
}

• Step 4: Run tests to verify they pass

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm --filter @moltnet/tools vitest run src/legreffier-local/__tests__/ax-storage.test.ts
Expected: All tests PASS.

• Step 5: Commit

git add tools/src/legreffier-local/ax-storage.ts tools/src/legreffier-local/__tests__/ax-storage.test.ts
git commit -m "feat(legreffier-local): add AxStorage adapter backed by diary entries"

---

Chunk 2: AxAI Adapter + Agent Factory

Task 4: Create AxAIClaudeAgentSDK adapter

This adapter wraps @anthropic-ai/claude-agent-sdk as an AxAI-compatible service so AxLearn can use Claude via keychain auth. The full implementation exists at /Users/edouard/Dev/getlarge/themoltnet/libs/context-evals/src/ax-claude-agent-sdk.ts (on the fix/skill-eval-pipeline-training-examples branch in the main worktree — not yet on origin/main).

Files:

• Create: tools/src/legreffier-local/ax-agent-sdk.ts

• Step 1: Copy and simplify the adapter

Copy the file from the main worktree:

cp /Users/edouard/Dev/getlarge/themoltnet/libs/context-evals/src/ax-claude-agent-sdk.ts \
   /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp/tools/src/legreffier-local/ax-agent-sdk.ts

Then simplify:

1. Remove the imports of getRuntimeEnv and loadContextEvalsConfig from ./config.js
2. Remove the import of ResultPayload from ./sdk-types.js
3. Replace loadContextEvalsConfig() in buildQueryOptions with inline env reads:
   • process.env.CLAUDE_CODE_EXECUTABLE for pathToClaudeCodeExecutable
   • process.env.ANTHROPIC_API_KEY / process.env.ANTHROPIC_AUTH_TOKEN for auth
4. Replace getRuntimeEnv() with {} (no special env forwarding needed for this spike)
5. Inline the ResultPayload type (it's just the shape of the result message from Claude Agent SDK):

   interface ResultPayload {
     type: 'result';
     subtype: 'success' | 'error';
     result?: string;
     errors?: string[];
     usage?: {
       input_tokens: number;
       output_tokens: number;
       cache_creation_input_tokens?: number;
       cache_read_input_tokens?: number;
     };
     num_turns?: number;
     duration_ms?: number;
     duration_api_ms?: number;
     total_cost_usd?: number;
   }

6. Remove streaming (runAgentQueryStream) — not needed for AxLearn. Set FEATURES.streaming to false.

• Step 2: Verify it compiles

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm --filter @moltnet/tools run typecheck
Expected: No type errors.

• Step 3: Commit

git add tools/src/legreffier-local/ax-agent-sdk.ts
git commit -m "feat(legreffier-local): add AxAIClaudeAgentSDK adapter for AxLearn"

Task 5: Create agent factory

Files:

• Create: tools/src/legreffier-local/agent.ts

• Step 1: Write agent factory

/**
 * AxLearn agent factory — creates and configures the self-improving agent.
 */

import { ax, AxLearn, type AxGen } from '@ax-llm/ax';
import type { Client } from '@moltnet/api-client';

import { AxAIClaudeAgentSDK } from './ax-agent-sdk.js';
import { createDiaryAxStorage } from './ax-storage.js';
import type { AgentInput, AgentOutput, ServerConfig } from './types.js';

export interface AgentBundle {
  agent: AxLearn<AgentInput, AgentOutput>;
  gen: AxGen<AgentInput, AgentOutput>;
  studentAi: AxAIClaudeAgentSDK;
}

export function createAgent(
  config: ServerConfig,
  sessionId: string,
  client: Client,
): AgentBundle {
  const storage = createDiaryAxStorage({
    client,
    diaryId: config.diaryId,
    bearerToken: config.bearerToken,
    sessionId,
  });

  const teacherAi = new AxAIClaudeAgentSDK({ model: config.teacherModel });
  const studentAi = new AxAIClaudeAgentSDK({ model: config.studentModel });

  const gen =
    ax<'question:string "User question about the codebase", codeContext?:string "Relevant code or docs" -> answer:string "Helpful answer", confidence:class "high, medium, low"'>(
      'question:string "User question about the codebase", codeContext?:string "Relevant code or docs" -> answer:string "Helpful answer", confidence:class "high, medium, low"',
    ) as unknown as AxGen<AgentInput, AgentOutput>;

  gen.setInstruction(
    'You are a MoltNet development assistant. Answer questions about the MoltNet codebase accurately and concisely. Cite specific files and patterns when possible. If you are unsure, say so and indicate low confidence.',
  );

  const agent = new AxLearn(gen, {
    name: 'legreffier-local',
    teacher: teacherAi,
    storage,
    budget: 5,
    generateExamples: false,
    useTraces: true,
  });

  return { agent, gen, studentAi };
}

• Step 2: Verify it compiles

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm --filter @moltnet/tools run typecheck
Expected: No type errors.

• Step 3: Commit

git add tools/src/legreffier-local/agent.ts
git commit -m "feat(legreffier-local): add AxLearn agent factory with diary storage"

---

Chunk 3: MCP Tools + Server Entry Point

Task 6: Implement MCP tool handlers (tests first)

Files:

• Create: tools/src/legreffier-local/__tests__/tools.test.ts

• Create: tools/src/legreffier-local/tools.ts

• Step 1: Write failing tests for tool handlers

/**
 * MCP tool handler tests — mocked agent, no network.
 */
import { describe, it, expect, vi, beforeEach } from 'vitest';

import {
  handleAsk,
  handleFeedback,
  handleTraces,
  handleStatus,
} from '../tools.js';
import type { LocalMcpDeps } from '../types.js';

function makeDeps(overrides: Partial<LocalMcpDeps> = {}): LocalMcpDeps {
  return {
    agent: {
      forward: vi
        .fn()
        .mockResolvedValue({ answer: 'test answer', confidence: 'high' }),
      getTraces: vi.fn().mockResolvedValue([]),
      addFeedback: vi.fn().mockResolvedValue(undefined),
      optimize: vi
        .fn()
        .mockResolvedValue({
          score: 0.8,
          improvement: 0.1,
          checkpointVersion: 1,
          stats: {
            trainingExamples: 3,
            validationExamples: 1,
            durationMs: 5000,
          },
        }),
      getGen: vi
        .fn()
        .mockReturnValue({ getInstruction: () => 'test instruction' }),
      getStorage: vi.fn(),
    } as any,
    gen: {} as any,
    studentAi: {} as any,
    client: {} as any,
    config: {
      apiBaseUrl: 'http://localhost:8000',
      diaryId: 'diary-1',
      bearerToken: 'tok',
      port: 0,
      teacherModel: 'opus',
      studentModel: 'sonnet',
      idleTimeoutMs: 7200000,
    },
    logger: {
      info: vi.fn(),
      error: vi.fn(),
      debug: vi.fn(),
      warn: vi.fn(),
    } as any,
    sessionId: 'session-123',
    traceCounter: 0,
    traceIndex: new Map(),
    lastActivity: Date.now(),
    startTime: Date.now(),
  };
}

describe('handleAsk', () => {
  it('calls agent.forward and returns answer with trace index', async () => {
    const deps = makeDeps();
    (deps.agent.forward as any).mockResolvedValue({
      answer: 'JWT auth',
      confidence: 'high',
    });

    const result = await handleAsk({ question: 'how does auth work?' }, deps);
    const parsed = JSON.parse(result.content[0].text);

    expect(parsed.answer).toBe('JWT auth');
    expect(parsed.confidence).toBe('high');
    expect(parsed.traceIndex).toBe(1);
    expect(deps.traceCounter).toBe(1);
  });
});

describe('handleFeedback', () => {
  it('adds feedback to the latest trace when no traceIndex given', async () => {
    const deps = makeDeps();
    deps.traceCounter = 1;
    deps.traceIndex.set(1, 'trace-id-abc');
    (deps.agent.getTraces as any).mockResolvedValue([{ id: 'trace-id-abc' }]);

    const result = await handleFeedback({ score: 0, comment: 'wrong' }, deps);

    expect(deps.agent.addFeedback).toHaveBeenCalledWith('trace-id-abc', {
      score: 0,
      comment: 'wrong',
    });
    expect(result.isError).toBeFalsy();
  });

  it('returns error when no traces exist', async () => {
    const deps = makeDeps();
    const result = await handleFeedback({ score: 1 }, deps);
    expect(result.isError).toBe(true);
  });
});

describe('handleTraces', () => {
  it('returns formatted trace list', async () => {
    const deps = makeDeps();
    const now = new Date();
    (deps.agent.getTraces as any).mockResolvedValue([
      {
        id: 'trace-1',
        input: { question: 'auth?' },
        output: { answer: 'JWT', confidence: 'high' },
        startTime: now,
        durationMs: 100,
        feedback: { score: 1 },
      },
    ]);

    const result = await handleTraces({ limit: 5 }, deps);
    const parsed = JSON.parse(result.content[0].text);

    expect(parsed.traces).toHaveLength(1);
    expect(parsed.traces[0].question).toBe('auth?');
    expect(parsed.traces[0].score).toBe(1);
  });
});

describe('handleStatus', () => {
  it('returns session info', async () => {
    const deps = makeDeps();
    (deps.agent.getTraces as any).mockResolvedValue([
      { feedback: { score: 0.8 } },
      { feedback: { score: 0.6 } },
    ]);

    const result = await handleStatus(deps);
    const parsed = JSON.parse(result.content[0].text);

    expect(parsed.sessionId).toBe('session-123');
    expect(parsed.traceCount).toBe(2);
    expect(parsed.avgScore).toBeCloseTo(0.7);
  });
});

• Step 2: Run tests to verify they fail

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm --filter @moltnet/tools vitest run src/legreffier-local/__tests__/tools.test.ts
Expected: FAIL — handler functions don't exist.

• Step 3: Implement tool handlers and registration

/**
 * Legreffier Local MCP — Tool handlers + registration
 */

import { Type, type Static } from '@sinclair/typebox';
import type { FastifyInstance } from 'fastify';

import type { LocalMcpDeps } from './types.js';

// ── Schemas ───────────────────────────────────────────

export const AskSchema = Type.Object({
  question: Type.String({ description: 'Question about the codebase.' }),
  codeContext: Type.Optional(
    Type.String({
      description: 'Relevant code snippet or file content for context.',
    }),
  ),
});

export const FeedbackSchema = Type.Object({
  traceIndex: Type.Optional(
    Type.Integer({
      description: 'Trace index from this session (default: latest).',
    }),
  ),
  score: Type.Number({
    description: 'Quality score: 0 = bad, 1 = good.',
    minimum: 0,
    maximum: 1,
  }),
  label: Type.Optional(
    Type.String({ description: 'Short label (e.g. "wrong-scope").' }),
  ),
  comment: Type.Optional(Type.String({ description: 'Detailed feedback.' })),
});

export const TracesSchema = Type.Object({
  limit: Type.Optional(
    Type.Integer({
      description: 'Max traces to return (default: 5).',
      minimum: 1,
      maximum: 50,
    }),
  ),
});

export const OptimizeSchema = Type.Object({
  budget: Type.Optional(
    Type.Integer({
      description: 'Max optimization rounds (default: 5).',
      minimum: 1,
      maximum: 20,
    }),
  ),
});

export const StatusSchema = Type.Object({});

type AskInput = Static<typeof AskSchema>;
type FeedbackInput = Static<typeof FeedbackSchema>;
type TracesInput = Static<typeof TracesSchema>;
type OptimizeInput = Static<typeof OptimizeSchema>;

// ── Result helpers ────────────────────────────────────

interface CallToolResult {
  content: Array<{ type: 'text'; text: string }>;
  isError?: boolean;
}

function textResult(data: unknown): CallToolResult {
  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
}

function errorResult(message: string): CallToolResult {
  return {
    content: [{ type: 'text', text: JSON.stringify({ error: message }) }],
    isError: true,
  };
}

// ── Handlers ──────────────────────────────────────────

export async function handleAsk(
  args: AskInput,
  deps: LocalMcpDeps,
): Promise<CallToolResult> {
  deps.lastActivity = Date.now();

  try {
    const result = await deps.agent.forward(deps.studentAi, {
      question: args.question,
      codeContext: args.codeContext,
    });

    // Get the trace that was just created
    const traces = await deps.agent.getTraces({ limit: 1 });
    const latestTrace = traces[0];

    deps.traceCounter++;
    if (latestTrace) {
      deps.traceIndex.set(deps.traceCounter, latestTrace.id);
    }

    return textResult({
      answer: result.answer,
      confidence: result.confidence,
      traceIndex: deps.traceCounter,
    });
  } catch (err) {
    deps.logger.error({ err }, 'legreffier_ask failed');
    return errorResult(
      err instanceof Error ? err.message : 'Forward call failed',
    );
  }
}

export async function handleFeedback(
  args: FeedbackInput,
  deps: LocalMcpDeps,
): Promise<CallToolResult> {
  deps.lastActivity = Date.now();

  const targetIndex = args.traceIndex ?? deps.traceCounter;
  const traceId = deps.traceIndex.get(targetIndex);

  if (!traceId) {
    return errorResult(
      `No trace found at index ${targetIndex}. Run legreffier_ask first.`,
    );
  }

  const feedback: { score?: number; label?: string; comment?: string } = {
    score: args.score,
  };
  if (args.label) feedback.label = args.label;
  if (args.comment) feedback.comment = args.comment;

  try {
    await deps.agent.addFeedback(traceId, feedback);
    return textResult({
      success: true,
      traceIndex: targetIndex,
      feedback,
    });
  } catch (err) {
    deps.logger.error({ err }, 'legreffier_feedback failed');
    return errorResult(err instanceof Error ? err.message : 'Feedback failed');
  }
}

export async function handleTraces(
  args: TracesInput,
  deps: LocalMcpDeps,
): Promise<CallToolResult> {
  deps.lastActivity = Date.now();

  const traces = await deps.agent.getTraces({ limit: args.limit ?? 5 });

  const formatted = traces.map((t, i) => ({
    index: deps.traceCounter - i,
    question: (t.input as Record<string, unknown>).question,
    answer: truncate(
      String((t.output as Record<string, unknown>).answer ?? ''),
      100,
    ),
    confidence: (t.output as Record<string, unknown>).confidence,
    score: t.feedback?.score ?? null,
    label: t.feedback?.label ?? null,
    durationMs: t.durationMs,
    time: t.startTime,
  }));

  return textResult({ traces: formatted });
}

export async function handleOptimize(
  args: OptimizeInput,
  deps: LocalMcpDeps,
): Promise<CallToolResult> {
  deps.lastActivity = Date.now();
  deps.logger.info('Starting optimization...');

  try {
    const result = await deps.agent.optimize({
      budget: args.budget,
    });

    return textResult({
      score: result.score,
      improvement: result.improvement,
      checkpointVersion: result.checkpointVersion,
      stats: result.stats,
    });
  } catch (err) {
    deps.logger.error({ err }, 'legreffier_optimize failed');
    return errorResult(
      err instanceof Error ? err.message : 'Optimization failed',
    );
  }
}

export async function handleStatus(
  deps: LocalMcpDeps,
): Promise<CallToolResult> {
  deps.lastActivity = Date.now();

  const traces = await deps.agent.getTraces({ limit: 100 });
  const scores = traces
    .map((t) => t.feedback?.score)
    .filter((s): s is number => s !== undefined);
  const avgScore =
    scores.length > 0
      ? scores.reduce((a, b) => a + b, 0) / scores.length
      : null;

  const instruction = deps.agent.getGen().getInstruction();

  return textResult({
    sessionId: deps.sessionId,
    traceCount: traces.length,
    tracesWithFeedback: scores.length,
    avgScore,
    currentInstruction: instruction ? truncate(instruction, 200) : null,
    uptimeSeconds: Math.round((Date.now() - deps.startTime) / 1000),
  });
}

// ── Registration ──────────────────────────────────────

export function registerTools(
  fastify: FastifyInstance,
  deps: LocalMcpDeps,
): void {
  fastify.mcpAddTool(
    {
      name: 'legreffier_ask',
      description:
        'Ask a question about the codebase. The answer is traced and can receive feedback for self-improvement.',
      inputSchema: AskSchema,
    },
    async (args: AskInput) => handleAsk(args, deps),
  );

  fastify.mcpAddTool(
    {
      name: 'legreffier_feedback',
      description:
        'Give feedback on a previous answer. Score 0-1 (0=bad, 1=good). Targets latest trace by default.',
      inputSchema: FeedbackSchema,
    },
    async (args: FeedbackInput) => handleFeedback(args, deps),
  );

  fastify.mcpAddTool(
    {
      name: 'legreffier_traces',
      description:
        'List recent traces (questions + answers + scores) from this session.',
      inputSchema: TracesSchema,
    },
    async (args: TracesInput) => handleTraces(args, deps),
  );

  fastify.mcpAddTool(
    {
      name: 'legreffier_optimize',
      description:
        'Run batch optimization. Teacher model reviews traces with feedback and produces an improved checkpoint.',
      inputSchema: OptimizeSchema,
    },
    async (args: OptimizeInput) => handleOptimize(args, deps),
  );

  fastify.mcpAddTool(
    {
      name: 'legreffier_status',
      description:
        'Show session status: trace count, avg score, checkpoint info.',
      inputSchema: StatusSchema,
    },
    async () => handleStatus(deps),
  );
}

function truncate(s: string, max: number): string {
  return s.length <= max ? s : s.slice(0, max - 3) + '...';
}

• Step 4: Run tests to verify they pass

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm --filter @moltnet/tools vitest run src/legreffier-local/__tests__/tools.test.ts
Expected: All tests PASS.

• Step 5: Commit

git add tools/src/legreffier-local/tools.ts tools/src/legreffier-local/__tests__/tools.test.ts
git commit -m "feat(legreffier-local): add MCP tool handlers with tests"

Task 7: Create server entry point

Files:

• Create: tools/src/legreffier-local/main.ts

• Step 1: Write server entry point

#!/usr/bin/env -S npx tsx
/**
 * Legreffier Local MCP Server
 *
 * A local MCP server that wraps AxLearn with diary-backed storage
 * for self-improving codebase Q&A.
 *
 * Usage:
 *   pnpm legreffier-local
 *
 * Environment:
 *   MOLTNET_API_URL    — REST API base URL (default: http://localhost:8000)
 *   MOLTNET_DIARY_ID   — Diary UUID for storage (required)
 *   MOLTNET_TOKEN      — Bearer token for API auth (required)
 *   LEGREFFIER_PORT    — SSE port (default: 0 = random)
 *   LEGREFFIER_TEACHER — Teacher model (default: claude-opus-4-6)
 *   LEGREFFIER_STUDENT — Student model (default: claude-sonnet-4-6)
 *   LEGREFFIER_IDLE_MS — Idle timeout in ms (default: 7200000 = 2h)
 */

import { randomUUID } from 'node:crypto';

import mcpPlugin from '@getlarge/fastify-mcp';
import { createClient } from '@moltnet/api-client';
import Fastify from 'fastify';

import { createAgent } from './agent.js';
import { registerTools } from './tools.js';
import type { LocalMcpDeps, ServerConfig } from './types.js';

function loadConfig(): ServerConfig {
  const diaryId = process.env.MOLTNET_DIARY_ID;
  const bearerToken = process.env.MOLTNET_TOKEN;

  if (!diaryId) {
    console.error('MOLTNET_DIARY_ID is required');
    process.exit(1);
  }
  if (!bearerToken) {
    console.error('MOLTNET_TOKEN is required');
    process.exit(1);
  }

  return {
    apiBaseUrl: process.env.MOLTNET_API_URL ?? 'http://localhost:8000',
    diaryId,
    bearerToken,
    port: parseInt(process.env.LEGREFFIER_PORT ?? '0', 10),
    teacherModel: process.env.LEGREFFIER_TEACHER ?? 'claude-opus-4-6',
    studentModel: process.env.LEGREFFIER_STUDENT ?? 'claude-sonnet-4-6',
    idleTimeoutMs: parseInt(process.env.LEGREFFIER_IDLE_MS ?? '7200000', 10),
  };
}

async function main(): Promise<void> {
  const config = loadConfig();
  const sessionId = randomUUID();

  const app = Fastify({ logger: { level: 'info' } });

  // Health check
  app.get('/healthz', () => ({ status: 'ok', sessionId }));

  // Register MCP plugin (no auth)
  await app.register(mcpPlugin, {
    serverInfo: { name: 'legreffier-local', version: '0.1.0' },
    capabilities: { tools: {} },
    enableSSE: true,
    sessionStore: 'memory',
    authorization: { enabled: false },
  });

  // Create API client + agent
  const client = createClient({ baseUrl: config.apiBaseUrl });
  const { agent, gen, studentAi } = createAgent(config, sessionId, client);

  // Build deps
  const deps: LocalMcpDeps = {
    agent,
    gen,
    studentAi,
    client,
    config,
    logger: app.log,
    sessionId,
    traceCounter: 0,
    traceIndex: new Map(),
    lastActivity: Date.now(),
    startTime: Date.now(),
  };

  // Register tools
  registerTools(app, deps);

  // Start server
  const address = await app.listen({ port: config.port, host: '127.0.0.1' });
  app.log.info({ address, sessionId }, 'Legreffier local MCP server started');

  // Idle shutdown timer
  const idleCheck = setInterval(() => {
    if (Date.now() - deps.lastActivity > config.idleTimeoutMs) {
      app.log.info('Idle timeout reached, shutting down');
      clearInterval(idleCheck);
      app.close();
    }
  }, 60_000);

  // Graceful shutdown
  const shutdown = async () => {
    clearInterval(idleCheck);
    app.log.info('Shutting down...');
    await app.close();
    process.exit(0);
  };

  process.on('SIGINT', shutdown);
  process.on('SIGTERM', shutdown);
}

main().catch((err) => {
  console.error('Failed to start:', err);
  process.exit(1);
});

• Step 2: Verify it compiles

Run: cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp && pnpm --filter @moltnet/tools run typecheck
Expected: No type errors.

• Step 3: Commit

git add tools/src/legreffier-local/main.ts
git commit -m "feat(legreffier-local): add MCP server entry point with idle shutdown"

---

Chunk 4: Integration Testing + Claude Code Registration

Task 8: Manual smoke test against local dev

Files:

• No new files — this is a verification step.

Prerequisites: Docker Compose stack running (docker compose --env-file .env.local up -d), a diary + bearer token available.

• Step 1: Start the server manually

cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp
MOLTNET_DIARY_ID=<your-diary-id> MOLTNET_TOKEN=<your-token> pnpm legreffier-local

Expected: Server starts, prints address + session ID.

• Step 2: Test health endpoint

curl http://127.0.0.1:<port>/healthz

Expected: {"status":"ok","sessionId":"..."}

• Step 3: Test MCP tool list via SSE

curl http://127.0.0.1:<port>/mcp -H 'Accept: text/event-stream'

Expected: SSE stream with MCP protocol. Tools should be discoverable via tools/list.

Task 9: Register in Claude Code settings

Files:

• Note: .claude/settings.json is user-local, do not commit. Document the config in the research doc.

• Step 1: Document MCP registration

Add to docs/research/local-context-packs-axrag-self-improvement.md:

// Add to .claude/settings.json (user-local, not committed)
{
  "mcpServers": {
    "legreffier-local": {
      "args": ["tsx", "tools/src/legreffier-local/main.ts"],
      "command": "npx",
      "cwd": "/path/to/themoltnet",
      "env": {
        "MOLTNET_API_URL": "http://localhost:8000",
        "MOLTNET_DIARY_ID": "<your-diary-id>",
        "MOLTNET_TOKEN": "<your-token>"
      }
    }
  }
}

• Step 2: Commit docs update

git add docs/research/local-context-packs-axrag-self-improvement.md
git commit -m "docs: add Claude Code MCP registration instructions"

Task 10: Run all tests + final verification

• Step 1: Run full test suite

cd /Users/edouard/Dev/getlarge/themoltnet/.worktrees/spike-legreffier-local-mcp
pnpm --filter @moltnet/tools vitest run src/legreffier-local/

Expected: All unit tests pass.

• Step 2: Run typecheck

pnpm --filter @moltnet/tools run typecheck

Expected: No type errors.

• Step 3: Run lint

pnpm --filter @moltnet/tools run lint

Expected: No lint errors (or only pre-existing ones).

• Step 4: Final commit if needed

git add -A
git commit -m "chore(legreffier-local): fix lint/type issues from final review"

[legreffier]

Spike observations & next steps (2026-03-20)

What works

• stdio + SSE transport, Claude Code integration via .mcp.json
• Diary-backed trace/checkpoint storage (AxStorage adapter)
• Identity/soul context injection at startup
• Diary search enrichment for legreffier_ask (entries.search → codeContext)
• Feedback loop: ask → feedback → traces stored as diary entries
• libs/ax-agents extracted — adapters accept env injection, no context-evals dependency

What doesn't work (yet)

• AxLearn optimize() — hangs indefinitely with the Claude Agent SDK teacher. Added a timeout but never saw a successful optimization run. The core self-improvement claim is unverified.
• axRAG multi-hop — @ax-llm/ax@19.0.13 has an internal bug where currentContext field is not populated when context is empty, crashing the quality assessor.
• AxDefaultResultReranker — i.match is not a function parsing error in ax-llm internals.
• entries.search with filters — entryTypes/excludeTags/weight params cause 404 on prod (works in local e2e). Environment-specific, not a code bug.

Key insight from pi-self-learning

Studied mcollina/pi-self-learning — a pi extension that captures agent failures/fixes automatically:

What they do well:

• Intercept interruption signals (blocked commands, permission denials, user aborts) from the session branch
• Score learnings by score - (ageDays * 0.05) with repetition bonus 1 + min(1, hits * 0.08)
• Reflection prompt: "focus on what went wrong and how it was fixed, NOT accomplishments"
• Mistakes → anti-patterns, Fixes → learnings, top N by score injected into system prompt
• Runs automatically after every task (agent_end event)

What they don't do:

• No verification that learnings actually improve performance
• No eval generation from session traces
• Pure memory accumulation — trusts that reflections are useful

The gap both systems share: no closed loop proving that learned context improves outcomes.

Questions to resolve before this graduates from spike

1. Can we capture interruption signals in Claude Code / Codex? Pi has privileged runtime access (ctx.sessionManager.getBranch()). We don't. Hooks (Stop, PreToolUse) fire but don't expose the conversation branch. A universal solution needs an agent SDK hook like onToolError(toolName, error, context) that neither Claude Code nor Codex exposes today.

2. How to wire sessions to the self-learning system with minimal human interaction? Options:

   • Claude Code Stop hook → triggers reflection prompt → extracts mistakes/fixes → stores as scored diary entries
   • MCP notifications/cancelled → legreffier-local detects aborted tool calls
   • Periodic self-assessment: after N tool calls, agent auto-evaluates recent traces
   • Piggyback on /handoff: the legreffier skill already runs at session end

3. How to turn traces into reliable eval tasks? A trace with {question, context_available, bad_answer, correction} is a candidate eval. But verifying it requires proving the correction is actually better WITH the right context — chicken-egg with GEPA.

4. Should we drop AxLearn and build simpler? Pi's approach is just: reflect → score → inject top N into prompt. No optimization loop, no teacher model, no checkpoints. Simpler, proven to at least accumulate useful memories. AxLearn's promise is stronger (actual prompt optimization) but unproven in our setup.

PR status

Branch: spike/legreffier-local-mcp-418 — infrastructure works, self-improvement loop doesn't. Useful as plumbing for whatever approach we choose next.

[getlarge]

Complementary Codex-specific observations after testing the local Codex CLI surface:

• Codex CLI currently does not appear to expose repo-defined slash commands or a first-class hook system comparable to Claude Code hooks. ~/.codex/config.toml exposes project trust / model config, but nothing like Stop, PreToolUse, or task-end callbacks.
• Skills are not a runtime extension point. They are instruction bundles that shape agent behavior when invoked, but they cannot trap task interruption, user abort, or tool failure events on their own.
• The important boundary for us is not POSIX SIGINT that kills the whole process, but "the user interrupted this task / changed course". Codex does not seem to expose that event as a programmable callback. That means we should not build a design that assumes reliable automatic capture of interrupted-task state.
• This limitation actually strengthens the human-in-the-loop argument. When a task is interrupted, intent is ambiguous: the user may have seen drift, danger, partial success, or simply changed priorities. Treating interruption as a safe stop + explicit human decision is the defensible default.

What still looks viable in Codex:

• Emulate a slash command with a wrapper command such as mx incident, mx oops, or mx learn. This can call codex exec with a dedicated prompt/skill specialized in condensing failure context into a structured diary entry.
• The wrapper can gather deterministic context before invoking Codex: cwd, branch, dirty files, recent diff summary, failing command + stderr, optional free-text from the human.
• The specialist agent should output structured fields rather than prose-first notes: entry_type, title, symptoms, trigger, attempts, resolution, confidence, affected_paths, tags, resume_hint, pack_candidate. This will matter later when clustering entries into context packs.
• In Codex, the likely interaction model is: human notices something notable -> runs explicit capture command -> Codex condenses -> diary entry is stored -> consolidation later promotes repeated high-signal entries into injectable nuggets/context packs.

Net: Codex seems better suited to explicit failure-capture commands than implicit interruption hooks. That is probably the right abstraction anyway, because it gives us a durable human signal that the event was worth learning from.

[legreffier]

legreffier flag — context-aware incident capture (2026-03-20)

Design

Extend @themoltnet/legreffier CLI (TypeScript, Ink) with a non-interactive flag subcommand. The calling agent is smart — it dumps relevant context. The ax agent under the hood structures it into diary entries.

Interface

# Pipe context from the calling agent (preferred — allows large context)
echo "<agent dumps relevant conversation fragments, errors, diffs, corrections>" | \
  legreffier flag --name legreffier

# Via file (for very large context)
legreffier flag --name legreffier --input /tmp/incident.md

# Inline for quick captures
legreffier flag --name legreffier "missed Go client regen after OpenAPI change"

# Configure the ax agent adapter powering the structuring
legreffier flag --name legreffier --model claude-agent-sdk  # default
legreffier flag --name legreffier --model codex-agent-sdk

# Aliases
legreffier oops ...
legreffier incident ...

Under the hood

1. Read context from stdin / --input / positional arg
2. Resolve credentials from .moltnet/<name>/moltnet.json
3. Resolve diary from repo name (same as legreffier-mcp startup)
4. Pass raw dump to an AxGen agent powered by @moltnet/ax-agents (configurable adapter)

Ax signature:

context:string "Raw dump — errors, diffs, conversation fragments, corrections"
→ whatHappened:string, rootCause:string, fix:string, watchFor:string, 
  tags:string[], severity:class "low, medium, high",
  affectedPaths:string[], packCandidate:boolean

5. Create diary entries:
   • episodic (the incident): whatHappened + rootCause
   • semantic (the learning): fix + watchFor (only if fix extracted)
   • Both tagged: flag:incident, flag:session:<timestamp>, branch:<branch>, scope:<...>
6. Print entry IDs to stdout (for the calling agent to reference in commits)

Code sharing with legreffier-mcp

The structuring logic lives in a shared module importable by both:

• packages/legreffier-cli/ — CLI wrapper (parseArgs → stdin → flag core → stdout)
• apps/legreffier-mcp/ (renamed from legreffier-local) — MCP tool wrapper (legreffier_flag tool → flag core → MCP result)

Both use @moltnet/ax-agents for the LLM call, @themoltnet/sdk for diary access.

Pack extraction

All flagged entries share flag:incident tag. Pack generator:

1. entries.list({ tags: 'flag:incident' })
2. Check each has a linked semantic entry (the learning)
3. Verify via provenance (entry relations + content signatures) that the learning addresses the incident
4. Bundle into packs — high-frequency incidents become high-priority context

Why this is the right HITL entry point

Per the Codex analysis above: automatic interruption capture is unreliable across agent CLIs. The defensible default is explicit human action: "this was worth learning from." The flag command is that action — minimal friction (pipe or one-liner), maximum context (the calling agent provides everything), and the structuring is automated (ax agent, not manual fields).

This is step 1 of the flywheel: Spot → Capture. Steps 2-4 (Structure eval → Score → Integrate) build on having clean, tagged, provenance-linked incident entries.

[legreffier]

Agent observability as input spec for legreffier flag (2026-03-20)

From a post on agent observability — this defines what the calling agent must dump and what the ax agent must extract:

1. What context did the agent see when it made the decision?
2. What tools could it call, and which did it choose?
3. What guardrails stopped bad outcomes?
4. What trace explains the decision?

What the calling agent should include in its dump

The main agent (Claude, Codex, etc.) has all four dimensions at flag time:

1. Context seen — files read, search results, diary entries injected. If it missed a key file, that's the root cause.
2. Tool choices — recent tool calls, especially repeated/failed ones. Five retries = confusion signal.
3. Guardrail events — the human's correction + any permission denials, aborted actions, redirections.
4. Decision trace — reasoning chain that led to the bad output. Key decision points, alternatives considered.

Ax signature (structured output builder)

import { ax, f } from '@ax-llm/ax';

const flagSig = f()
  .input('context', f.string('Raw dump: files seen, tool calls, errors, diffs, conversation fragments').min(10).max(50000))
  .input('problem', f.string('Human description of what went wrong').min(5).max(2000))
  .input('solution', f.string('Human correction or fix, if known').max(2000).optional())
  .output('incident', f.object({
    whatHappened: f.string('What the agent did wrong').min(10).max(1000),
    rootCause: f.string('Why — was context stale/missing? Tool confusion? Wrong assumption?').min(10).max(1000),
    contextGap: f.string('What context was missing or stale that caused this').max(500).optional(),
    toolPattern: f.string('Tool call pattern that reveals the confusion, if any').max(500).optional(),
  }))
  .output('learning', f.object({
    fix: f.string('What should happen instead').min(10).max(1000),
    watchFor: f.string('Prevention rule for future sessions').min(10).max(500),
    scope: f.class(['file', 'module', 'project', 'cross-project']),
  }))
  .output('meta', f.object({
    severity: f.class(['low', 'medium', 'high']),
    affectedPaths: f.string().min(1).max(200).array(),
    tags: f.string().min(2).max(50).array(),
    packCandidate: f.class(['yes', 'no']),
  }));

const flagAgent = ax(flagSig.build());

The ax agent interprets the human's correction in light of the agent's decision trace. "You missed the Go client" + seeing the tool only called pnpm generate:openapi (dim 2) without reading cmd/moltnet-api-client/ (dim 1) = structured root cause, not transcription.

Each dimension feeds a different downstream consumer

• Context gaps (dim 1) → context pack improvements (pack should have included X)
• Tool patterns (dim 2) → skill/instruction improvements (agent should try X before Y)
• Human corrections (dim 3) → eval candidates (baseline = bad action, expected = correction)
• Decision traces (dim 4) → provenance for verification (was the learning applied later? did it help?)

[legreffier]

legreffier flag — two-call CLI pattern (2026-03-20)

Universal across Claude Code, Codex, and any agent that can run shell commands. No skills, no hooks, no agent-specific wiring.

First call: agent discovers what's needed

$ npx @themoltnet/legreffier flag

Returns (stdout — the agent reads this):

To report an incident, gather the following from your current session:

1. Files you read or modified in your recent actions
2. Tool calls that failed, were retried, or were interrupted
3. Your reasoning: why you chose this approach over alternatives
4. The human's correction, complaint, or frustration

Then call again with context:

  echo "<gathered context>" | npx @themoltnet/legreffier flag --name <agent-name>

  npx @themoltnet/legreffier flag --name <agent-name> --input <file>

  npx @themoltnet/legreffier flag --name <agent-name> "<short description>"

Options:
  --name <agent-name>    Agent identity (resolves credentials from .moltnet/<name>/)
  --input <file>         Read context from file instead of stdin
  --model <adapter>      Ax agent adapter: claude-agent-sdk (default), codex-agent-sdk
  --dir <path>           Project directory (default: cwd)

Aliases: legreffier oops, legreffier incident

No API call, no auth, no agent name needed. Like --help but written for an LLM to act on.

Second call: agent dumps context

$ echo "I was asked to regenerate the API client after changing the OpenAPI spec.
I ran pnpm generate:openapi which updated libs/api-client/src/generated/.
I did not check cmd/moltnet-api-client/ because I didn't know a Go client existed.
The human said: both TS and Go clients must always be regenerated.
Files read: libs/api-client/package.json, apps/rest-api/src/routes/diary-entries.ts
Failed tools: none, but the Go client was silently stale." | \
  npx @themoltnet/legreffier flag --name legreffier

Output:

Created entries:
  episodic: abc123 — "Missed Go client regeneration after OpenAPI change"
  semantic: def456 — "After OpenAPI changes, always regenerate both TS and Go clients"
  tags: flag:incident, branch:feat/openapi-update, scope:codegen
  relations: abc123 ──derived_from──→ def456

Why this works across agents

• Claude Code: agent sees npx @themoltnet/legreffier flag fail/return instructions → gathers context → calls again with pipe. Same pattern as any CLI tool it learns to use.
• Codex: mx flag wrapper or direct npx call → same two-step.
• Any future agent: if it can run a shell command and read stdout, it can learn the protocol.

The tool teaches its own usage on first call. The agent provides the four observability dimensions (context seen, tool choices, guardrails, decision trace) because the instructions ask for them. The ax agent under the hood structures the raw dump into diary entries.

MCP equivalent

legreffier_flag MCP tool in legreffier-mcp has the same ax agent logic but skips the two-call dance — the tool description tells the main agent what to include upfront. Shared core between CLI and MCP.

Entry relations for provenance

A flag session creates 2+ entries. Entry relations (API in progress) link them structurally:

episodic (what happened) ──derived_from──→ semantic (the learning)
                         ──derived_from──→ procedural (the fix steps, if any)

This enables:

• Pack extraction: follow relations to verify a learning has its source incident attached
• Eval extraction: pull the full chain — incident → learning → was it applied later?
• Consolidation: cluster related flag sessions by relation graphs

The flag:session:<timestamp> tag groups entries loosely, but relations make it structural and queryable via the API.

Note: the server doesn't have a built-in pack type that uses relations. This would be a client-side custom packType — an agent (potentially trained via AxLearn) that follows relations to pick entries and assemble packs. The server provides the relation graph and entries; the pack assembly logic lives in the client, where it can evolve with the agent's improving judgment about what constitutes a useful incident→learning bundle.