tylerjrbuell/memory-patterns

Memory Patterns

Agent objective

Produce a builder with the right memory tier, database path, and tool configuration so the agent retains and retrieves knowledge correctly across interactions and sessions.

When to load this skill

• Agent needs to remember facts across multiple agent.run() calls
• Agent accumulates knowledge over time (research, learning, preference tracking)
• Building a conversational agent with multi-turn context
• Agent must search past observations semantically (recall) or by key (find)

Implementation baseline

// Standard (in-memory only — lost on restart)
const agent = await ReactiveAgents.create()
  .withProvider("anthropic")
  .withReasoning({ defaultStrategy: "adaptive" })
  .withTools({ allowedTools: ["checkpoint", "recall"] })
  .withMemory()   // "standard" tier — working + semantic, in-memory
  .build();

// Enhanced (SQLite persistence — survives restarts)
const agent = await ReactiveAgents.create()
  .withProvider("anthropic")
  .withReasoning({ defaultStrategy: "adaptive" })
  .withTools({ allowedTools: ["checkpoint", "recall", "find"] })
  .withMemory({ tier: "enhanced", dbPath: "./agent-memory.db" })
  .build();

4-layer memory architecture

| Layer | Purpose | Storage | Tier required | |-------|---------|---------|---------------| | Working | Current task context, active reasoning | In-memory | "standard" | | Semantic | Factual knowledge, SQLite + FTS5 full-text | SQLite | "standard" | | Episodic | Past interactions, timestamped experience log | SQLite | "enhanced" | | Procedural | Learned behaviors, skill patterns | SQLite | "enhanced" |

Key patterns

Memory tiers

// Standard — working + semantic, in-memory (fast, no persistence)
.withMemory()
.withMemory("standard")

// Enhanced — all 4 layers, SQLite persistence
.withMemory("enhanced")
.withMemory({ tier: "enhanced", dbPath: "./data/agent.db" })
.withMemory({ tier: "enhanced", dbPath: "./data/agent.db", capacity: 24 })
// capacity: max working memory entries (default varies)

Memory tools

// recall — semantic search over episodic + semantic memory
.withTools({ allowedTools: ["recall", "find", "checkpoint"] })

// In system prompt: guide the agent to use memory tools
.withSystemPrompt(`
  Before answering questions about past work, use recall("topic keywords").
  After completing a task, checkpoint the key findings.
`)

Combining memory with RAG documents

.withDocuments([
  { id: "docs-1", content: "Product documentation...", metadata: { source: "docs" } },
  { id: "policy-1", content: "Company policy...", metadata: { source: "policy" } },
])
.withMemory({ tier: "enhanced", dbPath: "./agent.db" })
.withTools({ allowedTools: ["find", "recall", "checkpoint"] })
// find: searches over .withDocuments() content (rag-search was removed in v0.10.0 — use find)
// find also searches semantic memory if memory is enabled
// recall: searches over past agent interactions in memory only

Multi-agent memory isolation

// Give each agent a separate DB to prevent cross-contamination
const researchAgent = await ReactiveAgents.create()
  .withMemory({ tier: "enhanced", dbPath: "./memory/researcher.db" })
  .build();

const writerAgent = await ReactiveAgents.create()
  .withMemory({ tier: "enhanced", dbPath: "./memory/writer.db" })
  .build();

Builder API reference

| Method | Key params | Notes | |--------|-----------|-------| | .withMemory(opts?) | "standard"\|"enhanced"\|{ tier, dbPath?, capacity? } | No args = "standard" | | .withDocuments(docs) | DocumentSpec[] | RAG context — pairs with find tool | | .withExperienceLearning() | — | Injects prior-run experience tips from episodic memory |

Pitfalls

• "1" and "2" are deprecated tier names — use "standard" and "enhanced"
• "enhanced" without dbPath uses a default path — always set dbPath explicitly in multi-agent environments to prevent collisions
• recall requires .withMemory() — silently returns empty results without it
• find routes across multiple sources: scope: "documents" needs .withDocuments(), scope: "memory" needs .withMemory(), scope: "web" needs web-search enabled, scope: "auto" (default) tries documents first, falls back to web
• SQLite requires a writable filesystem path — check permissions before deployment
• capacity too low causes premature eviction of working memory; keep at 12–24 for long tasks
• .withExperienceLearning() requires .withMemory({ tier: "enhanced" }) — without it, no experience is persisted to inject