Memory & persistence

How agent memory works

Nexus agents use a three-tier memory architecture inspired by cognitive science. The episodic buffer stores complete session traces for immediate retrieval. The compressed working memory distills important information from past sessions. The long-term consolidation store integrates learned patterns across all sessions. This architecture is detailed in our research paper on Persistent Memory for Agentic Workflows.

Enabling persistent memory

Persistent memory is configured in nexus.yaml. The default configuration retains 90 days of memory:

memory:
  persistent: true
  retention_days: 90

You can adjust retention based on your needs. Shorter retention reduces storage but limits cross-session learning:

memory:
  persistent: true
  retention_days: 30

Reviewing agent memory

You can inspect what your agent remembers using the CLI:

nexus memory --agent my-agent --list
nexus memory --agent my-agent --search "auth module"

The memory inspector shows stored facts, their confidence levels, and when they were learned. You can manually delete or correct entries that are inaccurate.

Knowledge bases

Knowledge bases extend agent memory with curated, team-wide information. Unlike agent memory (which is learned through experience), knowledge bases are explicitly authored:

nexus knowledge create --name "api-conventions" --file ./api-guide.md

Knowledge bases are shared across all agents in your organization. They are ideal for storing coding standards, architecture decisions, and operational runbooks.

Cross-session learning

The most powerful feature of persistent memory is cross-session learning. An agent that learns your team's coding conventions in session 1 will correctly apply them in session 10 without being reminded. This compounding effect makes agents increasingly effective over time. Our production data shows that agent efficiency improves by approximately 8% per week of operation with persistent memory enabled.

Memory tiers explained

Nexus agents use a sophisticated three-tier memory system inspired by cognitive science, described in depth in our research paper on Persistent Memory for Agentic Workflows. Understanding the tiers helps you configure memory optimally for your use case.

Tier 1: Episodic Buffer. Stores complete session traces including every action, tool call, and observation. This is the agent's short-term memory, optimized for fast retrieval of recent context. The buffer retains the most recent 200 sessions or 7 days of activity. Retrieval takes under 50ms and supports similarity search. When the buffer is full, older sessions are compressed and moved to Tier 2.

Tier 2: Compressed Working Memory. Important information from the episodic buffer is distilled into compact key-value pairs. The agent applies an attention-based compression that retains the ~12% of information most predictive of future task success, achieving 12x compression with 94% information retention. The working memory holds up to 10,000 entries and retains information for up to 90 days. Entries with low confidence or infrequent access are automatically evicted.

Tier 3: Long-Term Consolidation. Knowledge that has been consistently reinforced across multiple sessions is consolidated into permanent storage using Elastic Weight Consolidation (EWC). This tier has unlimited capacity and permanent retention. Consolidated knowledge cannot be evicted by normal operations ? it must be explicitly deleted. This tier is shared across all agents in your organization, enabling team-wide knowledge transfer.

Inspecting and managing memory

The CLI provides several commands for memory inspection. List all stored memories: nexus memory --agent my-agent --list shows every key-value pair with its confidence score, tier, last-access timestamp, and source session. Search by keyword: nexus memory --agent my-agent --search "deployment config" performs semantic search across all tiers and returns the most relevant entries. View memory statistics: nexus memory --agent my-agent --stats shows total entries per tier, storage usage, hit rate, and consolidation rate.

Memory management operations: Delete an entry: nexus memory --agent my-agent --delete --id "mem_abc123". Use when the agent has learned incorrect information. Correct an entry: nexus memory --agent my-agent --correct --id "mem_abc123" --value "correct value". Clear all memory: nexus memory --agent my-agent --clear (requires confirmation). This forces the agent to re-learn from scratch ? useful when switching projects or after major architecture changes.

Troubleshooting memory issues

Issue: Agent forgets information between sessions. Check that persistent: true is set in nexus.yaml. If it is, check the retention_days setting ? if set too low, information may be evicted before the next session. Run nexus memory --agent my-agent --stats to see if the episodic buffer is full (200 sessions max). If so, the agent may be cycling through sessions too quickly. Increase retention or reduce session frequency.

Issue: Agent has outdated or incorrect information. Use the memory inspector to find the offending entry: nexus memory --agent my-agent --search "topic". Correct or delete the entry, then inform the agent of the correction. The agent will update its understanding in the next session. For systematic issues, consider using knowledge bases instead of relying on learned memory for facts that change frequently.

Issue: Memory storage costs are too high. Reduce retention_days (try 30 instead of 90). Set tier: compact in nexus.yaml to skip full episodic storage and go directly to compressed working memory. Use targeted knowledge bases instead of general memory for projects with well-defined documentation.

Memory best practices

From production experience across 800+ organizations, we recommend: (1) Use knowledge bases for stable truths ? coding conventions, architecture decisions, API contracts. Agent memory is best for learned patterns and project-specific insights. (2) Review memory periodically ? schedule a weekly review of learned memories. Incorrect or outdated memories compound over time. (3) Name your agents consistently ? the same agent name across sessions enables cross-session learning. Creating new agents for each session resets memory. (4) Be explicit in task descriptions ? agents form stronger memories when tasks include clear context and success criteria. Vague tasks produce weak, low-confidence memories.

Knowledge base management

Knowledge bases are explicitly authored collections of facts that supplement agent memory. Unlike learned memory (which is implicit and confidence-weighted), knowledge bases are authoritative: agents treat knowledge base entries as ground truth. This makes them ideal for information that should not be learned through trial and error.

Create a knowledge base from a file:

nexus knowledge create --name "api-conventions" --file ./api-guide.md

List, update, and delete knowledge bases:

nexus knowledge list
nexus knowledge update --name "api-conventions" --file ./api-guide-v2.md
nexus knowledge delete --name "api-conventions"

Knowledge bases support the following file formats: Markdown (best for documentation-style knowledge), YAML (structured data, configuration rules), JSON (data dictionaries, API schemas), and plain text (simple facts). Files are automatically chunked and indexed for semantic retrieval.

Memory API reference

The memory system exposes a programmatic API for advanced use cases. Use the SDK to query and manage memories:

import { Nexus } from "@nexus/sdk";
const nexus = new Nexus({ apiKey: "nk_..." });

// Query agent memory
const memories = await nexus.memory.query({
  agent: "my-agent",
  search: "deployment configuration",
  limit: 10,
  min_confidence: 0.7,
});

// Get memory statistics
const stats = await nexus.memory.stats("my-agent");
console.log(stats.tier1.entries, stats.tier2.entries, stats.tier3.entries);

// Manually add knowledge to memory
await nexus.memory.add({
  agent: "my-agent",
  key: "project:deployment:strategy",
  value: "Blue-green with automated rollback",
  source: "engineering-decision-log",
  confidence: 0.95,
});

Next steps

With memory configured, proceed to Step 6: Production deployment to learn how to deploy agents at scale with CI/CD, monitoring, and team management.