matthewwong525/WongStack / .agents/plugins/memory
memory
Verifiedscripts/lib/documents/packet.mjs
View on GitHub// One admission budget for the exact representation written to stdout.
export const PACKET_BYTES = 6144;
export const FILES_BYTES = 600;
const FILES_SHOWN = 8;
export const byteSize = value => Buffer.byteLength(typeof value === 'string' ? value : JSON.stringify(value));
const clipped = (value, max = 240) => {
let text = String(value || '');
if (byteSize(text) <= max) return text;
const chars = Array.from(text);
while (byteSize(chars.join('')) > max - 3) chars.pop();
return `${chars.join('')}…`;
};
const cleanStatus = status => ({ state: status?.state || 'unavailable', ...(status?.reason ? { reason: clipped(status.reason, 180) } : {}) });
export function packetText(packet) {
const lines = [`Recall v2 · scope ${packet.scope}`,
`Facts: ${packet.sources.facts.state}${packet.sources.facts.reason ? ` (${packet.sources.facts.reason})` : ''}; documents: ${packet.sources.documents.state}${packet.sources.documents.reason ? ` (${packet.sources.documents.reason})` : ''}${
packet.sources.files?.state === 'unavailable' ? `; files: unavailable${packet.sources.files.reason ? ` (${packet.sources.files.reason})` : ''}` : ''}`];
if (Object.keys(packet.filters).length) lines.push(`Fact filters: ${JSON.stringify(packet.filters)}`);
if (packet.change) lines.push(`Change documents: ${packet.change}`);
for (const fact of packet.facts) lines.push(`Fact #${fact.id} · ${fact.type} · ${fact.created_at} · author ${fact.author || 'unknown'} · session ${fact.session_id || 'none'} · slug ${fact.slug}\n${fact.body}\nSource: source ${fact.id}`);
for (const doc of packet.documents) lines.push(`${doc.role} · ${doc.reference} · ${doc.heading || 'passage'} · lines ${doc.startLine}-${doc.endLine} · SHA256 ${doc.hash} · ${doc.freshness}\n${doc.text}${doc.truncated ? '\n[excerpt truncated; read original]' : ''}`);
if (packet.files?.length) lines.push(['Files (from the facts above; a place to start, not a full list):',
...packet.files.map(file => `- ${file.path} (${file.facts.map(id => `#${id}`).join(', ')})`)].join('\n'));
lines.push(`Omitted selected entries: facts ${packet.omitted.facts}; documents ${packet.omitted.documents}. Read cited originals before acting; history may be superseded.`);
return `${lines.join('\n\n')}\n`;
}
function shorterDocument(document, fits) {
const lines = document.text.split('\n');
for (let length = lines.length; length > 0; length--) {
const candidate = { ...document, text: lines.slice(0, length).join('\n'), endLine: document.startLine + length - 1,
truncated: document.truncated || length < lines.length };
if (hasBody(candidate.text) && fits(candidate)) return candidate;
}
return null;
}
const bodyLine = line => Boolean(line.trim()) && !/^\s*(?:#{1,6}\s|```|~~~)/.test(line);
const hasBody = text => text.split('\n').some(bodyLine);
function minimumDocument(document) {
const lines = document.text.split('\n'), index = lines.findIndex(bodyLine);
return index < 0 ? null : { ...document, text: lines.slice(0, index + 1).join('\n'), endLine: document.startLine + index,
truncated: document.truncated || index + 1 < lines.length };
}
export function renderPacket({ question, scope = 'current', change = null, limit = 5, filters = {}, factSource, documentSource,
facts = [], documents = [], files, fileSource },
{ json = false, budget = PACKET_BYTES } = {}) {
// `files` undefined means no list was asked for, as on `documents`: the packet then carries no files fields.
const packet = { version: 2, question: clipped(question), scope, change, documentLimit: limit,
filters, sources: { facts: cleanStatus(factSource), documents: cleanStatus(documentSource),
...(files ? { files: cleanStatus(fileSource ?? { state: 'empty' }) } : {}) },
facts: [], documents: [], ...(files ? { files: [] } : {}), omitted: { facts: facts.length, documents: documents.length } };
const serialize = () => json ? `${JSON.stringify(packet)}\n` : packetText(packet);
const initial = byteSize(serialize());
if (initial > budget) throw new Error('retrieval metadata exceeds packet budget');
let cap = budget, admittedFacts, admittedDocs;
const admitFact = (fact, index, allowance) => {
const selected = { id: fact.id, slug: fact.slug, type: fact.type, body: fact.body, author: fact.author,
created_at: fact.created_at, session_id: fact.session_id || null, state: fact.state, superseded_by: null };
const before = byteSize(serialize());
packet.facts.push(selected); packet.omitted.facts--;
const growth = byteSize(serialize()) - before;
if (growth > allowance || byteSize(serialize()) > cap) { packet.facts.pop(); packet.omitted.facts++; return 0; }
admittedFacts.add(index); return growth;
};
const admitDoc = (doc, index, allowance) => {
const before = byteSize(serialize());
const selected = shorterDocument(doc, candidate => {
packet.documents.push(candidate); packet.omitted.documents--;
const size = byteSize(serialize());
packet.documents.pop(); packet.omitted.documents++;
return size - before <= allowance && size <= cap;
});
if (!selected) return 0;
packet.documents.push(selected); packet.omitted.documents--;
admittedDocs.add(index); return byteSize(serialize()) - before;
};
// Facts and passages within `cap`, whole entries before longer excerpts; returns the entries it admitted.
const fill = () => {
packet.facts = []; packet.documents = []; packet.omitted = { facts: facts.length, documents: documents.length };
admittedFacts = new Set(); admittedDocs = new Set();
const available = cap - initial;
const balanced = facts.length && documents.length;
const factShare = balanced ? Math.floor(available / 2) : available;
const docShare = balanced ? available - factShare : available;
let remainingFacts = factShare, remainingDocs = docShare;
facts.slice(0, 8).forEach((fact, index) => { remainingFacts -= admitFact(fact, index, remainingFacts); });
const selectedDocs = documents.slice(0, 5), minimumCosts = selectedDocs.map(doc => {
const minimum = minimumDocument(doc);
if (!minimum) return Infinity;
const before = byteSize(serialize()); packet.documents.push(minimum); packet.omitted.documents--;
const cost = byteSize(serialize()) - before; packet.documents.pop(); packet.omitted.documents++;
return cost;
});
// Reserve a useful original passage per role before allocating more text to any one document.
const firstRoles = new Set(), roleFirst = [], later = [];
selectedDocs.forEach((doc, index) => {
if (firstRoles.has(doc.role)) later.push(index);
else { firstRoles.add(doc.role); roleFirst.push(index); }
});
const reserved = new Set(); let reservedBytes = 0;
for (const index of [...roleFirst, ...later]) {
if (reservedBytes + minimumCosts[index] <= docShare) { reserved.add(index); reservedBytes += minimumCosts[index]; }
}
const roles = new Set([...reserved].map(index => selectedDocs[index].role));
const extraPerRole = (docShare - reservedBytes) / Math.max(1, roles.size);
selectedDocs.forEach((doc, index) => {
if (!reserved.has(index)) return;
const count = [...reserved].filter(selected => selectedDocs[selected].role === doc.role).length;
remainingDocs -= admitDoc(doc, index, Math.min(remainingDocs, minimumCosts[index] + Math.floor(extraPerRole / count)));
});
// Reclaim unused capacity without splitting fact bodies or adding extra entries.
facts.slice(0, 8).forEach((fact, index) => { if (!admittedFacts.has(index)) admitFact(fact, index, cap - byteSize(serialize())); });
documents.slice(0, 5).forEach((doc, index) => { if (!admittedDocs.has(index)) admitDoc(doc, index, cap - byteSize(serialize())); });
return [...[...admittedFacts].map(index => `f${index}`), ...[...admittedDocs].map(index => `d${index}`)];
};
// The files list holds back up to FILES_BYTES, but never at the cost of a fact or a passage.
const shown = (files || []).slice(0, FILES_SHOWN);
const reserve = shown.length ? Math.min(FILES_BYTES, (() => { packet.files = shown; const size = byteSize(serialize()); packet.files = []; return size - initial; })()) : 0;
const whole = fill();
if (reserve) {
cap = budget - reserve;
const held = fill();
cap = budget;
if (!whole.every(entry => held.includes(entry))) fill();
}
if (files) admitFiles(packet, files, admittedFacts, facts, serialize, budget);
// `ok` only once an entry fits; `empty` came first because the longer word keeps the switch within the budget.
if (packet.files?.length && packet.sources.files.state === 'empty') packet.sources.files.state = 'ok';
// Expand already-admitted excerpts with reclaimed bytes, keeping other source evidence reserved.
documents.slice(0, 5).forEach((doc, index) => {
if (!admittedDocs.has(index)) return;
const slot = packet.documents.findIndex(selected => selected.path === doc.path && selected.startLine === doc.startLine);
if (slot < 0 || packet.documents[slot].text === doc.text) return;
const [previous] = packet.documents.splice(slot, 1); packet.omitted.documents++;
if (!admitDoc(doc, index, budget - byteSize(serialize()))) { packet.documents.push(previous); packet.omitted.documents--; }
});
packet.facts.sort((a, b) => facts.findIndex(fact => fact.id === a.id) - facts.findIndex(fact => fact.id === b.id));
packet.documents.sort((a, b) => documents.findIndex(doc => doc.path === a.path && doc.startLine === a.startLine)
- documents.findIndex(doc => doc.path === b.path && doc.startLine === b.startLine));
return { packet, text: serialize(), bytes: byteSize(serialize()) };
}
// List entries in rank order while they fit, each naming only admitted facts; FILES_BYTES at most.
function admitFiles(packet, files, admittedFacts, facts, serialize, budget) {
const ids = new Set([...admittedFacts].map(index => facts[index].id));
const start = byteSize(serialize());
for (const file of files) {
if (packet.files.length >= FILES_SHOWN) break;
const named = file.facts.filter(id => ids.has(id));
if (!named.length) continue;
packet.files.push({ path: file.path, facts: named, via: file.via });
const size = byteSize(serialize());
if (size > budget || size - start > FILES_BYTES) { packet.files.pop(); break; }
}
}
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |