Insights22 April 2026Updated 26 October 20265 min read

A Cache Hierarchy for Team Knowledge: Sources, Permissions and Freshness

Neon concentric circles with glowing particles and a wavy line, illustrating a layered system or hierarchy concept.

A team knowledge cache should help an agent reuse evidence without turning a summary into the authoritative record. We recommend a layered lookup policy: a scoped knowledge cache for reusable context, the owning systems for source records, and the web for external questions. The design needs explicit rules for population, access and expiry before it needs a latency target.

The publisher's contents for Software Architecture in Practice, fourth edition, by Bass, Clements and Kazman, place performance tactics in chapter 9. For team knowledge, we would treat every cached answer as a derivative with a named source and an owner who can correct it.

Define the layers by responsibility

Three stacked tiers of light linked by a central vertical channel

Use L1 for the team knowledge cache, including approved summaries and pointers to original records. Use L2 for the systems that own those records, such as an issue tracker, documentation service or repository. Reserve L3 for external material, including vendor documentation and published research. These labels describe our proposed lookup policy, not a hardware architecture or a promise that each layer is faster than the next.

Route the question before searching. For a question about a team's decision, try authorised team evidence before searching the web. For a question about a vendor API, use the vendor's documentation directly rather than requiring an irrelevant internal miss first. For a live ticket state, query the owning system rather than accepting yesterday's summary.

Populate on reads, keep edits separate

Fetching a missing record and adding it to the cache is read-driven population. AWS distinguishes read-through caching from application-managed side caching: in read-through caching the cache fetches missing items, while side caching leaves fetching and population to application logic. If an agent performs the lookup and saves a summary itself, describe that mechanism as cache-aside population rather than claiming the cache implements transparent read-through.

Keep this separate from writing changes back to the source. Oracle's Coherence guide describes write-behind caching as asynchronously sending modified cache entries to the underlying data source after a delay. Our proposed knowledge cache does not do that: it stores a derived note after reading a source record, without changing that record. If an agent needs to edit a ticket or decision, give that write a separate authorised workflow and refresh the cached derivative afterwards.

Save evidence, not an unqualified answer

For each useful L2 lookup, we recommend a candidate cache entry containing the question, a short answer, the source URL, the source revision and the retrieval date. Add the project scope, permitted audience, source owner and conditions under which the answer should be checked again. Keep the source's modification time separate from the time the agent read it. In this design, reading an old record today must not relabel its contents as newly decided.

Before admitting the entry, check that the linked record supports the summary and that the intended audience may read it. Where the evidence is incomplete or contradictory, retain the disagreement and pointers rather than merging it into a confident conclusion. For example, a cache entry about an API retry policy should identify the repository revision and decision record used, not merely state that retries are safe. This is a proposed admission checklist, not a claim that every lookup deserves permanent storage.

Check permissions when serving the cache

NIST's Zero Trust Architecture guidance treats access to individual resources as a per-session decision and rejects implicit trust based on network location. Applying that principle here, we recommend checking the requesting identity and current access policy before returning cached evidence. A connector's ability to read a source should not become permission for every agent user to read its summary.

Apply the same restriction to titles, snippets and source pointers as to the answer itself. Test permission removal as well as permission granting, including an entry populated before a user's access was revoked. If the cache cannot establish the current permission, withhold the entry and report the access limitation rather than silently using an unrestricted fallback. These are access-control recommendations, not claims about a particular legal retention duty.

Give freshness an explicit rule

A bright crystal inside a segmented ring of light, like a timer counting around it

HTTP caching distinguishes fresh responses from stale ones by their age and freshness lifetime. That is a useful design reference, but an HTTP freshness calculation does not establish whether a generated summary still represents a team's decision. We recommend defining a separate freshness policy for each kind of knowledge entry.

An approved design explanation might be reusable until its source revision changes, while current incident status should require a live lookup. Assign an owner to invalidate or replace derivatives when a source changes, disappears or becomes restricted. When an entry has expired, recheck the source before presenting it as current. If the source is unavailable, return a dated historical note only where the team's policy permits it, otherwise state that the current answer could not be verified.

Measure correct reuse, not just fewer lookups

Before adding automatic population, agree a small set of representative team questions and record the evidence each answer should use. Include an unchanged decision, a revised decision, a restricted page, a deleted source and a source outage. Run those checks against both an empty cache and a populated cache. We recommend checking answer support, access decisions and freshness alongside response time and source-call volume.

Record why L1 declined an answer, distinguishing missing evidence from expired content and denied access. Do not count an unsupported answer as a successful cache hit merely because it avoided L2. Choose latency and cost targets from the team's measured workload rather than promising a universal hit rate or a fixed payback period. Start with one bounded project and an owner for corrections before broadening the cache's audience.

Update, October 2026

Our engineering article on grounding packs and the context agents need before searching adds a related design: supply orientation before work begins, then check load-bearing memory claims against code. Use it as a companion to the lookup policy, rather than treating a populated cache as the whole grounding process.

Sources

Want this in your team?

Tell us what you're building and where you want to get to, and we'll think it through with you.

Let's have a chat Follow by RSS →

All insights →