Skip to main content

Adaptive Memory

Adaptive Memory with Decay and Reinforcement gives Keeptrusts a feedback-driven memory lifecycle. Instead of treating memories as static records, Keeptrusts collects usage signals, adjusts trust over time, reinforces memories that keep helping, and moves stale memories out of active recall when they stop being useful.

Use this page when​

  • You need to understand how Keeptrusts turns memory feedback into trust and lifecycle decisions.
  • You want to operate the memory signal, analytics, freeze, and decay controls from the API, console, or CLI.
  • You are validating that stale or low-confidence memories age out safely while useful memories keep getting reinforced.

Primary audience​

  • Primary: Technical Engineers
  • Secondary: AI Agents, Technical Leaders

Main content​

1. What Is Adaptive Memory​

Adaptive Memory is a feedback-driven memory lifecycle that goes beyond simple create, read, update, and delete flows.

  • Keeptrusts collects usage signals from conversations and task execution.
  • Recalled memories can accumulate positive and negative evidence over time.
  • Repeated helpful use reinforces a memory and can raise its effective trust.
  • Stale memories, expiring memories, or memories with persistent negative feedback can become decay candidates.
  • Decay is designed to reduce bad or obsolete recall without permanently deleting evidence by default.

In current Keeptrusts terminology, reinforcement is driven by helpful feedback and negative pressure is driven by incorrect or outdated feedback.

2. Usage Signals​

Usage signals are submitted through the API and surfaced in the console and CLI.

  • API endpoint: POST /v1/memories/{id}/signal
  • BFF route: /api/memories/[id]/signal
  • Supported signal values today: helpful, incorrect, and outdated
  • Conceptually, helpful acts as a positive signal and incorrect/outdated act as negative signals
  • Signals accumulate on the memory record and are aggregated into positive and negative counters

In the console, recalled memories in chat expose a thumbs-up/thumbs-down/flag surface through MemorySignalButtons. In product terms, this is the memory signal controls surface for recalled memory feedback.

3. Trust-Level Adjustment​

Adaptive Memory changes how strongly Keeptrusts should trust a memory over time.

  • Consistent positive signals can promote a memory to a stronger trust state
  • Persistent negative signals can lower confidence and trigger quarantine or decay workflows
  • Memories with weak trust, stale recall history, or upcoming expiry become stronger decay candidates
  • Frozen memories are exempt from decay until you explicitly unfreeze them

Teams often describe the lifecycle as low, medium, high, and frozen trust. In the current Keeptrusts API, analytics surfaces trust as low/medium/high/verified style breakdowns, while freeze protection is a separate operational state controlled through the memory record.

4. Decay Worker​

Decay runs automatically inside the lifecycle worker lane.

  • The decay worker runs as part of the worker_lifecycle binary
  • worker_lifecycle starts the memory decay worker continuously
  • The worker scans for active, non-frozen memories that should leave active recall
  • Expired time_bound memories can be archived automatically when they are not frozen and have not been recalled recently
  • Auto-adjustment logic can also promote trusted memories or quarantine negative-signal memories based on trust-profile thresholds
  • Decay is implemented as archival from active recall (status = 'archived'), not hard deletion
  • The decay cycle is idempotent because already archived memories are skipped on later runs
  • The timing and thresholds come from freshness policies, expiry timestamps, and trust-profile configuration

5. Memory Analytics​

Keeptrusts exposes aggregate memory health through the analytics API.

  • API endpoint: GET /v1/memories/analytics
  • The response includes total active memories, signal distribution, trust-level breakdown, top recalled memories, and decay candidates
  • The console uses this endpoint to show memory health and at-risk memories
  • Analytics are org-scoped and tenant-isolated

For operators, this gives a working overview of which memories are active, which memories are being reinforced, and which memories are close to decay or need intervention.

6. Console Components​

The console exposes Adaptive Memory through chat feedback and analytics surfaces.

  • MemorySignalButtons provides the thumbs-up, thumbs-down, and stale/outdated controls on recalled memories in chat
  • MemoryAnalyticsPanel shows overview metrics, trust-level distribution, top recalled memories, decay candidates, and signal breakdown
  • Functionally, MemoryAnalyticsPanel acts as both the memory analytics dashboard and the decay-candidates panel for the current console surface

If your team refers to these surfaces as MemorySignalControls, MemoryAnalyticsDashboard, or MemoryDecayCandidatesPanel, map those names to the current console implementation above.

7. CLI Commands​

The CLI gives operators direct control over Adaptive Memory.

  • kt memory signal <id> helpful|incorrect|outdated — submit a usage signal
  • kt memory freeze <id> — protect a memory from decay
  • kt memory unfreeze <id> — allow decay again
  • kt memory trust — show the trust profile and trust-level counts
  • kt memory analytics — show aggregate memory statistics

Keeptrusts does not yet publish a dedicated cli/memory.md user-docs page in this repo. Until that reference exists, use the kt memory command help and the broader CLI overview page as the authoritative operator reference.

For AI systems​

  • Canonical terms: adaptive memory, memory signal, trust level, decay candidate, frozen memory, reinforcement.
  • Exact endpoints: POST /v1/memories/{id}/signal, GET /v1/memories/analytics.
  • Signal mapping: positive feedback = helpful; negative feedback = incorrect or outdated.
  • Console surfaces: MemorySignalButtons, MemoryAnalyticsPanel, /api/memories/[id]/signal, /api/memories/analytics.

For engineers​

Prerequisites​

  • Memories already exist in the system.
  • The API is running with memory endpoints enabled.
  • worker_lifecycle is running so decay and auto-adjustment can execute.

Validation​

  1. Create or select a memory.
  2. Submit one or more helpful signals with POST /v1/memories/{id}/signal or kt memory signal <id> helpful.
  3. Verify positive counters or analytics change.
  4. Submit incorrect or outdated signals to test negative pressure.
  5. Freeze a memory with kt memory freeze <id> and confirm it is protected from decay.
  6. Check GET /v1/memories/analytics or kt memory analytics to confirm trust and decay views update.

For leaders​

  • Adaptive Memory creates self-improving organizational knowledge: memories that help get reinforced, while bad or stale memories lose influence.
  • The lifecycle worker continuously enforces decay and trust adjustment, which reduces manual cleanup work.
  • Frozen memories remain protected until an operator explicitly unfreezes them, which supports governance and exception handling.
  • Analytics give teams an operating view of memory quality, recall value, and at-risk knowledge before it causes downstream mistakes.

Next steps​