Using Memory

Using Memory

Purpose

Memory and knowledge transform agents from stateless tools into learning entities. Instead of starting fresh each run, agents can:

• Recall what worked before
• Avoid repeating mistakes
• Apply organization-specific knowledge
• Build expertise over time

Altertable distinguishes knowledge entries from memories:

• Knowledge entries are durable reference material added by the team or synced from repositories. Use create_knowledge only when the user wants a stable source of truth recorded exactly.
• Memories are learned observations from agent work, notifications, discoveries, and feedback. Use memory tools for patterns, preferences, and working context learned through analysis.

When to Search

At the start of every workflow - proactively recall relevant context before taking action.

Search when:

• Beginning a new analysis
• Before creating discoveries or insights
• When context from past runs would help
• When working with familiar entities (tables, metrics, users)
• When initialize returns relevant knowledge entries, read them before deciding

When to Create

Only after something valuable happens - quality over quantity.

Create a memory when:

• A discovery was approved or rejected (learn from feedback)
• You found an organization-specific pattern or threshold
• A technique worked well (or failed in a specific context)
• You learned something that would help future runs

Create a knowledge entry when:

• The user gives a canonical metric definition, business rule, or operating procedure
• The content should be durable, searchable, and applied exactly in future work
• The source of truth is not already available through a connected repository or semantic model

Do not create memories for:

• Routine success ("query returned results")
• Minor details ("table has 1M rows")
• Information easily re-discoverable
• Duplicates of existing memories
• Stable definitions that belong in the semantic layer or a knowledge entry instead

Memory Types

Episodic - What Happened

Record specific events with outcomes.

Use when: Something happened that you should remember

• Discovery was created, approved, or rejected
• Analysis succeeded or failed
• User gave feedback

Include: The outcome (success, failure, rejected, approved)

Example: "Created DSC-789 for 15% revenue drop. User rejected - said threshold should be 20%."

Semantic - What You Know

Record facts and knowledge independent of specific events.

Use when: You learned a fact or pattern

• Organization prefers certain thresholds
• Data has specific characteristics
• Business rules or preferences

Include: Confidence level if uncertain

Example: "Organization ignores metric changes under 20% - confirmed by user feedback."

Procedural - How To Do Things

Record techniques and approaches that work.

Use when: You discovered a technique

• Query pattern that performs well
• Workaround for a limitation
• Best practice for a specific situation

Include: Success rate and failure contexts

Example: "For sales table: use date_trunc with timezone filter for accurate daily aggregations. Fails without timezone on UTC data."

Decision Tree

1. Did something HAPPEN? (event with outcome)

→ Episodic

1. Did you LEARN A FACT? (pattern, threshold, preference)

→ Semantic

1. Did you DISCOVER A TECHNIQUE? (approach, workaround)

→ Procedural

1. None of the above?

→ Probably not worth saving

Decision Matrix

Quick reference for common situations:

| Situation | Type | Scope | Importance | Decay | |-----------|------|-------|------------|-------| | Discovery approved | Episodic | Workflow | 8 | Weekly | | Discovery rejected with feedback | Episodic | Workflow | 9 | Monthly | | User stated preference | Semantic | Organization | 9 | Monthly | | Data pattern found | Semantic | Organization | 7 | Weekly | | Query optimization worked | Procedural | Organization | 8 | Monthly | | Workaround for edge case | Procedural | Workflow | 6 | Weekly | | Entity-specific behavior | Semantic | Entity | 7 | Weekly | | Workflow failed for specific reason | Episodic | Workflow | 8 | Weekly | | Business rule confirmed | Semantic | Organization | 9 | Monthly | | Technique failed in context | Procedural | Workflow | 7 | Weekly |

Memory Scopes

Organization

Knowledge that applies to everyone in the org.

• Business rules and thresholds
• Company-wide preferences
• Domain terminology

Workflow

Context specific to this workflow type.

• Patterns for this analysis type
• Workflow-specific learnings

Agent

Knowledge private to a specific agent.

• Agent-specific optimizations
• Personal learnings
• Specialized expertise

Entity

Facts about a specific entity (insight, discovery, table).

• Entity-specific preferences
• Historical context for that entity

Scope Decision Tree

1. Does this apply to the entire organization?

→ Organization

1. Is this specific to this workflow type?

→ Workflow

1. **Is this about a specific entity (INS-, DSC-)?**

→ Entity

1. Is this my personal learning/optimization?

→ Agent

Source Linking

Link memories to specific entities when relevant:

• Insights: INS-123
• Discoveries: DSC-456
• Segments: SGM-789
• Dashboards: DSH-101

This enables searching for all memories related to a specific entity.

Importance

Rate importance honestly - it affects how long memories persist.

| Score | Meaning | Examples | |-------|---------|----------| | 9-10 | Critical | Major outage cause, critical business rule | | 7-8 | Valuable | Clear pattern, confirmed preference | | 5-6 | Moderate | Potentially useful, unconfirmed | | 1-4 | Low | Minor detail, easily rediscovered |

Guideline: Only save memories with importance >= 7. Lower importance creates noise.

Forgetting Curve

Memories decay over time without reinforcement.

• Searching reinforces memories (they stay relevant longer)
• Higher importance = slower decay
• Frequent access = slower decay

Decay rates:

• Daily - Session context, temporary learnings
• Weekly - Short-term patterns (default)
• Monthly - Core knowledge, stable facts

Consolidation

Over time, the system automatically:

Episodic → Semantic: When multiple similar events occur, they get abstracted into a general pattern.

• 3+ similar episodic memories → 1 semantic memory
• Example: "Revenue drop triggered discovery" (x3) → "Revenue anomalies consistently trigger discoveries"

Procedural merging: Similar techniques get consolidated into best practices.

• Preserves success rates and failure contexts

Scope promotion: Patterns seen across multiple workflows get promoted to organization scope.

• Workflow patterns that repeat → Organization-level knowledge

Writing Effective Content

Good memories are specific, actionable, and include context.

Good vs Bad Examples

| Bad | Good | |-----|------| | "Revenue issue" | "Revenue dropped 15% in Q4 due to seasonal churn" | | "User didn't like it" | "User rejected DSC-123 - said 10% threshold is too low, prefers 20%" | | "Query was slow" | "Sales table aggregation: use date_trunc with index, reduced from 30s to 2s" | | "Something about funnels" | "Funnel analysis requires strict event ordering for accurate conversion rates" |

Content Checklist

• What happened or what did you learn? (the core fact)
• Why does it matter? (impact or implication)
• What should change? (actionable guidance)
• Any constraints? (when this applies or doesn't)

Best Practices

Searching

• Search broadly at workflow start
• Use natural language queries
• Filter by type when you know what you need
• Search parent scopes to find org-level knowledge

Creating

• Be specific, not vague
• Include context that makes the memory actionable
• Set importance honestly
• Add relevant tags for discoverability
• Link to entities when applicable

Quality Over Quantity

• One high-quality memory > many low-quality ones
• If unsure whether to save, don't
• Duplicate memories create noise
• Let unimportant memories decay naturally

Common Pitfalls

• Not searching at workflow start (missing valuable context)
• Saving everything (creates noise, reduces signal)
• Vague content ("something happened with revenue")
• Wrong type selection (fact stored as event)
• Importance inflation (everything marked as 9-10)
• Missing outcome for episodic memories
• Missing success_rate for procedural memories

Troubleshooting

Search returns no results:

• Broaden query terms (use synonyms, related concepts)
• Search parent scopes (workflow → organization)
• Check if memories existed but decayed (low importance + no recent access)

Search returns low relevance:

• Refine query to be more specific
• Filter by memory type if you know what you need
• Results may have decayed - consider if re-learning is needed

Expected memory is missing:

• May have decayed due to low importance or infrequent access
• Check if it was saved at wrong scope (entity vs workflow)
• Re-create if the knowledge is still valuable

Too much noise in results:

• Be more selective when creating (importance >= 7)
• Let low-value memories decay naturally
• Use more specific search queries

Reference Files

• [Memory types](references/memory-types.md) - Read when choosing between episodic, semantic, and procedural memory types
• [Memory scopes](references/memory-scopes.md) - Read when deciding the right scope (organization, workflow, agent, entity, user)
• [Forgetting curve](references/forgetting-curve.md) - Read when tuning decay rates or understanding why memories disappeared

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: altertable-ai
• Source: altertable-ai/skills
• License: MIT
• Homepage: https://altertable.ai

Install and usage instructions live in the source repository linked above.