Skip to content
AgentCTX

Memory & Persistence

Memory & Persistence

Section titled “Memory & Persistence”

AgentCTX’s memory system gives agents persistent, cross-session storage organized in five layers. This guide covers how to store, retrieve, and manage memories effectively.

The 5-Layer Architecture

Section titled “The 5-Layer Architecture”
Layer 5: Global        ← Platform-wide facts (shared by all agents everywhere)
Layer 4: Organization  ← Org-wide knowledge
Layer 3: Team          ← Shared within a team
Layer 2: Individual    ← Per-agent, cross-session
Layer 1: Ephemeral     ← Single session only (auto-expires)

Each layer has different persistence and sharing characteristics.

Storing Memories

Section titled “Storing Memories”

Basic Storage

Section titled “Basic Storage”
+m "auth-decision" #arch "JWT for API, session tokens for WebSocket"

With Layer Tags

Section titled “With Layer Tags”
+m "personal-note" #my "I prefer factory pattern over singleton"
+m "team-convention" #team "All APIs use PASETO tokens"
+m "company-policy" #org "No PII in logs"
+m "universal-fact" #global "HTTP 429 means rate limited"
+m "quick-note" #ephemeral "Testing this in staging"

With Kind Tags

Section titled “With Kind Tags”
+m "bug-pattern" #lesson "Singleton breaks parallel tests"
+m "api-key-location" #fact "API key stored in 1Password vault 'DevOps'"
+m "ryan-timezone" #preference "Prefers US Central timezone"

Retrieving Memories

Section titled “Retrieving Memories”

By Tag

Section titled “By Tag”
?m #arch @7d ^5         Architecture decisions from last week (top 5)
?m #my #lesson @30d     My lessons from the last month
?m #team                All team memories

By Similarity

Section titled “By Similarity”
?m @similar "auth-decision" #k:5   5 most similar memories to "auth-decision"

By Graph Traversal

Section titled “By Graph Traversal”
?m @traverse auth-decision #depth:3   Follow relationships 3 levels deep

By Time Window

Section titled “By Time Window”
?m @7d                  Last 7 days
?m @2h                  Last 2 hours
?m @2026-03-01          Since March 1st

Updating Memories

Section titled “Updating Memories”
~m auth-decision "Updated: switched from JWT to PASETO tokens"

Deleting Memories

Section titled “Deleting Memories”
-m obsolete-decision

Memory Decay

Section titled “Memory Decay”

Memories naturally decay in relevance over time. The decay system:

  • Assigns each memory a relevance score (0.0 to 1.0)
  • Decrements the score over time unless the memory is accessed
  • Low-scoring memories can be archived or pruned
  • Agents can query with a decay threshold:
?m @decay #threshold:0.7    Only memories with relevance > 0.7

Reinforcing Memories

Section titled “Reinforcing Memories”

Accessing a memory resets its decay timer. Frequently accessed memories stay fresh. This creates a natural LRU-like behavior without manual cleanup.

Memory Consensus

Section titled “Memory Consensus”

In multi-agent teams, memories can be confirmed by multiple agents:

Agent A: +m "api-pattern" #team "Use PASETO for all new APIs"
Agent B: ~m api-pattern #team +confirm
Agent C: ~m api-pattern #team +confirm

Consensus-backed memories have higher trust scores and resist decay.

Graph Relationships

Section titled “Graph Relationships”

Create relationships between memories:

+m @relate auth-decision->informs->api-design "JWT choice shapes API surface"
+m @relate api-design->requires->token-refresh "PASETO needs refresh flow"

Then traverse them:

?m @traverse auth-decision #depth:3

Returns the full relationship graph starting from auth-decision.

Live Subscriptions

Section titled “Live Subscriptions”

Subscribe to memory changes in real-time:

?m #team #live     Subscribe to team memory updates
?m #live #diff     Get change deltas instead of full results

Uses SurrealDB’s LIVE SELECT for push-based updates.

Best Practices

Section titled “Best Practices”
  1. Tag everything — use layer + kind tags consistently
  2. Keep it structured — short keys, descriptive payloads
  3. Don’t over-store — if it’s in the knowledge plane, don’t duplicate in memory
  4. Use #ephemeral — for session-specific notes that shouldn’t persist
  5. Let decay work — trust the system to prune stale memories

See Also

Section titled “See Also”