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.3.0 (2026-10-09)

- Memory is on demand. Before a turn nothing is injected: no snapshot, no recall, and no restore after compaction or a tree move. The agent reads memory with `memory_context`, whose description now says what memory holds and when to look it up.
- Failed tool results are no longer tagged with an evidence handle. In 94 recent `memory_record` calls, 2 cited one, while the tag was added to 994 failed results.
- Remove the automatic recall search and its encoder warm-up from the prompt path.
- Remove the link to pi-context-prune (`/memory prune`, the panel's prune key and context line): with nothing injected, there is no superseded memory to prune.

## 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.
Expand Down
8 changes: 5 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,9 +51,11 @@ and shared by every project, and only when memory outgrows the prompt block.
- `memory_record` stores a selective temporal fact, appends a resolution instead
of rewriting history, or indexes a generic source document.

The extension keeps a bounded, session-local staging window for host tool
results. A failed tool result carries its staged evidence handle so the agent
can cite it with `memory_record`; successful results are left untouched.
Memory never enters the model context on its own: no snapshot, recall or
evidence tag is injected before or during a turn. The agent reads memory with
`memory_context` when it decides to. The extension keeps a bounded,
session-local staging window for host tool results; results reach the model
exactly as the tool wrote them.
Exact, secret-free user declarations beginning with `remember`, `recuerda`, or
`acuérdate` are also stored directly as supported lexical procedures after the
turn, preserving their original wording and language; corrections
Expand Down
13 changes: 7 additions & 6 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -113,8 +113,8 @@ Thus a future-effective replacement does not retire the current answer early.
Terminal intervals cannot be reopened in place: record a new fact so the gap in
validity is not erased. Fact ids are immutable. GC's seven-day grace starts no
earlier than both resolution time and the end of validity. Retrieval includes
observation, declared validity and resolution dates; automatic recall explicitly
warns that publication dates do not establish present applicability.
observation, declared validity and resolution dates; lookups explicitly warn
that publication dates do not establish present applicability.

### Source freshness and retirement

Expand Down Expand Up @@ -242,9 +242,10 @@ files and every data-bearing cache remain under the project root.
`memory_record`, retrieval, source sync, checkpoints and maintenance all target
the same active project authority.

Automatic recall appends a reference-data message; it does not rewrite the system
prompt. The recall threshold defaults to zero. The active agent can call
`memory_context` for further evidence or query expansion.
Nothing is recalled automatically. Before a turn the extension only counts it,
captures what the person declared and updates the status line; it adds no
message and never returns a system prompt. The active agent calls
`memory_context` when memory may matter, with its own queries.

## Language

Expand Down Expand Up @@ -310,7 +311,7 @@ in flight.

`pi-session` uses an independent 8-turn/60-second sync cadence. Exact declared
corrections and secret-free `remember`/`recuerda`/`acuérdate` statements are
promoted lexically after the turn so the next session can recall a supported
promoted lexically after the turn so the next session can look up a supported
fact without waiting for daemon curation. Questions containing those words are
not declarations. Raw observations are never embedded.

Expand Down
4 changes: 2 additions & 2 deletions package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "@prjct.app/pi-memory",
"version": "0.2.3",
"version": "0.3.0",
"description": "Pi-native temporal memory and hybrid retrieval for agents.",
"type": "module",
"keywords": [
Expand Down
34 changes: 0 additions & 34 deletions src/extension/context-prune.ts

This file was deleted.

110 changes: 18 additions & 92 deletions src/extension/hooks.ts
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,6 @@ import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-a
import { contentText } from '@earendil-works/pi-ai';
import type { EvidenceRef } from '../contracts/evidence.ts';
import { factIsValidAt, type MemoryKind } from '../contracts/memory.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 @@ -97,13 +95,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)
.replaceAll('<', '\\u003c').replaceAll('>', '\\u003e').replaceAll('\u2028', '\\u2028').replaceAll('\u2029', '\\u2029');

export type MemorySearch = (
request: Parameters<typeof federatedSearch>[1],
) => ReturnType<typeof federatedSearch>;
Expand All @@ -114,7 +107,9 @@ export type MemorySearch = (
export const DEFAULT_RECALL_THRESHOLD = 0;

export const installMemoryHooks = (pi: ExtensionAPI, options: {
home?: string; recallThreshold?: number;
home?: string;
/** Legacy: automatic recall was removed; memory_context lookups carry their own threshold. */
recallThreshold?: number;
handoff?: HandoffBudget;
observations?: Partial<ObservationPolicy>;
history?: Partial<HistoryPolicy>;
Expand All @@ -129,7 +124,6 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
/** Legacy injection retained for callers; storage preserves original text. */
translator?: Translator;
} = {}) => {
const recallThreshold = options.recallThreshold ?? DEFAULT_RECALL_THRESHOLD;
const engineOptions = (): { home?: string; provider?: EmbeddingProvider } => ({
...(options.home === undefined ? {} : { home: options.home }),
...(options.embeddingProvider ? { provider: options.embeddingProvider } : {}),
Expand Down Expand Up @@ -305,16 +299,6 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
.finally(() => { backfill.running = undefined; });
};

const encoder: { project?: MemoryEngine; ready: boolean; warming?: Promise<void> } = { ready: false };
/** Starts loading the encoder in the background; true once it can serve queries. */
const encoderReady = (project: MemoryEngine): boolean => {
if (encoder.project !== project) Object.assign(encoder, { project, ready: false, warming: undefined });
if (!encoder.ready && !encoder.warming) {
encoder.warming = project.warmEncoder().then(ready => { if (encoder.project === project) encoder.ready = ready; });
}
return encoder.ready;
};

const flushSessionObservations = async (): Promise<void> => {
const pending = get();
if (!pending.observations.length && !pending.declarations.length) return;
Expand Down Expand Up @@ -403,50 +387,22 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
} });

/**
* Only hard rules ride in every snapshot; the rest is recalled when the prompt
* makes it relevant. The revision follows the core alone, so a new preference
* or failure does not resend the snapshot. The full digest still decides
* whether memory is small enough to skip the encoder (~500MB resident).
* Only hard rules count toward the status line; the rest is found with
* memory_context when the model asks for it.
*/
const coreSnapshot = (project: MemoryEngine) => {
const facts = project.projection.activeFacts(project.scopeId, DIGEST_SCAN_LIMIT)
.filter(fact => (fact.standing === 'supported' || fact.standing === 'needs_review') && factIsValidAt(fact, Date.now()));
const digest = memoryDigest(facts, Date.now(), CORE_DIGEST_BYTES, CORE_KINDS);
return { facts, digest, small: memoryDigest(facts).complete, revision: sha256(digest.block ?? '') };
};
/** 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 } : {}) };
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 } };
return { facts, digest: memoryDigest(facts, Date.now(), CORE_DIGEST_BYTES, CORE_KINDS) };
};

/**
* 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.
* Memory never enters the context on its own: no snapshot, no recall, no
* message. The model reads it with memory_context when it decides to. This
* hook only counts the turn, captures what the person declared, and updates
* the status line. It never returns systemPrompt either: Pi takes any returned
* prompt as a forced prompt for prompted turns only, which flipped the cache.
*/
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);
const message = memoryMessage(ctx, revision, digest.block);
if (message) pi.sendMessage(message, { triggerTurn: false });
};
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;
Expand Down Expand Up @@ -476,39 +432,10 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
}
}
const project = await engine().catch(() => undefined);
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);
// 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 */ }
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();
// Search the rest. Small memories stay lexical; for larger ones dense joins
// once the encoder has loaded in the background; a prompt never waits for it.
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 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
? `<retained_memory trust="untrusted">\n${highConfidence.map(item => retainedJson({
id: item.id, namespace: item.namespace, standing: item.standing, provenance: item.provenance,
statement: item.statement, observedAt: item.observedAt, validAt: item.validAt, invalidAt: item.invalidAt,
})).join('\n')}\n</retained_memory>`
: undefined;
// Deduplicate only after context selection; proposals are not deliveries.
return deliver(memoryBlock, highConfidence.length, recalled?.omitted ?? 0);
if (stale() || !project) return undefined;
const { facts, digest } = coreSnapshot(project);
try { setMode(ctx, 'memory', memoryStatusLine(digest, facts.length, 0)); } catch { /* the status line must not cost the prompt */ }
return undefined;
});

/**
Expand Down Expand Up @@ -552,11 +479,10 @@ export const installMemoryHooks = (pi: ExtensionAPI, options: {
sessionId: ctx.sessionManager.getSessionId(),
});
}
// Results are staged for memory_record, never tagged: a failure handle in
// every failed result cost context for evidence the model almost never cited.
const capped = await capOutput(event.toolName, event.toolCallId, event.content as readonly unknown[], event.details, raw);
// Every result is staged, but only a failure carries its handle: tagging all
// results cost ~53k tokens in four days for a handle that was never cited.
if (!capped && !event.isError) return undefined;
return { content: [...(capped ?? event.content), ...(event.isError ? [{ type: 'text' as const, text: `[pi-memory evidence: ${handle}]` }] : [])] };
return capped ? { content: capped } : undefined;
});

pi.on('turn_end', () => { void flushInBackground(); });
Expand Down
6 changes: 0 additions & 6 deletions src/extension/memory-panel.ts
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,6 @@ export type MemorySnapshot = Readonly<{
curation?: CurationStats;
sources: readonly (SyncDecision & { last?: SyncRun | null })[];
error?: string;
/** Memory blocks in this session's context, from pi-context-prune. */
context?: string;
}>;

/** What the panel can ask the extension to do. Each returns a one-line result. */
Expand All @@ -26,8 +24,6 @@ export type MemoryOps = Readonly<{
gc(): Promise<string>;
checkpointWal(): Promise<string>;
rebuild(): Promise<string>;
/** Remove superseded memory from this session's context on the next request. */
prune?(): Promise<string>;
}>;

const STORE = 'store';
Expand Down Expand Up @@ -73,7 +69,6 @@ export function memoryPanelSpec(ops: MemoryOps, initial: MemorySnapshot): PanelS
{ key: 'g', label: 'Collect garbage', when: onStore, run: act(STORE, ops.gc) },
{ key: 'w', label: 'Checkpoint WAL', when: onStore, run: act(STORE, ops.checkpointWal) },
{ key: 'R', label: 'Rebuild index', when: onStore, confirm: true, run: act(STORE, ops.rebuild) },
...(ops.prune ? [{ key: 'p', label: 'Prune memory from context', when: onStore, run: act(STORE, ops.prune) }] : []),
];

const items = (): PanelItem[] => {
Expand Down Expand Up @@ -158,7 +153,6 @@ export function memoryPanelSpec(ops: MemoryOps, initial: MemorySnapshot): PanelS
{ label: 'curation', value: `${(curation?.pending ?? 0) + (curation?.claimed ?? 0)} queued · ${curation?.published ?? 0} published` },
{ label: 'problems', value: `${curation?.failed ?? 0} failed · ${curation?.blocked ?? 0} blocked`, tone: (curation?.failed || curation?.blocked) ? 'warning' : undefined },
{ label: 'cache', value: 'session-references-v2' },
...(snap.context ? [{ label: 'context', value: clean(snap.context) }] : []),
],
sections: [history(STORE)],
};
Expand Down
Loading
Loading