prism-registry-demo

Agent memory systems degrade LLM prefix caching, allow prompt injection via persisted content, and create inconsistent state when live writes update both the store and the in-context representation simultaneously. TRIGGER when: designing a memory system for a persistent agent, debugging prompt cache misses after memory writes, or adding external memory providers to an agent.

Agent conversations that span many turns overflow the context window, causing silent truncation, lost task state, or infinite retry loops. TRIGGER when: designing a long-running agent, adding context compression, debugging an agent that appears to restart mid-task or retries indefinitely, or observing model amnesia on extended conversations.

LLM API error codes and HTTP status codes frequently carry multiple semantically distinct meanings that require different recovery actions. TRIGGER when: implementing retry logic for an LLM API client, debugging agents that loop on recoverable errors, or building failover logic across LLM providers.

LLM provider reliability strategies that seem correct — key rotation, backoff with jitter — fail at scale due to credential ordering, correlated retries, and missing circuit breakers. TRIGGER when: implementing retry or failover logic for an LLM gateway, debugging thundering-herd rate-limit storms, or building a multi-provider routing layer.

Multi-agent systems bleed iteration budgets on programmatic tool calls and create unbounded cost loops through recursive delegation. TRIGGER when: implementing a delegation or subagent system, adding code-execution or batch-processing tools to an agent, or debugging agents that exhaust their iteration budget faster than expected.

Agents that write or modify their own persistent configuration create attack vectors — malicious tasks can plant injections in files that execute in future sessions. TRIGGER when: building an agent that learns or saves reusable skill or config files, implementing capability gates or redaction controls, or supporting multi-user deployments of a shared agent.

Large tool outputs silently overflow the context window or cause request failures misdiagnosed as prompt-length errors. TRIGGER when: building agents that call file, search, or code-execution tools; debugging context overflow on tool-heavy tasks; handling LLM API errors after tool-rich turns.

Distinguish LLM extraction failures from genuinely-empty results so callers can implement retry and alerting. TRIGGER when: designing error handling for an LLM extraction step, implementing retry logic for an AI-backed processing pipeline, adding monitoring to a pipeline that returns results from an LLM call.

Make AI/ML dependency degradation (missing model, failed import, unavailable component) visible to operators without interrupting the caller. TRIGGER when: designing fallback behavior for an optional AI/ML dependency, adding a new AI/ML step with graceful degradation, implementing health checks for a system with optional AI components.

Avoid synchronous network I/O inside async client constructors — it blocks the event loop during construction and stalls all concurrent requests. TRIGGER when: adding API key validation or network ping to an async client constructor, constructing a client that hits a remote endpoint on init, designing an async SDK wrapper around a synchronous HTTP library.

Claude Code PreToolUse hooks must exit 2 to block tool execution — exit 1 signals hook failure but allows the tool to proceed. TRIGGER when: writing a Claude Code PreToolUse hook that should prevent a tool from executing, implementing access control or guardrails in a hook, debugging a hook that runs but does not block the tool.

File-backed embedded stores (RocksDB, LMDB) allow only one writer per path — multiple lazy-initialized clients on the same path deadlock or crash. TRIGGER when: initializing two logical stores backed by the same embedded database, using an embedded vector store alongside a secondary index on the same storage path, designing lazy initialization for stores that may share a file path.

File-backed embedded stores must require an explicit path in config — auto-injected temp paths create disk-backed behavior invisible to callers and lost on container restart. TRIGGER when: configuring a file-backed vector store or embedded database, deploying a service that uses an embedded store to a containerized environment, designing default configuration for a store that can run in-memory or file-backed modes.

Hybrid search (semantic + keyword + signal boost) must over-fetch semantic candidates before re-ranking — fetching exactly top-k from the vector store gives de facto pure-semantic results regardless of hybrid scoring. TRIGGER when: implementing hybrid search over a vector store, adding keyword or entity-boost re-ranking on top of semantic retrieval, designing a retrieval pipeline that combines multiple signals.

In hybrid search systems (semantic + keyword + signal boost), similarity thresholds must be calibrated to the combined score distribution — standard semantic defaults cause recall collapse. TRIGGER when: configuring a similarity threshold for hybrid search results, tuning recall vs precision in a system that combines semantic and keyword signals, migrating from pure-semantic to hybrid retrieval.

Memory or AI clients that perform network validation on construction must be instantiated once and reused — per-request construction adds a round-trip per request and causes concurrent validation storms under load. TRIGGER when: initializing a memory or AI client inside a request handler or tool call, benchmarking a service that constructs clients at call time, designing dependency injection for a service with a remote memory or AI backend.

In multi-tenant memory systems, env vars or runtime flags that widen search scope beyond the requesting user must be explicitly audited — they bypass per-user identity isolation and expose cross-tenant data. TRIGGER when: adding a global-search or admin-mode feature to a multi-tenant system, implementing env-var-controlled search scope overrides, designing wildcard or cross-user queries.

Prevents context window overflow in multi-turn tool-calling agents by combining transcript persistence, split compression strategies, and tool output offloading. TRIGGER when: building a multi-turn agent with tool calling, conversation history grows across turns and approaches context limits, tool outputs are large or unpredictable in size, agent repeats tool calls or loses context after long sessions, designing prompt compression strategy for cost-sensitive execution paths.

Prevents race conditions and security holes when agent tasks execute in parallel over shared credentials, network, and filesystem. TRIGGER when: building agents that execute multiple tool calls or tasks concurrently, agents share OAuth credentials or API keys across parallel executions, agent code execution runs on shared multi-tenant infrastructure, agents need both temporary scratch space and persistent storage across turns, designing workspace isolation for agent sessions.

Agent session design: separating stable session identity from mutable working location. TRIGGER when: designing session storage for agents that support worktrees, remote execution, or mid-session directory changes; when debugging resume failures after a working directory change; when comparing session IDs across API versions or compat layers; or when a team member asks why getCwd()should not be used to derive session file paths.

Prevent redundant API calls from side operations whose inputs don't change across loop iterations in a multi-step agentic tool-use loop. TRIGGER when: adding a background API call or prefetch to an agentic tool-use loop, designing context enrichment for a multi-step agent, adding memory retrieval to a streaming tool pipeline.

Anthropic API agentic streaming loop: how to recover from context-size errors (prompt-too-long 413, max-output-tokens) without terminating the session. TRIGGER when: designing or implementing any agentic loop that streams from the Anthropic API, when debugging sessions that terminate unexpectedly on context overflow, when deciding how to wire post-turn hooks, or when a team member asks why errors are withheld from the stream rather than surfaced immediately.

Anthropic API prompt caching: how to keep server-side cache hits stable across a long agentic session. TRIGGER when designing session state models for agentic applications, when debugging unexpected cache misses after feature flag changes, when deciding whether to re-evaluate eligibility or feature headers per-turn, or when configuring compaction to avoid busting the prompt cache. Load even before cache misses are observed — these decisions must be made at design time.

Anthropic API extended thinking: how thinking blocks must be preserved and when they cause 400 errors. TRIGGER when: implementing extended thinking in a multi-turn agentic loop, when debugging 400 errors with 'thinking blocks cannot be modified', when implementing model fallback that switches from a thinking-enabled model, or when deciding what to strip before a retry. Load when writing any code that handles extended thinking across multiple turns.

Anthropic API tool use: detecting when the model has called a tool and dispatching tool execution correctly. TRIGGER when: implementing tool dispatch in a streaming API loop, when debugging tool calls that are silently missed, or when a team member asks why stop_reason should not be used as the tool-dispatch signal. Load when writing any code that processes streaming responses for tool use.

Initialize authentication before any feature-flag or remote config system that uses user identity for targeting — otherwise authenticated users are denied on cache miss. TRIGGER when: configuring startup initialization order for a service with user-specific feature flags, adding feature gating to an authenticated endpoint, integrating a feature-flag SDK into an auth-required service.

Parallel tool executors: how to safely batch concurrent tool calls while preserving deterministic context mutation. TRIGGER when: designing a tool executor that runs multiple tool calls concurrently, when debugging non-deterministic context state after concurrent tool execution, when deciding whether a tool call is safe to run concurrently, or when a write tool appears in a batch with read tools. Load when writing any code that executes multiple tool calls in parallel.

Ensure optional post-step hooks in a processing pipeline surface failures rather than silently swallowing them. TRIGGER when: adding a hook invocation to a processing pipeline, designing optional post-processing callbacks, wiring post-sampling or post-tool hooks into an agentic loop.

Polling loops with capacity throttling how to prevent tight-loop failures when a polling service enters an at-capacity state. TRIGGER when: designing a polling loop that has a 'throttled' or 'at capacity' mode, when configuring sleep intervals for capacity-throttled polling, or when debugging a service that appears to be looping at HTTP-round-trip speed. Load when writing any poll loop that can enter a reduced-activity mode.

Remote config validation for interdependent fields: why to reject the entire config object rather than clamping individual fields. TRIGGER when designing validation for remotely-tunable configuration objects with fields that constrain each other, when choosing between whole-object rejection vs. per-field clamping in a validation schema, or when debugging a service that behaved unexpectedly after a remote config push. Load when writing validation for any config that is served remotely and has cross-field constraints.

Prevent circular references when persisting large tool results to disk for session resume — tools that read arbitrary paths or URLs must not have their output persisted. TRIGGER when: adding result persistence to a tool system, designing session-resume tool result replay, adding a new tool that reads files or external resources.

Work queues with short-lived auth credentials: why token expiry requires re-dispatching the claimed work item, not just refreshing the token. TRIGGER when building a work queue (Redis Streams, SQS, Kafka, RabbitMQ) where consumers authenticate with short-lived credentials (JWTs, OAuth tokens, signed claims), when debugging a consumer that appears healthy but receives no new work, or when designing token refresh for long-running queue consumers. Load when combining any ACK/claim-based queue with short-lived auth.

Keeps agent framework code decoupled from application layer code and ensures cross-process config changes propagate without restarts. TRIGGER when: packaging an agent framework for embedded or library use, deploying an agent framework and API gateway as separate processes, debugging stale tool configs that don't update after config edits, ensuring config changes in one process are visible to another without restart.

Prevents agent long-term memory from degrading due to session-scoped references, low-confidence extractions, and cross-agent or cross-user contamination. TRIGGER when: building persistent memory for a multi-turn agent, memory retrieved in future sessions contains stale or invalid references, agent performance degrades as memory grows, deploying an agent in a multi-user or multi-agent environment.

Ensures agent memory file writes are non-blocking and crash-safe in production. TRIGGER when: adding persistent memory to a multi-turn agent, memory updates slowing agent response times, agent memory files corrupted after process crash or restart, debugging partial writes or JSON parse errors in memory storage.

Maintains message history invariants required by LLM APIs when middleware injects or repairs messages mid-conversation. TRIGGER when: building middleware that injects messages into an ongoing conversation, handling agent interruption or cancellation that leaves tool calls without responses, injecting warnings or status messages mid-conversation across multiple LLM providers.

Prevents agent safety controls from being silently bypassed via artifact serving, guardrail provider errors, or injected instructions in tool results. TRIGGER when: serving files or artifacts generated by an agent, configuring guardrails or content filters for tool calls, ingesting web search results or file content into agent message history, reviewing security posture of a production agent deployment.

Prevents gateway memory exhaustion and event loop blocking when handling large file uploads in async web frameworks. TRIGGER when: implementing a file upload endpoint in an async web framework (FastAPI, aiohttp, Django Channels, or similar), choosing between reading the full body vs chunked streaming for file ingestion, adding file size limits to an async upload handler.

"Docker Compose environment variable precedence: failure modes when mixing the environment section and env_file for the same variable. TRIGGER when: writing docker-compose.yml with both environment and env_file sections, using \${VAR:-default} syntax in an environment section, debugging why .env overrides are silently ignored at docker compose up."

Prevents silently misconfigured extensions when env var placeholders in plugin config resolve to empty string at load time. TRIGGER when: adding env var references to MCP server or plugin configs, designing config resolution for user-supplied extension manifests, choosing between fail-fast and silent-fallback for missing environment variables in optional integrations.