Nuggets synthesis

Type: agentic-system-analyses/types/agentic-system-synthesis.md

Bounded synthesis

From messages to retained context

Nuggets is a memory and context-supply system around an external Pi runtime, not an independently shipped model loop. This account covers the original TypeScript library, Pi extensions, both messaging gateway trees, maintenance writers and test source at commit 714cab8a3b1fb843aa98dfb51584d2c07a6739f3, with cutoff 2026-10-14. SRC-1 supplies implementation and doctrine/design evidence only. No deployment, tests, model calls, observed runs or causal experiments were supplied or performed. The advertised plugin workspace is absent from this revision; plugin and MCP behavior are not characterized. The boundary and evidence and Source register define these inclusions and exclusions.

An admitted Telegram chat or WhatsApp JID enters a per-identifier promise queue. The gateway starts or reuses a local Pi subprocess with a continued session directory, configured provider/model arguments and inherited environment. Pi owns subsequent model and tool decisions; the gateway waits for agent_end, extracts assistant text, chunks it and calls the channel sender. Handler return after enqueueing is not delivery completion. Telegram retries a failed HTML send as plain text, regardless of failure cause; ultimate send failure has no router replay. Pool pressure can evict busy work, and the RPC timeout measures inactivity rather than elapsed wall time. These are implemented integration and recovery rules, not demonstrated continuity or delivery guarantees. SRC-1: src/gateway/router.ts, src/gateway/pi-pool.ts, src/gateway/pi-rpc.ts, src/gateway/telegram.ts; RT-RTE-message-turn.

Ingress and state separation have narrower scopes than the conversation interface suggests. Empty allowlists permit all identifiers through the transport predicate; cron, direct extension/library calls and host tools bypass that predicate. Per-chat session directories separate conversation addresses, while default memory files are shared under the same OS user's ~/.nuggets. Per-identifier queues serialize one gateway process, not all writers. No deployed sandbox or global effect authorization is established. SRC-1: src/gateway/config.ts, src/gateway/pi-pool.ts, src/nuggets/memory.ts; RT-CLM-ingress-control, RT-RTE-memory-context.

Capture, persistence and later selection

Explicit model remember calls admit key/value strings through structural code checks, without per-item human approval or truth evaluation. Additional hooks automatically extract the first supported preference pattern from non-extension input and capture read/edit/write path inputs from tool-result events. Path capture does not check successful execution. Preference extraction can lose surrounding meaning: the epistemic report's static witness shows a negated instruction becoming an affirmative-looking learning fragment. This is a deduction from code, not an observed bad memory. SRC-1: .pi/extensions/nuggets.ts, src/nuggets/memory.ts; MEM-RTE-fact-mutation, MEM-RTE-hook-capture, EPI-RTE-preference-capture.

The persistent store is readable JSON fact content and configuration. Numerical HRR banks are reconstructed deterministically in RAM; they are not serialized vector banks or trained provider weights. Requested recall resolves a key through lexical rules, then decodes against the finite vocabulary of stored values. Across default kinds, greatest confidence wins and kind order breaks ties. A local substring fallback and direct list/hydration paths also exist. Confidence expresses relative numerical decoding scores, not world-truth probability, and decoding can associate the wrong stored value with a resolved key. SRC-1: src/nuggets/memory.ts, src/nuggets/shelf.ts; MEM-OBJ-nugget-facts, RT-CMP-hrr-vectors, MEM-RTE-recall-selection, EPI-RTE-recall-score.

Unsolicited context supply is a separate route. Lifecycle hooks rebuild a local facts map from retained branch tool details; session start additionally fills missing keys from default shelf stores. Before each agent starts, prefix-based formatting appends local facts to the system prompt. It renders at most ten active-file entries but has no global preference/ordinary-fact budget. Branch switching does not repeat shelf hydration. Old branch values can therefore override newer disk values. Named stores are reachable through explicit overrides but are outside default hydration. Delivery supplies context and standing preferences; it does not establish model obedience or changed behavior. SRC-1: .pi/extensions/nuggets.ts; MEM-OBJ-session-facts, MEM-RTE-context-rebuild, RT-BAP-facts-prompt.

Before host compaction, the extension retains the last three selected user texts, joined and truncated to 200 characters, as _task. It also copies qualifying paths from the final twenty assistant tool-use blocks: slicing precedes filtering, so nonmatching calls occupy that suffix. The task text is persisted and explicitly recallable, but ordinary prompt injection omits underscore-prefixed keys. Compaction-only path copies are local; their independent durability depends on other capture or host-retained details. Pi's summary, removal policy and checkpoint alternatives remain opaque. SRC-1: .pi/extensions/nuggets.ts; MEM-OBJ-task-summary, MEM-RTE-compaction-extract.

Withdrawal is not synchronized across copies. Local deletion can short-circuit disk deletion; cumulative snapshot replay does not interpret an omitted key as a tombstone; exported Markdown keeps entries whose shelf sources disappear. Direct library deletion does remove its own facts, so this is not a claim that all deletion fails. It is a concrete limit on interpreting a successful forget response as durable global withdrawal. SRC-1: .pi/extensions/nuggets.ts, src/nuggets/promote.ts; MEM-RTE-fact-mutation, MEM-RTE-context-rebuild, MEM-OBJ-promoted-memory.

Deferred work and its completion boundaries

The representative multi-step workflow is a one-shot reminder, reconstructed from shipped code rather than a user episode. In the selected conditional configuration—one allowlisted Telegram chat and no connected WhatsApp channel—the driver supplies a default recipient. Pi may choose the schedule tool, whose successful JSONL append returns a creation confirmation before gateway admission. The tool carries no originating chat ID. The gateway subsequently admits using fields and a request/default recipient, persists the job, and later emits its stored prompt into the same recipient Pi session. SRC-1: .pi/extensions/proactive.ts, src/gateway/main.ts, src/gateway/cron.ts; workflow account, RT-RTE-schedule-admission, RT-BAP-scheduled-prompt.

These handoffs do not close a verified completion loop. Startup skips existing request bytes; missing default recipient can cause rejection after confirmation; malformed cron shape can leave an admitted job that never matches. One-shot removal follows synchronous event emission, before asynchronous Pi processing or sending. Empty output or ultimate delivery failure does not restore that job. Sender-call completion is not recipient receipt or semantic fulfilment; an unregistered sender can log and resolve without sending. Heartbeat uses a different suppression rule: any occurrence of NOTHING suppresses its output, not merely the exact sentinel. SRC-1: src/gateway/cron.ts, src/gateway/router.ts, src/gateway/main.ts; workflow account, RT-RTE-proactive-turn.

What learning and improvement evidence supports

The strongest supported learning-related contribution is automatic trace-fed production of durable context: conversational fragments and tool paths become short facts with later prompt or recall consumers. Persisted task excerpts have a requested later-consumer route. These mechanisms qualify as wired trace learning in the route sense, without demonstrating improved capacity for future action. The profile verification preserves that distinction and incomplete coverage of opaque host alternatives. SRC-1: .pi/extensions/nuggets.ts; MEM-RTE-hook-capture, MEM-RTE-compaction-extract.

A separate improvement-directed pathway selects facts with at least three hits and writes recognized entries into a Claude-project MEMORY.md on compaction. This conditional context-placement writer is implemented. Ordinary extension recall supplies no session ID, however, and only nonempty library session IDs enable hit increments. Counters deduplicate against the last marker, not all historical sessions; overwritten values inherit hits. Existing recognized entries merge, while free-form prior prose can disappear when candidates trigger a rewrite. Actual external loading is unestablished. SRC-1: src/nuggets/memory.ts, src/nuggets/promote.ts, .pi/extensions/nuggets.ts; MEM-OBJ-hit-metadata, RT-RTE-memory-promotion, MEM-OBJ-promoted-memory.

For the README's faster/cheaper objective over future sessions, this supports a conditional improvement-directed context pathway, not exercised or successful self-improvement. Usage selects placement without evaluating usefulness; external consumption and subsequent behavior causally depending on that change are not established. No outcome comparison attributes a capacity gain to capture, HRR recall or promotion. Content-directed criticism improving future action is likewise unestablished, independently of automatic writes. The accepted runtime does not supply a condition-by-condition theory-builder assessment, so this synthesis assigns none: stored strings and delivery cannot establish theory consumption, criticism or iteration. Reflection and autonomous theory-building are not demonstrated; that does not negate code-controlled capture or timer-triggered invocation, and external model cognition remains uninspected rather than absent. SRC-1: README.md, src/nuggets/promote.ts; EPI-CLM-memory-improvement, RT-RTE-memory-context, RT-CMP-pi-model.

Operational admission is not epistemic acceptance. Within the inspected local memory routes, checks consume structure, lexical resemblance, numerical similarity or usage counts, not evidence accepting candidate truth for a named use and scope. Fixture tests have expected-answer oracles but no production fact-admission consumer, and were not run. These conclusions do not rule out external users or models checking content before a write. SRC-1: src/nuggets/memory.ts, src/nuggets/promote.ts, tests/memory.test.ts; EPI-ABS-truth-acceptance, EPI-RTE-memory-tests.

For repeated assistant work, the architecture provides concrete retained context and recall channels, but cannot establish correct extraction, recall accuracy or task benefit. For deferred reminders, it provides a coherent conditional path, but confirmation, admission and delivery remain distinct. Traces linking original inputs, derived facts, later consumption and outcomes would alter the activation assessment. Controlled comparisons varying capture, recall or promotion independently would be needed for component benefit. A traced hit-producing caller plus external Markdown loading would close important promotion gaps. Originating-recipient propagation, admission acknowledgements, durable delivery receipts/retry and cross-copy deletion propagation would change the corresponding architectural guarantees; merely running current code would not remove those implementation limits.

No target-source files were read for this synthesis; source warrants and minimum passages are supplied by the cited accepted records.

Limitations

Limitation	Affected SRC IDs and record citations	Inspected boundary	Conclusion prevented	Evidence that would resolve it
Stale compaction attribution remains in memory's integration issue; this is the reconciliation's unresolved conflict and report-verification limit.	SRC-1; MEM-RTE-compaction-extract, RT-RTE-memory-context, report-verification Limits	.pi/extensions/nuggets.ts and the handed reports. Current route records agree on slice-before-filter.	The integration issue cannot be treated as an accurate description of current runtime wording or an outstanding mechanism objection. The shared twenty-block-suffix conclusion remains supported.	Correction of the residual attribution by its owning analyst; no new mechanism evidence is needed.
No observed execution or causal comparison.	SRC-1; RT-RTE-message-turn, MEM-RTE-recall-selection, EPI-CLM-memory-improvement	Shipped code and doctrine at the frozen commit; tests inspected, not run.	Deployment success, activation, calibrated recall quality, measured speed/cost and causal improvement cannot be asserted.	Provenance-linked end-to-end traces and scoped outcome comparisons; independent component variation for component attribution.
External host/provider implementation and deployment contracts are unresolved.	SRC-1; boundary, RT-CMP-pi-model, MEM-RTE-context-rebuild, MEM-RTE-compaction-extract	Gateway and extension interfaces; not Pi/provider internals, installed grants or host checkpoints.	Complete host-memory classifications, exact context recovery, guaranteed extension activation, provider-internal checking or theory-building cannot be inferred.	Frozen host/provider contracts and inspection, deployed configuration and session/checkpoint traces.
Initial content, generic caller control and live concurrent state are unavailable.	SRC-1; MEM-OBJ-nugget-facts, MEM-OBJ-session-facts, RT-OBJ-cron-jobs, MEM-RTE-fact-mutation	Fact/job schemas and known writers/reload routes, not live histories.	Complete original lineage, per-content human control, factual warrant and deployed cross-process consistency remain unknown.	Admission histories, original content/evidence, caller identities and concurrent-write traces or an enforced coordination protocol.
Exported memory has no established external reader; ordinary extension recall does not accrue promotion hits.	SRC-1; RT-RTE-memory-promotion, MEM-OBJ-hit-metadata, MEM-OBJ-promoted-memory, EPI-CLM-memory-improvement	Conditional compaction writer and library hit update, not Claude loading or later behavior.	Ordinary repeated recall cannot be said to activate promotion, ensure permanent context or exercise self-improvement.	An identified session-ID-supplying route, retained hit/output provenance, host loading and later behavior causally dependent on the change.
Precompaction-only path durability is conditional.	SRC-1; MEM-RTE-compaction-extract, MEM-OBJ-session-facts	Local path copying versus persisted _task; host detail retention is external.	Persisted task text cannot establish durable recovery of every copied path or all discarded reasoning.	Trace each path through independent result-hook persistence or retained host details and later reload.
Advertised plugin is not shipped in the frozen tree.	SRC-1; boundary	Original TypeScript application and gateways only.	Findings cannot characterize the advertised npm plugin, its workspace or MCP behavior.	A separately authorized analysis of a frozen plugin implementation.