symfonic.capabilities.memory.counts

counts

What the memory stages report about themselves, as integers.

Every number here reaches the public event stream, an operator's screen and durable storage at once, so the module's whole job is to answer "how much" without ever answering "what". The names are the ones a reader needs to tell apart the failures that look alike:

• found is what the store returned. found=0 on a stage that ran is a different fact from no stage record at all, and the pair "memory is empty" / "memory never ran" is the one this repository has confused before.
• discarded is what the ceiling refused after ranking. A turn recalling nothing because it found nothing and a turn recalling nothing because the budget dropped everything are different problems with different fixes.
• admitted is what reached the prompt, and is the number a panel means by "entries used" -- taken from the stage that did the work rather than by querying the store afterwards, which answers a different question (what the scope holds) and answers it at a different time.

recall_counts

recall_counts(hydration: Any) -> Mapping[str, int]

The retrieval stage's own tally of one hydration.

graph and vector are what each route contributed before the merge, and deduplicated is how many were the same memory seen twice. Those three answer a question found cannot: a turn that recalled nothing because the vector index was empty and one that recalled nothing because the embedder was unreachable both report found=0, and only the route counters tell them apart.

Source code in src/symfonic/capabilities/memory/counts.py

def recall_counts(hydration: Any) -> Mapping[str, int]:
    """The retrieval stage's own tally of one hydration.

    ``graph`` and ``vector`` are what each route contributed *before* the
    merge, and ``deduplicated`` is how many were the same memory seen twice.
    Those three answer a question ``found`` cannot: a turn that recalled
    nothing because the vector index was empty and one that recalled nothing
    because the embedder was unreachable both report ``found=0``, and only
    the route counters tell them apart.
    """
    result = getattr(hydration.retrieval, "result", None)
    memories = getattr(result, "memories", ())
    found = len(memories)
    discarded = len(getattr(hydration, "dropped", ()))
    working = getattr(hydration, "working", None)
    counts = {
        "found": found,
        "discarded": discarded,
        # Never negative: a ceiling cannot refuse more lines than were found,
        # and a clamp here is cheaper than a panel rendering "-1 admitted".
        "admitted": max(found - discarded, 0),
        "window": len(getattr(working, "turns", ())),
    }
    for name, value in (getattr(result, "sources", None) or {}).items():
        # Prefixed, so a route counter can never collide with one of the four
        # above and quietly overwrite it.
        counts[f"{name}_candidates" if name != "deduplicated" else name] = int(value)
    return counts

recall_reason

recall_reason(hydration: Any) -> str

What to say about a route that could not be reached, or "".

A degraded route is not a degraded turn: the answer stands on the routes that answered. But it must be said, because the alternative is a turn that silently recalls less and reports the same zero as a turn with nothing to recall.

Source code in src/symfonic/capabilities/memory/counts.py

def recall_reason(hydration: Any) -> str:
    """What to say about a route that could not be reached, or ``""``.

    A degraded route is not a degraded turn: the answer stands on the routes
    that answered. But it must be *said*, because the alternative is a turn
    that silently recalls less and reports the same zero as a turn with
    nothing to recall.
    """
    unavailable = getattr(
        getattr(hydration.retrieval, "result", None), "unavailable", ()
    )
    if not unavailable:
        return ""
    return (
        f"recall degraded: {', '.join(sorted(unavailable))} unavailable this "
        "turn; the answer stands on the routes that answered"
    )