@reactive-agents/memory

Version: 0.10.3 — memory system for Reactive Agents.

Four memory tiers — Working, Semantic, Episodic, Procedural — backed by bun:sqlite with FTS5 full-text search (Tier 1) and optional sqlite-vec KNN vectors (Tier 2). Plus an ExperienceStore for cross-agent learning, a background MemoryConsolidator (decay + summarization), a Zettelkasten link index, and the SessionStore that powers gateway chat mode.

Installation

bun add @reactive-agents/memory

Requires Bun — uses bun:sqlite natively. Tier 2 also requires the sqlite-vec extension, which bun:sqlite loads at runtime.

Memory tiers

| Service | Purpose | Backend | |---|---|---| | WorkingMemoryService | Short-term in-session items, LRU-evicted | SQLite (in-memory or file) | | SemanticMemoryService | Long-term knowledge, FTS5 + optional vec | SQLite + FTS5 | | EpisodicMemoryService | Conversation / session history (turns, snapshots) | SQLite | | ProceduralMemoryService | Learned workflows / step sequences | SQLite |

Cross-cutting:

• ExperienceStore — per-(agent, model) records of tool patterns, error recoveries, success signals; consumed by the calibration system.
• MemoryConsolidatorService — background decay + summarization; rolls older episodic turns into compact summaries.
• ZettelkastenService — bidirectional links between memory entries.
• SessionStoreService — persistent (platform, sender) chat sessions (used by gateway chat mode).
• SkillStoreService / DebriefStoreService / PlanStoreService — auxiliary stores for the kernel and skill system.
• AgentMemoryFromMemoryService — port adapter that satisfies the narrow AgentMemory Tag in @reactive-agents/core from a MemoryService provider.

Two retrieval tiers

• Tier 1 — FTS5. Fast, deterministic keyword search; no embeddings required. Best for short, key-term queries. Verbose natural-language queries should be decomposed first.
• Tier 2 — vector search. sqlite-vec KNN; requires an embedding provider (OpenAI, Anthropic-compatible, or Ollama).

Quick example

import { ReactiveAgents } from "@reactive-agents/runtime";

const agent = await ReactiveAgents.create()
  .withName("my-agent")
  .withProvider("anthropic")
  .withModel("claude-sonnet-4-20250514")
  .withMemory("1") // "1" = FTS5; "2" = vector embeddings
  .build();

const r1 = await agent.run("Remember that my favorite color is blue.");
const r2 = await agent.run("What's my favorite color?"); // recalls 'blue'

For finer control, withMemory({ tier, dbPath, working, semantic, episodic, procedural }) exposes per-service options.

Direct service usage

import { Effect, Layer } from "effect";
import {
  MemoryServiceLive,
  SemanticMemoryService,
  ExperienceStoreLive,
  createMemoryLayer,
} from "@reactive-agents/memory";

const layer = createMemoryLayer({ tier: "1", dbPath: "./memory.db" });

await Effect.runPromise(
  Effect.gen(function* () {
    const sem = yield* SemanticMemoryService;
    yield* sem.store({ content: "RAFT is a consensus algorithm...", tags: ["distsys"] });
    return yield* sem.search({ query: "consensus", limit: 5 });
  }).pipe(Effect.provide(layer)),
);

Environment variables (Tier 2 only)

EMBEDDING_PROVIDER=openai          # openai | anthropic | ollama | custom
EMBEDDING_MODEL=text-embedding-3-small
OPENAI_API_KEY=sk-...

Gateway chat session persistence

When .withGateway() and .withChannels() are combined in chat mode, the runtime uses SessionStoreService from this package to persist (platform, senderId) conversations across process restarts. Each session is windowed (40 turns / 8 KiB), compacted daily, and pruned by TTL.

Experience store (cross-agent learning)

import { ExperienceStore } from "@reactive-agents/memory";

const exp = yield* ExperienceStore;
yield* exp.record({
  agentId: "researcher",
  modelId: "claude-sonnet-4-20250514",
  toolName: "web-search",
  outcome: "success",
  /* ... */
});

const summary = yield* exp.queryByModel("claude-sonnet-4-20250514");

ExperienceSummary materialization feeds the calibration system in @reactive-agents/llm-provider.

Documentation

• Memory guide: docs.reactiveagents.dev/guides/memory/
• Calibration: docs.reactiveagents.dev/guides/calibration/
• Related: @reactive-agents/runtime, @reactive-agents/llm-provider, @reactive-agents/gateway.

License

MIT