TealMemory

TealMemory is a governance module that controls what AI agents can write to and read from memory. It enforces scope boundaries, data classification, and content policies across 5 memory scopes and 4 classification levels.

Overview

Agentic AI systems increasingly use persistent memory — session state, user preferences, shared knowledge bases. Without governance, agents can leak secrets into memory, read across scope boundaries, or store sensitive data in inappropriate classifications. TealMemory introduces 5 new decision actions specifically for memory governance:

Action	Description
`ALLOW_WRITE`	Allow the memory write
`DENY_WRITE`	Block the memory write
`REDACT_AND_WRITE`	Redact sensitive content, then write
`STORE_SUMMARY_ONLY`	Store a summary instead of full content
`DENY_READ`	Block the memory read

5 Memory Scopes

Session, agent, user, shared, and global

4 Classifications

Public, internal, confidential, and restricted

Quick Start

import { TealEngineV12, TealMemory } from 'tealtiger';

const engine = new TealEngineV12({
  policy: {
    memory: {
      default_scope: 'session',
      classification: 'internal',
      deny_secrets_in_memory: true
    }
  },
  modules: [new TealMemory()]
});

// Write governance
const writeDecision = await engine.evaluateV12(
  {
    content: 'User prefers dark mode',
    memory_operation: 'write',
    memory_scope: 'user'
  },
  { correlation_id: 'mem-001', user_id: 'user-456' }
);
// writeDecision.action === 'ALLOW_WRITE'

// Write with secret → denied
const secretWrite = await engine.evaluateV12(
  {
    content: 'API key: sk-proj-abc123...',
    memory_operation: 'write',
    memory_scope: 'shared'
  },
  { correlation_id: 'mem-002', user_id: 'user-456' }
);
// secretWrite.action === 'DENY_WRITE'
// secretWrite.reason_codes === ['MEMORY_WRITE_DENIED_SECRET']

Memory Scopes

TealMemory defines 5 hierarchical scopes:

Scope	Visibility	Lifetime	Example
session	Current session only	Session duration	Conversation context
agent	Single agent instance	Agent lifetime	Agent working memory
user	All sessions for a user	Persistent	User preferences
shared	Multiple agents/users	Persistent	Team knowledge base
global	Entire system	Persistent	System configuration

Scope Hierarchy

Writes to broader scopes require higher classification clearance:

session → agent → user → shared → global
  (least restrictive)        (most restrictive)

Writing to global scope with internal classification triggers MEMORY_SCOPE_VIOLATION.

Data Classifications

Every memory entry has a classification level:

Classification	Description	Allowed Scopes
public	No restrictions	All scopes
internal	Organization-internal	session, agent, user
confidential	Sensitive business data	session, agent
restricted	Highly sensitive (PII, secrets)	session only

Classification Enforcement

// Attempting to write confidential data to shared scope
const decision = await engine.evaluateV12(
  {
    content: 'Q3 revenue projections...',
    memory_operation: 'write',
    memory_scope: 'shared',
    classification: 'confidential'
  },
  { correlation_id: 'mem-003' }
);

// decision.action === 'DENY_WRITE'
// decision.reason_codes === ['MEMORY_SCOPE_VIOLATION']

Policy Configuration

Configure TealMemory through the memory key in your policy:

const engine = new TealEngineV12({
  policy: {
    memory: {
      // Default scope for writes without explicit scope
      default_scope: 'session',

      // Default classification level
      classification: 'internal',

      // Block secrets from being written to memory
      deny_secrets_in_memory: true,

      // Block PII from being written to memory
      deny_pii_in_memory: true,

      // Redact instead of deny for PII
      redact_pii_on_write: true,

      // Store summaries for large content
      summary_threshold_chars: 10000,

      // Scope-specific overrides
      scopes: {
        global: { classification_required: 'public' },
        shared: { classification_required: 'public' },
        user: { classification_required: 'internal' }
      }
    }
  },
  modules: [new TealMemory()]
});

Write Governance

TealMemory evaluates every memory write against scope, classification, and content policies.

ALLOW_WRITE

Content passes all checks — write proceeds.

const decision = await engine.evaluateV12(
  {
    content: 'User timezone: America/New_York',
    memory_operation: 'write',
    memory_scope: 'user'
  },
  { correlation_id: 'mem-004', user_id: 'user-456' }
);
// decision.action === 'ALLOW_WRITE'

DENY_WRITE

Content violates a policy — write is blocked.

const decision = await engine.evaluateV12(
  {
    content: 'SSN: 123-45-6789',
    memory_operation: 'write',
    memory_scope: 'shared'
  },
  { correlation_id: 'mem-005' }
);
// decision.action === 'DENY_WRITE'
// decision.reason_codes === ['MEMORY_WRITE_DENIED_PII']

REDACT_AND_WRITE

Sensitive content is redacted before writing.

const decision = await engine.evaluateV12(
  {
    content: 'Contact email: [email protected], phone: 555-0123',
    memory_operation: 'write',
    memory_scope: 'agent'
  },
  { correlation_id: 'mem-006' }
);
// decision.action === 'REDACT_AND_WRITE'
// decision.reason_codes === ['MEMORY_WRITE_REDACTED']

STORE_SUMMARY_ONLY

Large or sensitive content is summarized before storage.

const decision = await engine.evaluateV12(
  {
    content: longDocumentContent,  // > 10,000 chars
    memory_operation: 'write',
    memory_scope: 'user'
  },
  { correlation_id: 'mem-007' }
);
// decision.action === 'STORE_SUMMARY_ONLY'
// decision.reason_codes === ['MEMORY_WRITE_SUMMARY_ONLY']

Read Governance

TealMemory also governs memory reads, enforcing scope and classification boundaries.

DENY_READ

Agent attempts to read memory outside its scope or classification clearance.

const decision = await engine.evaluateV12(
  {
    memory_operation: 'read',
    memory_scope: 'global',
    agent_classification: 'internal'  // insufficient for global
  },
  { correlation_id: 'mem-008', agent_id: 'agent-001' }
);
// decision.action === 'DENY_READ'
// decision.reason_codes === ['MEMORY_READ_DENIED_CLASSIFICATION']

Reason Codes

Code	Severity	Default Action	When
`MEMORY_WRITE_DENIED_SECRET`	critical	DENY_WRITE	Secret detected in write content
`MEMORY_WRITE_DENIED_PII`	high	DENY_WRITE	PII detected in write content
`MEMORY_WRITE_REDACTED`	medium	REDACT_AND_WRITE	Content redacted before write
`MEMORY_WRITE_SUMMARY_ONLY`	medium	STORE_SUMMARY_ONLY	Content summarized before write
`MEMORY_SCOPE_VIOLATION`	high	DENY_READ	Scope boundary violated
`MEMORY_READ_DENIED_CLASSIFICATION`	high	DENY_READ	Classification clearance insufficient

Event Types

Event Type	Description
`memory.write`	Memory write governance check
`memory.read`	Memory read governance check
`memory.retention`	Memory retention policy check

Python

from tealtiger import TealEngineV12, TealMemory

engine = TealEngineV12(
    policy={
        "memory": {
            "default_scope": "session",
            "classification": "internal",
            "deny_secrets_in_memory": True
        }
    },
    modules=[TealMemory()]
)

decision = await engine.evaluate_v12(
    request={
        "content": "User prefers dark mode",
        "memory_operation": "write",
        "memory_scope": "user"
    },
    ctx={"correlation_id": "mem-009", "user_id": "user-456"}
)

Getting Started

Core Concepts

Governance Domains

Policy Authoring

Architecture

Integrations

Deployment

API Reference

Cookbook

Compliance & GRC

Guides

Reference

Versions

Playground

Dashboard

Blog

Overview

5 Memory Scopes

4 Classifications

Quick Start

Memory Scopes

Scope Hierarchy

Data Classifications

Classification Enforcement

Policy Configuration

Write Governance

ALLOW_WRITE

DENY_WRITE

REDACT_AND_WRITE

STORE_SUMMARY_ONLY

Read Governance

DENY_READ

Reason Codes

Event Types

Python

​Overview

5 Memory Scopes

4 Classifications

​Quick Start

​Memory Scopes

​Scope Hierarchy

​Data Classifications

​Classification Enforcement

​Policy Configuration

​Write Governance

​ALLOW_WRITE

​DENY_WRITE

​REDACT_AND_WRITE

​STORE_SUMMARY_ONLY

​Read Governance

​DENY_READ

​Reason Codes

​Event Types

​Python

​Related Documentation

Overview

Quick Start

Memory Scopes

Scope Hierarchy

Data Classifications

Classification Enforcement

Policy Configuration

Write Governance

ALLOW_WRITE

DENY_WRITE

REDACT_AND_WRITE

STORE_SUMMARY_ONLY

Read Governance

DENY_READ

Reason Codes

Event Types

Python

Related Documentation