Agent Memory Read with Recency and Relevance Scoring

This prompt is for agent developers and infrastructure engineers who need to retrieve context from a shared memory store, not just by semantic similarity, but by balancing what is recent with what is relevant to the current task. The job-to-be-done is producing a ranked, scored, and justified list of memory entries that an agent can use as its working context. The ideal user is building a multi-agent system where agents share a blackboard, session state, or long-term fact store and must avoid the common failure mode of retrieving stale but semantically similar information over fresh, critical updates.

Use this prompt when your agent has a specific task or query and needs to pull a limited set of the most valuable entries from a larger memory store. It is appropriate when memory entries have associated timestamps and you need the model to apply a configurable recency weight. Do not use this prompt for simple top-K vector similarity search without scoring justification, for writing new memories, or for full database scans. It is also not a replacement for a deterministic retrieval pipeline; it is the scoring and ranking layer that sits on top of candidate retrieval, adding judgment that pure vector distance cannot provide.

The prompt requires you to provide a set of candidate memory entries, each with a unique ID, content, and a timestamp. You must also supply the agent's current task or query. The output is a structured list of entries with relevance scores, recency scores, a combined weighted score, and a concise justification for each entry's inclusion. Before deploying, you must validate the output schema strictly—missing justifications or malformed scores should trigger a retry or fallback. In high-stakes applications where memory retrieval drives autonomous action, always log the scored results for auditability and consider a human review step if the combined score falls below a defined confidence threshold. If your memory store is large, pre-filter candidates with a vector or keyword search before passing the top-N to this prompt to manage context window costs.

This prompt template is designed to be inserted into your agent's memory retrieval pipeline. It instructs the model to act as a retrieval ranker, consuming a set of candidate memory entries and a query representing the agent's current information need. The model must score each entry on two axes—recency and relevance—and produce a final composite score with a concise justification. The output is structured JSON, making it suitable for direct consumption by a downstream agent or orchestrator without additional parsing.

textCopy
You are a memory retrieval ranker for an autonomous agent system. Your task is to evaluate a set of candidate memory entries against the agent's current query and rank them by a composite score that balances recency and relevance.

## INPUT
Query: [AGENT_QUERY]
Current Timestamp: [CURRENT_TIMESTAMP]
Candidate Memory Entries:
[CANDIDATE_MEMORY_ENTRIES]

## SCORING RULES
1. For each entry, assign a `relevance_score` (0.0 to 1.0) based on how well the entry's content answers or informs the query.
2. Assign a `recency_score` (0.0 to 1.0) using exponential decay: `recency_score = exp(-[DECAY_RATE] * hours_since_timestamp)`. Use the provided `Current Timestamp` and the entry's `timestamp` to calculate `hours_since_timestamp`.
3. Compute a `composite_score` as `([RELEVANCE_WEIGHT] * relevance_score) + ([RECENCY_WEIGHT] * recency_score)`. Ensure the weights sum to 1.0.
4. If an entry's `relevance_score` is below [RELEVANCE_THRESHOLD], set its `composite_score` to 0.0 and mark it as `excluded: true`.
5. If an entry's `timestamp` is older than [STALENESS_CUTOFF_HOURS] hours, set its `composite_score` to 0.0 and mark it as `stale: true`.

## CONSTRAINTS
- Do not fabricate information. Only use the content provided in each entry.
- If no entries meet the threshold, return an empty `ranked_results` array.
- Preserve the original `entry_id` for traceability.

## OUTPUT_SCHEMA
Return a valid JSON object with this exact structure:
{
  "query": "string",
  "ranked_results": [
    {
      "entry_id": "string",
      "relevance_score": number,
      "recency_score": number,
      "composite_score": number,
      "justification": "string (1-2 sentences explaining the relevance assessment)",
      "excluded": boolean,
      "stale": boolean
    }
  ],
  "retrieval_metadata": {
    "total_candidates": number,
    "returned_count": number,
    "excluded_count": number,
    "stale_count": number
  }
}

To adapt this template for your system, replace the square-bracket placeholders with values from your application context. [AGENT_QUERY] should be the current task or question the agent is trying to resolve. [CANDIDATE_MEMORY_ENTRIES] must be a pre-fetched list of objects, each containing at least an entry_id, timestamp (ISO 8601), and content field. Tune [DECAY_RATE], [RELEVANCE_WEIGHT], [RECENCY_WEIGHT], [RELEVANCE_THRESHOLD], and [STALENESS_CUTOFF_HOURS] based on your application's tolerance for old information. For high-stakes domains like healthcare or finance, always route the final ranked list through a human review step before the agent acts on it, and log the full prompt and response for auditability.

Before deploying, validate the output against the defined JSON schema. Common failure modes include the model returning a composite score for an entry it simultaneously marked as excluded: true, or miscalculating the recency decay. Implement a post-processing validator that checks for these inconsistencies and either corrects them programmatically or triggers a retry. Start with a RELEVANCE_WEIGHT of 0.7 and a RECENCY_WEIGHT of 0.3 for task-oriented agents, then adjust based on eval results for retrieval precision.

The memory read prompt is not a standalone query; it is a retrieval step inside an agent's context assembly pipeline. Before the agent acts, it calls a memory store, passes the current task and recent observations as [QUERY_CONTEXT], and receives a ranked list of memory entries. The implementation harness must handle the full lifecycle: constructing the prompt with the correct variables, calling the model, validating the structured output, handling failures, and merging the result into the agent's working context window. This prompt is typically invoked at the start of a new task, after a tool call that changes state, or when the agent detects a knowledge gap.

Integration pattern. Wrap the prompt in a function read_memory(query_context, memory_store, top_k=10, recency_decay_days=7). The function should: (1) Retrieve candidate entries from the memory store using a hybrid search (vector similarity + keyword filters on session ID, agent ID, or task type). (2) Assemble the prompt by injecting [MEMORY_CANDIDATES] as a JSON array of objects with fields id, content, timestamp, source_agent, and access_count. (3) Inject [QUERY_CONTEXT] with the current task description, recent observations, and any active constraints. (4) Call the model with response_format set to the defined output schema. (5) Parse and validate the JSON response. (6) Filter entries below [RELEVANCE_THRESHOLD] (default 0.5) and return the scored list to the agent's context assembler.

Validation and retry logic. The output must conform to a strict schema: an array of objects with memory_id, relevance_score (float 0-1), recency_score (float 0-1), combined_score (float 0-1), and relevance_justification (string). Implement a post-processing validator that checks: all memory_id values exist in the input candidates, scores are within bounds, and combined_score is a weighted sum of relevance and recency (default 0.7 relevance, 0.3 recency). If validation fails, retry once with the error message appended to the prompt. If the retry also fails, fall back to a rule-based ranking using timestamp decay and keyword overlap, and log the failure for prompt debugging. For high-stakes agent workflows, add a human review step when the top result's combined_score is below 0.4 or when multiple entries have scores within 0.05 of each other, indicating ambiguity.

Observability and evals. Log every memory read call with: the query context hash, number of candidates, top-k results with scores, validation status, and latency. This data feeds two eval checks. First, retrieval precision: periodically sample memory reads and have a human or LLM judge rate whether the top-3 entries were actually relevant to the query context. Target precision above 0.85. Second, staleness detection: flag entries older than [STALENESS_THRESHOLD_DAYS] that receive high relevance scores, and verify whether the information is still accurate. If staleness is a recurring problem, adjust the recency decay weight upward or add a TTL field to memory entries. Wire these evals into your prompt regression test suite so that changes to the scoring prompt or weights are caught before deployment.

What to avoid. Do not call this prompt inside a tight agent loop without caching; repeated identical queries waste tokens and latency. Cache results keyed by (query_context_hash, memory_store_version) for the duration of a task. Do not pass the entire memory store as candidates; pre-filter to a manageable set (50-200 entries) using vector search and metadata filters. Do not skip validation; malformed JSON or out-of-bounds scores will break downstream context assembly. Finally, do not treat the model's relevance scores as ground truth; they are a ranking heuristic. Always preserve the raw memory content alongside the scores so the agent can reason over the evidence, not just the ranking.