Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,10 @@
## 0.2.3 (2026-10-09)

- Send the memory snapshot only when the retained context lacks it: an unchanged snapshot is no longer repeated every turn, a new recall rides alone, and an empty memory with nothing to revoke sends nothing.
- Never return `systemPrompt` from `before_agent_start`. Pi treats any returned prompt, even an unchanged one, as a forced prompt for that turn only.

## 0.2.2 (2026-10-07)

## 0.2.0 (2026-10-06)

- Remove semantic reranking, classifier curation, turn judging and credential setup.
Expand Down
130 changes: 119 additions & 11 deletions package-lock.json

Large diffs are not rendered by default.

6 changes: 3 additions & 3 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@prjct.app/pi-memory",
"version": "0.2.1",
"version": "0.2.3",
"description": "Pi-native temporal memory and hybrid retrieval for agents.",
"type": "module",
"keywords": [
Expand Down Expand Up @@ -45,13 +45,13 @@
},
"dependencies": {
"@huggingface/transformers": "4.3.0",
"@prjct.app/pi-secrets": "^0.2.1",
"@prjct.app/pi-secrets": "^0.2.6",
"@prjct.app/pi-tui-kit": "^0.3.4",
"sqlite-vec": "0.1.9",
"tsx": "^4.20.0"
},
"peerDependencies": {
"@earendil-works/pi-ai": "*",
"@earendil-works/pi-ai": ">=1.0.4",
"@earendil-works/pi-coding-agent": "*",
"@earendil-works/pi-tui": "*",
"typebox": "*"
Expand Down
7 changes: 2 additions & 5 deletions src/curation/analyzer.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
import type { Api, AssistantMessage, Model } from '@earendil-works/pi-ai';
import { contentText, type Api, type Model } from '@earendil-works/pi-ai';
import { ModelRuntime } from '@earendil-works/pi-coding-agent';
import { CurationBlockError, type AnalysisResult, type Analyzer, type EvidenceBundle } from './types.ts';
import { extractJsonObject, parseProposal } from './validate.ts';
Expand Down Expand Up @@ -37,9 +37,6 @@ Rules:
- Never assign provenance. The publisher derives it from the source boundary; you are not a host observer.
- Preserve the source language, meaning, qualifications and force. Quote the source verbatim in excerpt; excerpts are evidence and are never translated.`;

const textOf = (message: AssistantMessage): string =>
message.content.flatMap(block => 'type' in block && block.type === 'text' && 'text' in block ? [String(block.text)] : []).join('\n');

const bundlePrompt = (bundle: EvidenceBundle): string => JSON.stringify({
identity: bundle.identity,
currentTopic: bundle.currentTopic ?? null,
Expand All @@ -66,7 +63,7 @@ export const createSdkAnalyzer = async (options: Readonly<{
if (message.stopReason === 'error' || message.stopReason === 'aborted') {
throw new Error(message.errorMessage || `Analysis ${message.stopReason}.`);
}
const output = textOf(message);
const output = contentText(message.content);
if (Buffer.byteLength(output, 'utf8') > maxOutputChars) throw new Error('Analysis output exceeded the size limit.');
const proposal = parseProposal(extractJsonObject(output), bundle);
return {
Expand Down
7 changes: 2 additions & 5 deletions src/curation/curator.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
import type { Api, AssistantMessage, Model } from '@earendil-works/pi-ai';
import { contentText, type Api, type Model } from '@earendil-works/pi-ai';
import { ModelRuntime } from '@earendil-works/pi-coding-agent';
import { createHash } from 'node:crypto';
import { mkdir, readFile, readdir, stat, writeFile } from 'node:fs/promises';
Expand Down Expand Up @@ -45,9 +45,6 @@ Return ONLY a JSON object: {"actions":[...]}. Each action is one of:
If an added rule refines an existing one, supersede the existing rule by the new one's position instead of keeping both: add it, then supersede the old id with "by":"new".
Leave every other rule alone. Never invent a rule. Prefer fewer actions when unsure.`;

const textOf = (message: AssistantMessage): string =>
message.content.flatMap(block => 'type' in block && block.type === 'text' && 'text' in block ? [String(block.text)] : []).join('\n');

/** Only actions about rules that were shown, with the fields each op needs. */
export const parseCuration = (value: unknown, rules: readonly Rule[], userMessages: readonly string[] = []): CurationAction[] => {
const ids = new Set(rules.map(rule => rule.id));
Expand Down Expand Up @@ -95,7 +92,7 @@ export const createSdkCurator = async (options: Readonly<{ provider: string; mod
messages: [{ role: 'user', content: JSON.stringify(await protectOutboundData({ rules, userMessages })), timestamp: Date.now() }],
}, { maxTokens: Math.min(model.maxTokens, 32768), reasoning: 'high', ...(signal === undefined ? {} : { signal }) });
if (message.stopReason === 'error' || message.stopReason === 'aborted') throw new Error(message.errorMessage || `Curation ${message.stopReason}.`);
return parseCuration(extractJsonObject(textOf(message)), rules, userMessages);
return parseCuration(extractJsonObject(contentText(message.content)), rules, userMessages);
},
};
};
Expand Down
7 changes: 2 additions & 5 deletions src/curation/translator.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
import type { Api, AssistantMessage, Model } from '@earendil-works/pi-ai';
import { contentText, type Api, type Model } from '@earendil-works/pi-ai';
import { ModelRuntime } from '@earendil-works/pi-coding-agent';

/**
Expand All @@ -24,9 +24,6 @@ Rules:
prohibition, a preference stays a preference.
- If the input is already English, return it unchanged.`;

const textOf = (message: AssistantMessage): string =>
message.content.flatMap(block => 'type' in block && block.type === 'text' && 'text' in block ? [String(block.text)] : []).join('\n');

export class TranslationUnavailableError extends Error {
constructor(message: string) {
super(message);
Expand All @@ -44,7 +41,7 @@ const complete = async (
if (message.stopReason === 'error' || message.stopReason === 'aborted') {
throw new TranslationUnavailableError(message.errorMessage || `Translation ${message.stopReason}.`);
}
const output = textOf(message).trim();
const output = contentText(message.content).trim();
// A translation that comes back empty, or wildly longer than its input, is
// the model having answered the sentence instead of translating it.
if (!output || output.length > Math.max(400, text.length * 3)) {
Expand Down
7 changes: 2 additions & 5 deletions src/eval/answer.ts
Original file line number Diff line number Diff line change
@@ -1,14 +1,11 @@
import { protectOutboundData } from '@prjct.app/pi-secrets/privacy';
import type { Api, AssistantMessage, Model } from '@earendil-works/pi-ai';
import { contentText, type Api, type Model } from '@earendil-works/pi-ai';
import { ModelRuntime } from '@earendil-works/pi-coding-agent';
import { CurationBlockError } from '../curation/types.ts';
import type { AnswerProvider, AnswerRequest, AnswerResult } from './comparison.ts';

const SYSTEM = 'Answer only from the provided evidence and prior facts. Quote supporting excerpts. Do not invent claims.';

const textOf = (message: AssistantMessage): string =>
message.content.flatMap(block => 'type' in block && block.type === 'text' && 'text' in block ? [String(block.text)] : []).join('\n');

export const createSdkAnswerProvider = async (options: Readonly<{
provider: string; model: string; maxOutputChars?: number;
}>): Promise<AnswerProvider> => {
Expand All @@ -32,7 +29,7 @@ export const createSdkAnswerProvider = async (options: Readonly<{
if (message.stopReason === 'error' || message.stopReason === 'aborted') {
return { text: '', inputTokens: message.usage?.input ?? 0, outputTokens: message.usage?.output ?? 0, failed: true };
}
const text = textOf(message).slice(0, maxOutputChars);
const text = contentText(message.content).slice(0, maxOutputChars);
return {
text,
inputTokens: message.usage?.input ?? Math.ceil(request.evidence.length / 4),
Expand Down
58 changes: 36 additions & 22 deletions src/extension/hooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,11 @@ import { mkdir, realpath, writeFile } from 'node:fs/promises';
import { homedir, tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
import { contentText } from '@earendil-works/pi-ai';
import type { EvidenceRef } from '../contracts/evidence.ts';
import { factIsValidAt, type MemoryKind } from '../contracts/memory.ts';
import { renderMemoryEnvelope, type MemoryEnvelope } from '../handoff/memory-envelope.ts';
import { unseenMemory, type MemoryEnvelope } from '../handoff/memory-envelope.ts';
import type { HandoffMessage } from '../handoff/turns.ts';
import { hostEvidence, MemoryEngine } from '../engine.ts';
import type { EmbeddingProvider } from '../vector/providers.ts';
import { CORE_DIGEST_BYTES, CORE_KINDS, memoryDigest, memoryStatusLine } from './digest.ts';
Expand Down Expand Up @@ -95,6 +97,8 @@ export const recallQueries = (prompt: string): string[] => {
const NOT_INITIALIZED = /not initialized/iu;
/** Facts considered for the digest; far more than fit its byte budget. */
const DIGEST_SCAN_LIMIT = 500;
/** The revision of an empty snapshot; a context without any snapshot holds the same. */
const EMPTY_REVISION = sha256('');
export const isNotInitialized = (error: unknown): boolean => error instanceof Error && NOT_INITIALIZED.test(error.message);

const retainedJson = (value: unknown): string => JSON.stringify(value)
Expand Down Expand Up @@ -410,36 +414,46 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
const digest = memoryDigest(facts, Date.now(), CORE_DIGEST_BYTES, CORE_KINDS);
return { facts, digest, small: memoryDigest(facts).complete, revision: sha256(digest.block ?? '') };
};
const memoryMessage = (revision: string, block: string | undefined, recall?: string, items = 0, omitted = 0) => {
/** What the next request carries, compaction-aware. Fixtures without a session carry nothing. */
const retainedMessages = (ctx: ExtensionContext): readonly HandoffMessage[] => {
try { return ctx.sessionManager.buildSessionProjection?.().messages ?? []; } catch { return []; }
};
/**
* Only the part of the envelope the retained context lacks: an unchanged
* snapshot is not resent every turn, and an empty memory with no earlier
* snapshot to revoke sends nothing. Undefined when nothing is new.
*/
const memoryMessage = (ctx: ExtensionContext, revision: string, block: string | undefined, recall?: string, items = 0, omitted = 0) => {
const memory: MemoryEnvelope = { version: 1, revision,
snapshot: block ?? 'No eligible facts in this snapshot.', ...(recall ? { recall } : {}) };
return { customType: 'pi-memory-recall', content: renderMemoryEnvelope(memory), display: false,
details: { memory, items, omitted } };
const content = unseenMemory(retainedMessages(ctx), memory, EMPTY_REVISION);
if (content === undefined) return undefined;
return { customType: 'pi-memory-recall', content, display: false, details: { memory, items, omitted } };
};

/**
* Turns that start without a typed prompt (a self-compact handoff, a subagent
* result) never reach before_agent_start. After the window is rebuilt the core
* goes back in right away, so those turns do not run without the rules.
*/
const restoreCore = async (): Promise<void> => {
const restoreCore = async (ctx: ExtensionContext): Promise<void> => {
const current = get();
const project = await engine().catch(() => undefined);
if (!project || get().generation !== current.generation) return;
const { digest, revision } = coreSnapshot(project);
if (!digest.block) return;
pi.sendMessage(memoryMessage(revision, digest.block), { triggerTurn: false });
const message = memoryMessage(ctx, revision, digest.block);
if (message) pi.sendMessage(message, { triggerTurn: false });
};
pi.on('session_compact', async () => { await restoreCore().catch(() => undefined); });
pi.on('session_tree', async () => { await restoreCore().catch(() => undefined); });
pi.on('session_compact', async (_event, ctx) => { await restoreCore(ctx).catch(() => undefined); });
pi.on('session_tree', async (_event, ctx) => { await restoreCore(ctx).catch(() => undefined); });

pi.on('before_agent_start', async (event, ctx) => {
const current = get();
const stale = (): boolean => get().generation !== current.generation;
void flushInBackground();
set({ ctx, prompt: event.prompt });
await countTurn(ctx).catch(() => undefined);
if (stale()) return { systemPrompt: event.systemPrompt };
if (stale()) return undefined;
const prompt = clipSessionSummary(event.prompt);
const observedAt = new Date().toISOString();
const correction = declaredCorrectionQuote(event.prompt);
Expand All @@ -462,20 +476,20 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
}
}
const project = await engine().catch(() => undefined);
if (stale()) return { systemPrompt: event.systemPrompt };
// No system prompt edits: a per-turn system prompt is dropped on automated
// turns (subagent results, self-compact handoffs), which flipped the cached
// prefix and re-billed the whole context. The snapshot itself says it is
// reference data, not instructions.
const base = event.systemPrompt;
if (stale()) return undefined;
// Never return systemPrompt, not even unchanged: Pi takes any returned
// prompt as a forced prompt and rewrites the request head for this turn.
// Automated turns (subagent results, self-compact handoffs) skip this hook,
// so the cached prefix flipped and the whole context was re-billed. The
// snapshot itself says it is reference data, not instructions.
if (!project) return undefined;
const { facts, digest, small, revision } = coreSnapshot(project);
// L0 is policy only. Changing facts belong at the append-only message tail,
// not in the early system prefix. Include empty snapshots to revoke memory.
const systemPrompt = base;
// Changing facts belong at the append-only message tail, not in the early
// system prefix. An empty snapshot still revokes an earlier one in context.
const deliver = (recall?: string, items = 0, omitted = 0) => {
try { setMode(ctx, 'memory', memoryStatusLine(digest, facts.length, items)); } catch { /* the status line must not cost the prompt */ }
return { systemPrompt, message: memoryMessage(revision, digest.block, recall, items, omitted) };
const message = memoryMessage(ctx, revision, digest.block, recall, items, omitted);
return message ? { message } : undefined;
};
// The snapshot already carries all of memory: nothing to search, no encoder.
if (facts.every(fact => digest.covered.has(fact.id))) return deliver();
Expand All @@ -484,7 +498,7 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
const dense = small ? false : encoderReady(project);
const recalled = await search({ queries: recallQueries(event.prompt), limit: 8, maxBytes: 1500, dense, scoreThreshold: recallThreshold, namespaces: ['memory', 'memory.topic'] })
.catch(() => undefined);
if (stale()) return { systemPrompt: event.systemPrompt };
if (stale()) return undefined;
const highConfidence = (recalled?.items ?? [])
.filter(item => (item.standing === 'supported' || item.standing === 'needs_review') && !digest.covered.has(item.id)).slice(0, 4);
const memoryBlock = highConfidence.length
Expand Down Expand Up @@ -588,7 +602,7 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
return branch.flatMap(entry => {
if (entry.type !== 'message' || entry.message.role !== 'user') return [];
const content = entry.message.content;
return [typeof content === 'string' ? content : content.filter(part => part.type === 'text').map(part => part.text).join('\n')];
return [contentText(content)];
});
},
};
Expand Down
39 changes: 31 additions & 8 deletions src/handoff/memory-envelope.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,14 +8,28 @@ export const renderMemoryEnvelope = (memory: MemoryEnvelope, snapshot = true, re
...(recall && memory.recall ? [memory.recall] : []),
].join('\n\n');

type DeliveryState = { revision: string | undefined; recalls: Set<string> };

/** Which parts of `memory` are new after the deliveries folded into `state`; folds this one in. */
const nextDelivery = (state: DeliveryState, memory: MemoryEnvelope): { snapshot: boolean; recall: boolean } => {
const snapshot = state.revision !== memory.revision;
if (snapshot) {
state.revision = memory.revision;
state.recalls.clear();
}
const recall = Boolean(memory.recall && !state.recalls.has(memory.recall));
if (memory.recall) state.recalls.add(memory.recall);
return { snapshot, recall };
};

/** Recompute from retained context, never from a process-lifetime delivery ledger.
* Keep first-copy bytes and compare only the latest snapshot: A → B → A is a
* new delivery, not a repeat of the obsolete A. Proposed messages count only
* if they survive selection. Re-running after eviction restores missing data.
*/
export const uniqueMemory = (messages: readonly HandoffMessage[],
onReplacement?: (replacement: HandoffMessage, source: HandoffMessage) => void): readonly HandoffMessage[] => {
const state = { revision: undefined as string | undefined, recalls: new Set<string>() };
const state: DeliveryState = { revision: undefined, recalls: new Set<string>() };
return messages.flatMap(message => {
const custom = message as EnvelopeMessage;
if (custom.customType !== 'pi-memory-recall') return [message];
Expand All @@ -26,13 +40,7 @@ export const uniqueMemory = (messages: readonly HandoffMessage[],
state.recalls.add(key);
return [message];
}
const snapshot = state.revision !== memory.revision;
if (snapshot) {
state.revision = memory.revision;
state.recalls.clear();
}
const recall = Boolean(memory.recall && !state.recalls.has(memory.recall));
if (memory.recall) state.recalls.add(memory.recall);
const { snapshot, recall } = nextDelivery(state, memory);
if (!snapshot && !recall) return [];
const content = renderMemoryEnvelope(memory, snapshot, recall);
if (content === message.content) return [message];
Expand All @@ -41,3 +49,18 @@ export const uniqueMemory = (messages: readonly HandoffMessage[],
return [replacement];
});
};

/** The envelope text the model does not already have in `retained`, or
* undefined when it would repeat what is there. A context with no snapshot
* counts as holding `baseline`, so an empty memory has nothing to revoke.
*/
export const unseenMemory = (retained: readonly HandoffMessage[], memory: MemoryEnvelope, baseline?: string): string | undefined => {
const state: DeliveryState = { revision: baseline, recalls: new Set<string>() };
for (const message of retained) {
const custom = message as EnvelopeMessage;
const earlier = custom.customType === 'pi-memory-recall' ? custom.details?.memory : undefined;
if (earlier?.version === 1) nextDelivery(state, earlier);
}
const { snapshot, recall } = nextDelivery(state, memory);
return snapshot || recall ? renderMemoryEnvelope(memory, snapshot, recall) : undefined;
};
4 changes: 2 additions & 2 deletions src/sources/discovery.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import { readdir, readFile } from 'node:fs/promises';
import { homedir } from 'node:os';
import { join } from 'node:path';
import { getAgentDir } from '@earendil-works/pi-coding-agent';

/**
* Scopes are discovered from the marker files prjct publishes, not from
Expand All @@ -19,7 +19,7 @@ const TEAM_NAME = /^[a-z][a-z0-9-]{0,47}$/;
* the mailbox is agent-local runtime state.
*/
export const teamMailboxRoot = (override?: string): string =>
override ?? join(process.env.PI_CODING_AGENT_DIR ?? join(homedir(), '.pi', 'agent'), 'teams');
override ?? join(getAgentDir(), 'teams');

const readTeamMarker = async (home: string, id: string): Promise<TeamScope | undefined> => {
const raw = await readFile(join(home, 'teams', id, 'settings.json'), 'utf8').catch(() => undefined);
Expand Down
Loading
Loading