> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/prd-shared/memory-architecture.md).

# Memory Architecture

## Memory Architecture: Implementation Guide & Research Foundations

> **Part of**: [Shared PRD](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/shared/README.md) | **Last Updated**: 2026-02-20
>
> This document is split into two parts. **Part 1** is a practical implementation guide — code snippets, schemas, and patterns for building the DeFi Brain memory subsystem inside `packages/safe/src/memory/`. **Part 2** is the research foundation — the cognitive science, retrieval, self-improvement, and production reliability research that informs the design. For MCP tool specifications (what the tool API looks like), see [07-tools-advanced.md](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md) Memory and Knowledge Tools section. For formal citations, see [research-citations.md](/docs/gotts-vaults/vault/research-citations.md).

***

## Part 1: Implementation Guide

How to build the DeFi Brain memory internals. All code targets the Gotts codebase conventions: viem, zod, MCP SDK (`@modelcontextprotocol/sdk`), strict TypeScript. Dependency versions match [12-dependencies.md](/docs/gotts-vaults/vault/12-dependencies.md).

***

### 1. File Structure & Init Sequence

Directory layout under `packages/safe/src/` (matches [04-architecture.md](/docs/gotts-vaults/vault/04-architecture.md)):

```
memory/
├── episodic.ts        # LanceDB episodic memory store
├── semantic.ts        # SQLite/sqlite-vec semantic memory store
├── consolidation.ts   # ExpeL distillation loop
├── decay.ts           # Importance-weighted retention scoring (P&L impact + regime tags)
└── embedder.ts        # Transformers.js embedding pipeline
```

Data directory (created at first run, gitignored):

```
data/
├── defi-brain.db      # SQLite: insights, structured data, vec0 tables
├── defi-brain/        # LanceDB: episodic memories (Lance columnar format)
└── models/            # Cached ONNX model files (~23MB q8)
```

**Initialization order** (matters — SQLite is synchronous, LanceDB is async, embedding model is lazy):

```typescript
// packages/safe/src/memory/init.ts
import { initSqlite } from "./semantic.js";
import { initLance } from "./episodic.js";
import { Embedder } from "./embedder.js";

export async function initMemory(dataDir: string) {
  // 1. SQLite opens synchronously — instant
  const sqlite = initSqlite(path.join(dataDir, "defi-brain.db"));

  // 2. LanceDB connects asynchronously — <100ms
  const lance = await initLance(path.join(dataDir, "defi-brain"));

  // 3. Embedding model loads lazily on first embed() call — 2-3s cold start
  //    Pre-warm if desired:
  await Embedder.embed("warmup");

  return { sqlite, lance };
}
```

**Resource footprint**: \~150-250MB RAM (dominated by ONNX Runtime + embedding model). Sub-millisecond SQLite queries. <25ms LanceDB vector search. Disk grows \~1KB/episode, \~500B/insight.

***

### 2. Storage Layer Setup

#### SQLite + sqlite-vec + Drizzle

`better-sqlite3` ^11.0.0 with `sqlite-vec` ^0.1.7 loaded as a native extension. WAL mode for concurrent reads during writes. `drizzle-orm` ^0.45.1 for type-safe queries.

```typescript
// packages/safe/src/memory/semantic.ts
import Database from "better-sqlite3";
import * as sqliteVec from "sqlite-vec";
import { drizzle } from "drizzle-orm/better-sqlite3";
import { migrate } from "drizzle-orm/better-sqlite3/migrator";
import * as schema from "./schema.js";

export function initSqlite(dbPath: string) {
  const sqlite = new Database(dbPath);
  sqlite.pragma("journal_mode = WAL");
  sqlite.pragma("synchronous = normal");
  sqlite.pragma("temp_store = memory");
  sqliteVec.load(sqlite);

  const db = drizzle({ client: sqlite, schema });
  migrate(db, { migrationsFolder: "./drizzle" });

  // vec0 virtual table (Drizzle can't define these — use raw SQL)
  sqlite.exec(`
    CREATE VIRTUAL TABLE IF NOT EXISTS vec_insights USING vec0(
      insight_id INTEGER PRIMARY KEY,
      embedding float[384],
      category TEXT,
      confidence REAL,
      +content TEXT,
      +last_validated TEXT
    );
  `);

  return { sqlite, db };
}
```

#### LanceDB

`@lancedb/lancedb` ^0.26.2. Lance columnar format — immutable fragments, automatic versioning, portable directory.

```typescript
// packages/safe/src/memory/episodic.ts
import * as lancedb from "@lancedb/lancedb";

export async function initLance(dir: string) {
  const db = await lancedb.connect(dir);

  const episodes = await db.createTable(
    "episodes",
    [
      {
        id: crypto.randomUUID(),
        vector: new Array(384).fill(0),
        text: "",
        tool: "init",
        outcome: "{}",
        chain: "base",
        tokenPair: "",
        timestamp: Date.now(),
      },
    ],
    { existsOk: true },
  );

  // Enable full-text search index for hybrid BM25+vector queries
  await episodes.createIndex("text", { config: lancedb.Index.fts() });

  return { db, episodes };
}
```

***

### 3. Schema Definitions

#### Drizzle `insights` table

```typescript
// packages/safe/src/memory/schema.ts
import { sqliteTable, text, integer, real } from "drizzle-orm/sqlite-core";

export const insights = sqliteTable("insights", {
  id: integer("id").primaryKey({ autoIncrement: true }),
  content: text("content").notNull(),
  category: text("category", {
    enum: [
      "slippage",
      "gas_timing",
      "route_selection",
      "pool_behavior",
      "mev_pattern",
      "liquidity_depth",
      "volatility",
      "fee_optimization",
      "rebalance_timing",
      "vault_strategy",
      "emergency",
      "general",
    ],
  }).notNull(),
  confidence: real("confidence").notNull().default(0.5),
  accessCount: integer("access_count").notNull().default(0),
  createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
  lastAccessed: integer("last_accessed", { mode: "timestamp" }).notNull(),
  stability: real("stability").notNull().default(604800), // TTL for volatile data only; see decay.ts importanceScore() for strategy-level retention
  chain: text("chain").default("base"),
  tokenPair: text("token_pair"),
});

export type Insight = typeof insights.$inferSelect;
export type NewInsight = typeof insights.$inferInsert;
```

Category enum matches [07-tools-advanced.md](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md) insight categories. Generate migrations with `npx drizzle-kit generate`, apply at startup via `migrate()`.

#### sqlite-vec KNN query

The `vec0` virtual table supports pre-filtered KNN in a single query:

```sql
SELECT insight_id, content, confidence, distance
FROM vec_insights
WHERE embedding MATCH ?query_vector
  AND k = 5
  AND category = 'slippage'
  AND confidence > 0.5
ORDER BY distance;
```

Brute-force search — no ANN indexes. Sub-millisecond for <10K vectors at 384 dimensions.

#### LanceDB episode structure

```typescript
interface Episode {
  id: string; // UUID
  vector: number[]; // 384-dim embedding
  text: string; // LLM-generated reflection
  tool: string; // 'swap' | 'rebalance' | 'deposit' | 'withdraw' | ...
  outcome: string; // JSON-serialized result
  chain: string; // 'base' | 'ethereum' | ...
  tokenPair: string; // 'WETH/USDC' | ...
  timestamp: number; // Unix ms
}
```

***

### 4. Embedding Pipeline

`@huggingface/transformers` ^3.8.1 with `Xenova/all-MiniLM-L6-v2` (384-dim, \~23MB q8). Runs via `onnxruntime-node` (native C++ bindings, auto-selected by Node.js).

The singleton stores the **pipeline Promise** (not the resolved pipeline) — prevents duplicate model downloads during concurrent startup calls:

```typescript
// packages/safe/src/memory/embedder.ts
import {
  pipeline,
  env,
  type FeatureExtractionPipeline,
} from "@huggingface/transformers";

env.cacheDir = "./data/models";

export class Embedder {
  private static instance: Promise<FeatureExtractionPipeline> | null = null;
  static readonly DIMS = 384;

  static getInstance(): Promise<FeatureExtractionPipeline> {
    if (!this.instance) {
      this.instance = pipeline(
        "feature-extraction",
        "Xenova/all-MiniLM-L6-v2",
        {
          dtype: "q8", // INT8 quantized: 23MB model, ~2x faster than fp32
        },
      ) as Promise<FeatureExtractionPipeline>;
    }
    return this.instance;
  }

  static async embed(text: string): Promise<number[]> {
    const extractor = await this.getInstance();
    const output = await extractor(text, { pooling: "mean", normalize: true });
    return Array.from(output.data as Float32Array);
  }

  static async embedBatch(texts: string[]): Promise<number[][]> {
    const extractor = await this.getInstance();
    const output = await extractor(texts, { pooling: "mean", normalize: true });
    return output.tolist() as number[][];
  }
}
```

**Key details**: `dtype: "q8"` loads INT8 quantized ONNX (\~95%+ similarity to fp32). \~150-250MB total process RAM. Set `env.allowRemoteModels = false` after initial download for air-gapped/TEE operation. First call triggers \~23MB Hugging Face download; subsequent calls use cache.

**Tier 1 upgrade**: Swap to `nomic-ai/nomic-embed-text-v1.5` (768-dim MRL, \~75MB q8) for 14x retrieval speedup via Matryoshka truncation. Drop-in replacement — same Transformers.js API, confirmed ONNX-ready. See Research Foundations §2.

***

### 5. Episode Storage (Reflexion)

After every write operation, generate a reflection and store it as an episodic memory in LanceDB.

```typescript
// packages/safe/src/memory/episodic.ts (continued)

export async function storeEpisode(
  episodes: lancedb.Table,
  episode: {
    tool: string;
    context: Record<string, unknown>;
    outcome: Record<string, unknown>;
    reflection: string;
    chain: string;
    tokenPair: string;
  },
) {
  const vector = await Embedder.embed(episode.reflection);
  await episodes.add([
    {
      id: crypto.randomUUID(),
      vector,
      text: episode.reflection,
      tool: episode.tool,
      outcome: JSON.stringify(episode.outcome),
      chain: episode.chain,
      tokenPair: episode.tokenPair,
      timestamp: Date.now(),
    },
  ]);
}
```

#### Hybrid search (BM25 + vector via RRF)

LanceDB's native hybrid search combines Tantivy-based BM25 full-text with vector ANN, merged via Reciprocal Rank Fusion. Keyword queries ("ETH/USDC 0.3% slippage") use BM25; semantic queries ("what happens during European hours") use vector similarity.

```typescript
export async function searchEpisodes(
  episodes: lancedb.Table,
  query: string,
  opts: { tool?: string; limit?: number } = {},
) {
  const queryVec = await Embedder.embed(query);
  const reranker = await lancedb.rerankers.RRFReranker.create();

  let q = episodes
    .query()
    .fullTextSearch(query)
    .nearestTo(queryVec)
    .rerank(reranker)
    .limit(opts.limit ?? 10);

  if (opts.tool) {
    q = q.where(`tool = '${opts.tool}'`);
  }

  return q.toArray();
}
```

At <100K vectors with 384-dim, flat brute-force is sufficient at 1-3ms. Create an IVF-PQ index only past 100K rows.

***

### 6. Insight Management (ExpeL)

Four operations against SQLite + sqlite-vec. Confidence changes are asymmetric for safety (DOWNVOTE has larger impact than UPVOTE).

```typescript
// packages/safe/src/memory/semantic.ts (continued)
import { eq, and, gte } from "drizzle-orm";
import { insights, type NewInsight } from "./schema.js";

// ADD — create new insight from recurring episode pattern
export async function addInsight(
  db: ReturnType<typeof drizzle>,
  sqlite: Database.Database,
  insight: {
    content: string;
    category: string;
    chain?: string;
    tokenPair?: string;
  },
) {
  const now = new Date();
  const [row] = await db
    .insert(insights)
    .values({
      content: insight.content,
      category: insight.category as NewInsight["category"],
      confidence: 0.6, // ExpeL default start
      stability: 604800, // 7 days
      createdAt: now,
      lastAccessed: now,
      chain: insight.chain ?? "base",
      tokenPair: insight.tokenPair ?? null,
    })
    .returning();

  // Sync embedding to vec0 table
  const vec = await Embedder.embed(insight.content);
  sqlite
    .prepare(
      "INSERT INTO vec_insights (insight_id, embedding, category, confidence, content, last_validated) VALUES (?, ?, ?, ?, ?, ?)",
    )
    .run(
      row.id,
      new Float32Array(vec),
      insight.category,
      0.6,
      insight.content,
      now.toISOString(),
    );

  return row;
}

// UPVOTE — similar episode validates existing insight
export async function upvoteInsight(
  db: ReturnType<typeof drizzle>,
  id: number,
) {
  const [row] = await db.select().from(insights).where(eq(insights.id, id));
  if (!row) return;
  const newConfidence = Math.min(1.0, row.confidence + 0.1);
  await db
    .update(insights)
    .set({
      confidence: newConfidence,
      lastAccessed: new Date(),
      accessCount: row.accessCount + 1,
    })
    .where(eq(insights.id, id));
}

// DOWNVOTE — episode contradicts existing insight (asymmetric: -0.15)
export async function downvoteInsight(
  db: ReturnType<typeof drizzle>,
  id: number,
) {
  const [row] = await db.select().from(insights).where(eq(insights.id, id));
  if (!row) return;
  const newConfidence = Math.max(0, row.confidence - 0.15);
  await db
    .update(insights)
    .set({ confidence: newConfidence, lastAccessed: new Date() })
    .where(eq(insights.id, id));
}

// EDIT — refine insight content (re-embeds, keeps confidence)
export async function editInsight(
  db: ReturnType<typeof drizzle>,
  sqlite: Database.Database,
  id: number,
  newContent: string,
) {
  await db
    .update(insights)
    .set({ content: newContent, lastAccessed: new Date() })
    .where(eq(insights.id, id));

  const vec = await Embedder.embed(newContent);
  sqlite
    .prepare(
      "UPDATE vec_insights SET embedding = ?, content = ? WHERE insight_id = ?",
    )
    .run(new Float32Array(vec), newContent, id);
}
```

***

### 7. Memory Decay

Retention is scored by **P\&L impact and regime relevance**, not elapsed time. DeFi memories should persist based on how consequential they were — not how recently they occurred. Old patterns become relevant again when market conditions revert.

```typescript
// packages/safe/src/memory/decay.ts

/**
 * Importance-weighted retention scoring.
 * Replaces Ebbinghaus time-decay: DeFi memories should persist
 * based on P&L impact and regime relevance, not elapsed time.
 *
 * Key insight: Ebbinghaus was derived from human memorization of nonsense
 * syllables. DeFi knowledge is semantically structured and regime-cycling —
 * old patterns become relevant again when market conditions revert.
 */

export interface RetentionFactors {
  plImpactBps: number; // Realized P&L impact (higher = more important to retain)
  regimeTag: string; // Regime at time of episode (for regime-conditional recall)
  accessCount: number; // How often this memory has been retrieved and used
  ageSeconds: number; // Only used for TTL on volatile data (gas prices)
}

/** Compute importance score for retention decisions. */
export function importanceScore(factors: RetentionFactors): number {
  const plComponent = Math.min(1.0, Math.abs(factors.plImpactBps) / 500); // caps at 500 bps
  const accessComponent = Math.min(0.3, factors.accessCount * 0.05);
  return Math.min(1.0, plComponent + accessComponent);
}

/**
 * Conditional decay rate multiplier based on P&L impact.
 * FadeMem (Wei et al., arXiv:2601.18642): important memories decay 3-5× slower,
 * not immortal. FinMem (Yu et al., arXiv:2311.13743): layered decay rates
 * α_shallow=0.9 (daily news) vs. α_deep=0.988 (annual reports / strategy patterns).
 */
export function decayRateMultiplier(factors: RetentionFactors): number {
  const absImpact = Math.abs(factors.plImpactBps);
  if (absImpact > 100) return 5.0; // High-impact: 5× slower decay
  if (absImpact > 50) return 2.0; // Medium-impact: 2× slower decay
  return 1.0; // Low-impact: standard TTL
}

/**
 * Should this insight be pruned from active context?
 * Combines importance-weighted decay with access frequency.
 * High-impact memories are NEVER hard-deleted, only archived.
 */
export function shouldPrune(
  factors: RetentionFactors,
  baseTtlSeconds: number,
): boolean {
  const effectiveTtl = baseTtlSeconds * decayRateMultiplier(factors);
  // Frequently accessed memories get TTL extended proportionally
  const accessBonus = Math.min(2.0, 1.0 + factors.accessCount * 0.2);
  return factors.ageSeconds > effectiveTtl * accessBonus;
}
// NOTE: Pruned = removed from active context, not hard-deleted.
// All episodes archived in LanceDB for regime-conditional recall.
```

**Retention policy by insight type** (importance-weighted conditional decay):

| Insight Type                             | Base TTL | Decay Multiplier | Notes                                      |
| ---------------------------------------- | -------- | ---------------- | ------------------------------------------ |
| MEV/exploit patterns                     | 365 days | 5×               | Archive only after TTL — may recur         |
| Emergency exit triggers                  | 365 days | 5×               | Critical safety knowledge                  |
| High-impact strategy episodes (>100 bps) | 180 days | 5×               | Regime-tagged; recalled when regime recurs |
| Medium-impact episodes (50–100 bps)      | 90 days  | 2×               | Retained across one regime cycle           |
| Slippage/route patterns                  | 30 days  | 1×               | Unless accessed > 3×                       |
| Gas price observations                   | 7 days   | 1×               | Highly volatile                            |
| Low-impact general observations          | 14 days  | 1×               | If accessCount < 2                         |

> **The STONE paradigm** (Luo et al., arXiv:2602.16192, 2026) advocates on-demand extraction rather than periodic batching: keep raw experiences in LanceDB and extract regime-relevant insights at query time. Note: this is a separate paradigm from Mem0 (arXiv:2504.19413), which uses an extraction-then-update pipeline with Add/Update/Delete/Merge operations.

Insights with importanceScore < 0.1 and ageSeconds > TTL are excluded from context injection but archived, not deleted — they may become relevant again in future regime shifts.

***

### 8. Context Injection Middleware

The retrieve-augment-execute-reflect-store loop wired into MCP tool calls. This middleware runs when the `learning` profile is active.

```typescript
// packages/safe/src/memory/middleware.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import { searchEpisodes } from "./episodic.js";
import { getRelevantInsights } from "./semantic.js";
import { Embedder } from "./embedder.js";
import { storeEpisode } from "./episodic.js";

/** Wrap an MCP tool handler with memory context injection. */
export function withMemory<T extends z.ZodRawShape>(
  handler: (
    args: z.infer<z.ZodObject<T>>,
    memoryContext: string,
  ) => Promise<unknown>,
) {
  return async (args: z.infer<z.ZodObject<T>>) => {
    // 1. RETRIEVE — query both stores for relevant context
    const query = JSON.stringify(args);
    const queryVec = await Embedder.embed(query);
    const [episodes, insights] = await Promise.all([
      searchEpisodes(lanceTable, query, { limit: 3 }),
      getRelevantInsights(drizzleDb, queryVec, {
        minConfidence: 0.5,
        limit: 5,
      }),
    ]);

    // 2. AUGMENT — format as context string for the handler
    const memoryContext = formatMemoryContext(insights, episodes);

    // 3. EXECUTE — run the tool with memory-informed parameters
    const result = await handler(args, memoryContext);

    // 4. REFLECT — generate post-execution reflection (via MCP sampling)
    const reflection = await generateReflection(args, result);

    // 5. STORE — save episode to LanceDB
    await storeEpisode(lanceTable, {
      tool: "swap", // derived from tool registration
      context: args,
      outcome: result as Record<string, unknown>,
      reflection,
      chain: ((args as Record<string, unknown>).chain as string) ?? "base",
      tokenPair: "", // derived from args
    });

    return result;
  };
}
```

**Safety constraint**: Memory only adjusts soft parameters (slippage tolerance within bounds, timing recommendations, route preferences). Memory **cannot override** safety limits, token allowlist, spending caps, simulation requirements, or circuit breakers. See [09-safety.md](/docs/gotts-safe-mcp-server/mcp-server/09-safety.md).

***

### 9. Consolidation Loop

Background interval that clusters recent episodes, extracts patterns via LLM, and applies ExpeL operations.

```typescript
// packages/safe/src/memory/consolidation.ts

const CONSOLIDATION_INTERVAL_MS = 4 * 60 * 60 * 1000; // 4 hours (configurable)

export function startConsolidationLoop(deps: {
  lance: lancedb.Table;
  db: ReturnType<typeof drizzle>;
  sqlite: Database.Database;
}) {
  return setInterval(async () => {
    // 1. Pull recent unconsolidated episodes from LanceDB
    const cutoff = Date.now() - CONSOLIDATION_INTERVAL_MS;
    const recent = await deps.lance
      .query()
      .where(`timestamp > ${cutoff}`)
      .limit(100)
      .toArray();

    if (recent.length < 3) return; // Not enough episodes to consolidate

    // 2. Cluster by tool + chain + tokenPair (matches 07-tools-advanced.md consolidation spec)
    const clusters = groupBy(
      recent,
      (e) => `${e.tool}:${e.chain}:${e.tokenPair}`,
    );

    // 3. For each cluster, ask LLM to extract patterns (via MCP sampling)
    for (const [key, episodes] of Object.entries(clusters)) {
      if (episodes.length < 2) continue;

      const prompt = buildExpeelPrompt(episodes, existingInsights);
      // LLM returns: { op: "ADD"|"UPVOTE"|"DOWNVOTE"|"EDIT", ... }
      const ops = await requestLlmConsolidation(prompt);

      // 4. Apply ExpeL operations
      for (const op of ops) {
        switch (op.type) {
          case "ADD":
            await addInsight(deps.db, deps.sqlite, op.insight);
            break;
          case "UPVOTE":
            await upvoteInsight(deps.db, op.insightId);
            break;
          case "DOWNVOTE":
            await downvoteInsight(deps.db, op.insightId);
            break;
          case "EDIT":
            await editInsight(
              deps.db,
              deps.sqlite,
              op.insightId,
              op.newContent,
            );
            break;
        }
      }
    }

    // 5. Archive decayed episodes below retention threshold
    await archiveDecayedInsights(deps.db);
  }, CONSOLIDATION_INTERVAL_MS);
}
```

> **Known limitations and planned improvements:**
>
> * **Batch size**: The 4-hour / minimum-3-episode trigger is a practical default. SaMuLe (EMNLP 2025) demonstrated that learning from failure trajectories alone (without paired successes) is essential in low-success environments. The consolidation loop should generate DOWNVOTE/EDIT operations from failure clusters even without corresponding successes.
> * **Noise accumulation**: UMEM (arXiv:2602.10652) showed fixed ADD/UPVOTE/DOWNVOTE/EDIT operations accumulate instance-specific noise over time. When insight pool exceeds \~500 entries, plan a Mem-Optimizer upgrade (small learnable LLM, e.g. Llama-3.2-1B) that jointly optimizes extraction and management via Semantic Neighborhood Modeling and GRPO reward.

***

### 10. Production Patterns

#### Circuit breakers (`opossum` ^8.0.0)

Wrap every external call (RPC, oracles, DEX routers, embedding model) in a circuit breaker. Red Hat-supported, 70K+ weekly npm downloads.

```typescript
import CircuitBreaker from "opossum";

const rpcBreaker = new CircuitBreaker(callRpc, {
  timeout: 5000, // 5s timeout per call
  errorThresholdPercentage: 50,
  resetTimeout: 30000, // 30s before half-open retry
  volumeThreshold: 5, // minimum calls before tripping
});

rpcBreaker.fallback(() => ({ error: "RPC unavailable", fallback: true }));
rpcBreaker.on("open", () => logger.warn("RPC circuit OPEN"));
```

**Portfolio-level breakers** (inspired by SEC circuit breakers):

* Warning: portfolio drawdown >3%
* Halt new positions: drawdown >7%
* Full stop: drawdown >13%

#### ADWIN drift detection

Adaptive Windowing detects distributional changes with mathematical error guarantees. Triggers re-evaluation or DOWNVOTE of insights when market conditions shift.

```typescript
// ~200 lines TypeScript — maintains running mean/variance over a sliding window
class ADWIN {
  private window: number[] = [];
  private sum = 0;
  private sumSq = 0;

  push(value: number): boolean /* driftDetected */ {
    this.window.push(value);
    this.sum += value;
    this.sumSq += value * value;

    // Try all split points; if Welch's t-test rejects H0, drop old half
    for (let i = Math.floor(this.window.length / 2); i > 0; i--) {
      if (this.welchTest(i)) {
        // Drift detected — drop old observations
        const dropped = this.window.splice(0, i);
        this.recomputeStats();
        return true;
      }
    }
    return false;
  }

  private welchTest(splitIdx: number): boolean {
    // Compare mean/variance of [0..splitIdx) vs [splitIdx..end)
    // Return true if statistically significant difference (p < 0.01)
    // ... (full implementation: ~50 lines of running statistics)
    return false; // placeholder
  }

  private recomputeStats() {
    this.sum = this.window.reduce((a, b) => a + b, 0);
    this.sumSq = this.window.reduce((a, b) => a + b * b, 0);
  }
}
```

Use one ADWIN instance per tracked metric (slippage, gas, pool depth, volatility). When `push()` returns `true`, trigger insight re-evaluation for that category.

***

## Part 2: Research Foundations

The cognitive science, retrieval, self-improvement, and production reliability research underpinning the DeFi Brain design. Each section provides the "why" behind Part 1's implementation patterns.

***

### 1. Cognitive Architecture Foundations

#### CoALA Framework

The Cognitive Architectures for Language Agents framework (Sumers et al., 2023, arXiv:2309.02427, TMLR 2024) formalizes LLM agents as having four memory types. The DeFi Brain implements each:

| CoALA Memory Type     | DeFi Brain Implementation                     | Store                             |
| --------------------- | --------------------------------------------- | --------------------------------- |
| **Working memory**    | In-context window + LRU cache                 | `lru-cache` (in-process)          |
| **Episodic memory**   | Per-operation reflections, trade outcomes     | LanceDB (Lance columnar format)   |
| **Semantic memory**   | Distilled insights with confidence scores     | SQLite + sqlite-vec (Drizzle ORM) |
| **Procedural memory** | Composable strategy library, tool definitions | Skill files + LanceDB index       |

This mapping mirrors classical SOAR and ACT-R cognitive architectures. Wray, Kirk & Laird (2025, arXiv:2505.07087) explicitly bridge SOAR design patterns to modern agentic LLM systems, demonstrating that observe-decide-act loops, knowledge compilation, and metacognitive reflection all have direct LLM-agent analogs.

#### MemGPT: Virtual Context Management

MemGPT (Packer et al., 2023, arXiv:2310.08560) operationalizes CoALA with OS-inspired virtual context management: a main context window pages information to/from external archival/recall storage via self-directed function calls. The DeFi Brain adapts this as: main context = system instructions + working context; archival = LanceDB; recall = SQLite; paging = context injection middleware (Part 1 §8).

#### FinMem: Layered Financial Memory

FinMem (Yu et al., arXiv:2311.13743, AAAI 2024) is the closest production system to the DeFi Brain's design: an LLM trading agent with layered memory and character design. Its three memory layers with different decay rates directly inform the DeFi Brain's conditional decay architecture:

* **Shallow layer** (α=0.9): high decay rate — short retention for daily news with immediate market impact
* **Intermediate layer** (α=0.967): medium decay rate — medium retention for company reports
* **Deep layer** (α=0.988): low decay rate — long retention for annual reports / structural insights

The mapping for DeFi: gas observations and daily price signals → shallow; rebalancing patterns → intermediate; protocol vulnerabilities and structural regime insights → deep.

#### Memory Surveys

Zhang et al. (2024, arXiv:2404.13501, ACM TOIS) catalog memory mechanisms across sources, forms, and operations. A-MEM (Xu et al., 2025, arXiv:2502.12110) proposes Zettelkasten-inspired agentic memory with dynamic interconnected knowledge networks. FadeMem (Wei et al., arXiv:2601.18642, Jan 2026) demonstrated 82.1% retention of critical facts using 55% of storage via *adaptive* decay — validating selective forgetting for high-volume low-importance episodic data such as trade logs and gas observations.

> **Note**: Ebbinghaus's forgetting curve was derived from memorization of nonsense syllables — a fundamentally different memory task than structured DeFi knowledge. FadeMem's storage reduction benefit holds for volatile, low-importance data (gas prices, routine trade logs). The model is **inappropriate** for strategy-level insights that may regain relevance during market regime cycles. The DeFi Brain uses importance-weighted conditional decay (Part 1 §7) for strategy insights: high-impact memories decay 5× slower (not immortal), and time-based TTL applies only to volatile low-impact observations.

***

### 2. Retrieval Architecture

#### Matryoshka Representation Learning (MRL)

MRL (Kusupati et al., 2022, arXiv:2205.13147, NeurIPS 2022) trains embeddings where the first *m* dimensions are independently useful, enabling **64-dim fast candidate search followed by full-dim reranking** — up to **14x speedup** at equivalent accuracy. Target upgrade model: `nomic-ai/nomic-embed-text-v1.5` (768-dim, supports 64-768 truncation, ONNX weights, confirmed in Transformers.js):

```javascript
const extractor = await pipeline(
  "feature-extraction",
  "nomic-ai/nomic-embed-text-v1.5",
);
let embeddings = await extractor(texts, { pooling: "mean" });
embeddings = layer_norm(embeddings, [embeddings.dims[1]])
  .slice(null, [0, matryoshka_dim])
  .normalize(2, -1);
```

**Financial domain caveat**: No published benchmarks exist for `nomic-embed-text-v1.5` on financial or DeFi text retrieval. FinMTEB (Tang & Yang, EMNLP 2025) found that general MTEB scores show statistically insignificant correlation with financial domain performance. The current recommendation of Nomic is appropriate for general DeFi text retrieval but may underperform for financial-specific queries.

**Better alternatives for financial text:**

* **Voyage-finance-2** (June 2024): NDCG\@10 of 0.831 across 11 financial datasets — 7% ahead of OpenAI text-embedding-3-large, 12% ahead of Cohere. However, it is API-only with no ONNX weights, making local/TEE use impossible without a proxy.
* **Fine-tuned Nomic on DeFi corpus**: Fine-tuning with \~6,300 synthetic query-document pairs (DeFi protocol docs, governance proposals, vault operation logs) yields \~7% NDCG improvement. A fine-tuned 128-dim Nomic model outperforms the unfine-tuned 768-dim baseline by 6.51% (Phil Schmid's SEC filing experiments). Use MatryoshkaLoss from sentence-transformers; 3-minute training on consumer GPU. This is the recommended path for production — retains ONNX/Node.js compatibility.

#### Anthropic Contextual Retrieval

Anthropic's technique (September 2024) prepends LLM-generated chunk context before embedding — reducing top-20 retrieval failure by **35%** alone, **49%** with hybrid BM25, **67%** with reranking. Cost: \~$1.02/M tokens with prompt caching.

#### HippoRAG

HippoRAG (Gutierrez et al., 2024, arXiv:2405.14831, NeurIPS 2024) mimics hippocampal indexing using a knowledge graph with **Personalized PageRank** for pattern completion — **10-30x cheaper and 6-13x faster** than iterative retrieval, with up to **20% improvement** on multi-hop QA. HippoRAG 2 (Feb 2025, arXiv:2502.14802, ICML 2025) adds deeper passage integration. Requires `graphology` npm (Tier 3).

#### RAPTOR

RAPTOR (Sarthi et al., 2024, arXiv:2401.18059, ICLR 2024) recursively clusters and summarizes chunks via GMMs, building a tree with multiple abstraction levels — **20% absolute accuracy improvement** on QuALITY. For DeFi: leaf = individual trade reflections, cluster = pair-specific patterns, root = strategy-level insights.

#### Self-RAG and CRAG

**Self-RAG** (Asai et al., 2023, arXiv:2310.11511, ICLR 2024) enables the LLM to decide when to retrieve and critique relevance. **CRAG** (Yan et al., 2024, arXiv:2401.15884) triggers fallback when retrieval quality is poor. For DeFi: verify cached insights against live on-chain state; if contradicted, DOWNVOTE and use live data.

#### Other Approaches (Research Context)

* **ColBERT v2**: Cross-encoder quality at retrieval speed, but **no ONNX/Node.js path exists** (Transformers.js Issue #851 open). Workaround: multiple aspect embeddings per episode as separate LanceDB rows.
* **FLARE** (Jiang et al., 2023): Forward-looking active retrieval for low-confidence tokens. Implementable as a prompt pattern.
* **MemoRAG** (Qian et al., 2024): Dual-system with lightweight LLM for global memory. Applicable as prompt orchestration.
* **TSDAE** (Wang et al., 2021): Domain-specific unsupervised embedding pre-training — relevant if DeFi-specific ONNX models become available.

***

### 3. Self-Improvement Patterns

#### ReAct -> Reflexion -> ExpeL Progression

| Dimension          | ReAct              | Reflexion             | ExpeL                         |
| ------------------ | ------------------ | --------------------- | ----------------------------- |
| **Learning scope** | None (single pass) | Intra-task (retries)  | Inter-task (cross-task)       |
| **Memory type**    | None               | Episodic reflections  | Episodic + semantic insights  |
| **Key metric**     | +34% on ALFWorld   | 91% pass\@1 HumanEval | Cross-task knowledge transfer |

**ReAct** (Yao et al., 2023, ICLR 2023) interleaves reasoning with actions — no learning. **Reflexion** (Shinn et al., 2023, NeurIPS 2023) adds verbal self-reflection achieving **97% on decision-making benchmarks**. **ExpeL** (Zhao et al., 2023) distills trajectory pairs into reusable insights. The DeFi Brain uses Reflexion for the inner loop (Part 1 §5) and ExpeL for the outer loop (Part 1 §6).

**ExpeL limitations at scale**: SaMuLe (arXiv:2509.20562, EMNLP 2025) found ExpeL collapses to 0% success rate on TravelPlanner, where task success is rare. Root cause: ExpeL requires successful trajectories as learning signals. For the DeFi Brain, novel market conditions and protocol failures produce failure-heavy periods. Implement multi-level reflection (single-trajectory, intra-task, inter-task) to learn from failures without requiring paired successes.

**MUSE** (arXiv:2510.08002, Oct 2025) achieved 51.78% SOTA on TAC (+20% relative) using three typed memory categories: procedural (step-by-step sequences), strategic (higher-level patterns), tool (tool-use guidance). Hierarchical typing enables retrieval at appropriate abstraction levels — maps directly to DeFi's need to differentiate "how to rebalance" (procedural) from "when to rebalance" (strategic).

**UMEM** (Ye et al., arXiv:2602.10652, Feb 2026): jointly optimizes memory extraction and management via a learnable Mem-Optimizer. Addresses noise accumulation from static ADD/UPVOTE/DOWNVOTE/EDIT prompts. Achieved 10.67% improvement over baselines with monotonic growth vs. rapid degradation in naive approaches. The DeFi Brain should plan this as a v2 upgrade when the insight pool matures.

**ReflAct** (Kim et al., arXiv:2505.15182, May 2025): replaces ReAct's action-planning loop with goal-state reflection, achieving 27.7% average improvement across ALFWorld, WebShop, ScienceWorld. Structured state-goal reflection with explicit quantitative anchors prevents error compounding — directly applicable to vault rebalancing where goal (target allocation) and constraints (max drawdown) are explicitly quantitative.

#### Voyager: Skill Libraries

Voyager (Wang et al., 2023, TMLR 2024) demonstrates lifelong learning via an ever-growing skill library — **15.3x faster** capability unlock. Maps to a growing library of composable DeFi strategies indexed in LanceDB by situation similarity.

#### LATS and ETO

**LATS** (Zhou et al., 2023, ICML 2024) adapts Monte Carlo Tree Search to language agents — **92.7% pass\@1 on HumanEval**. Enables exploring multiple transaction sequences before committing. **ETO** (Song et al., 2024, ACL 2024) learns from exploration failures via contrastive trajectory optimization — **>5% across benchmarks**. Directly applicable to learning from failed DeFi transactions.

#### Other Patterns (Research Context)

* **STaR/Quiet-STaR** (Zelikman et al., 2022/2024): Bootstrapped reasoning via iterative rationale generation.
* **Thought Cloning** (Hu & Clune, 2023, NeurIPS 2023 Spotlight): Clones thoughts and actions, enabling **Precrime Intervention** — detecting unsafe plans before execution.

***

### 4. DeFi-Specific ML

#### LVR-Aware Fee Optimization

LVR (Milionis et al., 2022, arXiv:2208.06046, JPE Microeconomics 2024) quantifies LP losses: instantaneous LVR rate = **(sigma^2/8) x pool\_value**. A pool needs \~10% daily turnover at 30bp fees to offset LVR at 5% volatility. The Arrakis Pro Hook (2025) is the first whitelisted dynamic fee hook using real-time volatility.

#### Regime-Switching Models

Ardia et al. (2019) fit 1,000+ GARCH models to crypto, finding **Markov-Switching GARCH with asymmetries** outperforms standard GARCH for VaR/ES. A 2024 Digital Finance paper combines HMM with RL using three volatility-defined regimes. The DeFi Brain's `classify_regime` implements a lightweight HMM (3-5 states) persisted in SQLite.

#### CVaR, CDaR, and IL Hedging

* **CVaR-constrained DRL** (Economic Modelling, 2022) outperforms traditional techniques on crypto portfolios
* **CDaR** (Chekhlov, Uryasev & Zabarankin, 2005) controls path-dependent drawdowns via LP formulation
* **IL hedging** (Lipton et al., 2024, arXiv:2407.05146): Static replication (options) and dynamic delta-hedging for V2/V3 positions
* **PnL attribution**: LP returns = Fee Revenue - LVR - Gas Costs - Opportunity Cost (BIS Working Paper No. 1227)

#### On-Chain Feature Engineering and Deep RL (Research Context)

TFT research identifies predictive on-chain features: TVL flows, exchange net flow, HODL waves, SOPR, active addresses. Deep RL for market making (Spooner et al., 2018; Ganesh et al., 2019; SAC/DDPG portfolio, 2025) informs heuristics and reward signals — the agent doesn't train RL models, but uses this research to shape how it evaluates strategy parameters via Bayesian optimization.

***

### 5. Causal and Temporal Reasoning

#### Granger Causality

Applied to DeFi: a 2022 MDPI study found **TVL does not Granger-cause future valuations**, but bidirectional relationship exists between valuations and GMV. Dixon et al. (2019) demonstrated extreme chainlet activity **Granger-causes** intraday price volatility.

#### Transfer Entropy and Causal Discovery

Chalkiadakis et al. (2021) show transfer entropy detects significant nonlinear causality between social media sentiment and crypto returns. **CD-NOTS** (Sadeghi et al., 2023) handles nonstationary financial time series. **GPT-4 DAG pruning** (Sokolov et al., 2024) generates causal DAGs then prunes with do-calculus.

#### Temporal Knowledge Graphs (TKGs)

TKGs enable time-aware retrieval: **MemoTime** (Tan et al., 2025) achieves **up to 24% improvement** via "Tree of Time" hierarchical decomposition. **GenTKG** (Liao et al., 2024, NAACL 2024) adds retrieval-augmented TKG forecasting. For DeFi: `(ETH_price, dropped_10%, 2026-02-15) -> caused -> (WETH/USDC_pool, liquidity_withdrawn, 2026-02-15)`.

#### Event-Driven Structured Memory and Continual Learning

Zhou et al. (2021) demonstrate (Actor, Action, Object) tuples with causal links outperform sentiment-based approaches. Shi et al. (2024, ACM Computing Surveys 2025) survey LLM continual learning — the DeFi Brain implements this at the knowledge structure level: experience replay, self-synthesized rehearsal (Huang et al., 2024), and importance-weighted TTL pruning as forgetting mitigation (replacing Ebbinghaus time-decay, which is inappropriate for regime-cycling DeFi knowledge).

***

### 6. Production Reliability

#### Circuit Breakers and ADWIN

**`opossum`** provides production-ready circuit breakers (see Part 1 §10 for setup). **ADWIN** detects distributional shifts (\~200 lines TypeScript, see Part 1 §10 for implementation sketch). Both are Tier 1 enhancements.

#### Conformal Prediction

Distribution-free coverage guarantees for position sizing. Fantazzini (2024) applied 4 ACI algorithms to **4,000 crypto-assets** — FACI and SF-OGD provide precise VaR estimates where GARCH fails. Kato et al. (2024) applied CP to portfolio selection. **ConU** (Wang et al., 2024, EMNLP 2024) applies CP to black-box LLMs. **DeLLMa** (Liu et al., 2024, ICLR 2025) validated on finance with **40% accuracy improvement**. All Tier 3.

#### Runtime Safety and Multi-Agent Debate

**AgentSpec** (Poskitt et al., 2025, ICSE 2026) introduces a DSL for runtime enforcement — validates the DeFi Brain's code-enforced invariants (PolicyCage) over prompt-based safety. **Multi-agent debate** (Du et al., 2023, ICML 2024) uses 3+ LLM instances debating to reduce hallucinations — deploy specialized agents (risk analyst, opportunity seeker, regime detector) for high-value transactions. Tier 2, TypeScript-only.

***

### 7. Implementation Tiers

All enhancements are TypeScript-only with zero external language dependencies.

#### Tier 1: Quick Wins (Days)

| Enhancement                                       | Effort | Impact                         |
| ------------------------------------------------- | ------ | ------------------------------ |
| Swap to nomic-embed-text-v1.5 (MRL)               | 1 day  | 14x retrieval speedup          |
| Enable LanceDB hybrid BM25+vector search          | 1 day  | Better keyword+semantic recall |
| Wrap external calls in `opossum` circuit breakers | 1 day  | Production reliability         |
| Implement ADWIN drift detection                   | 2 days | Detect stale insights          |

#### Tier 2: Moderate Investment (Weeks)

| Enhancement                                   | Effort  | Impact                          |
| --------------------------------------------- | ------- | ------------------------------- |
| Anthropic contextual retrieval pre-processing | 1 week  | 49% retrieval failure reduction |
| Self-RAG/CRAG retrieval evaluation            | 1 week  | Eliminate stale memory usage    |
| Voyager-inspired skill library                | 2 weeks | 15.3x faster capability unlock  |
| Multi-agent debate for high-value txns        | 1 week  | Reduce hallucination risk       |

#### Tier 3: Deep Integration (Months)

| Enhancement                              | Effort   | Impact                             |
| ---------------------------------------- | -------- | ---------------------------------- |
| HippoRAG knowledge graph (`graphology`)  | 2 months | 10-30x cheaper multi-hop retrieval |
| Temporal knowledge graph (MemoTime)      | 2 months | Time-aware causal reasoning        |
| Conformal prediction for position sizing | 1 month  | Distribution-free risk guarantees  |
| Event-driven structured memory           | 1 month  | Better causal retrieval            |

***

### Dashboard Exposure

The memory system is surfaced to operators via the Portal Agent Management Dashboard ([prd/website/portal/02-agent-dashboard.md](/docs/website/website/portal/02-agent-dashboard.md)). This section specifies how the dashboard interacts with memory internals.

#### Queryable Data

The dashboard exposes two memory stores for operator inspection:

| Store                   | Dashboard Tab | Query Tool                     | What's Visible                                                              |
| ----------------------- | ------------- | ------------------------------ | --------------------------------------------------------------------------- |
| LanceDB episodic memory | Episodes      | `search_memory`                | Reflection text, tool involved, outcome, chain, timestamp, importance score |
| SQLite semantic memory  | Insights      | `retrieve_insights` (filtered) | Content, category, confidence, decay status, access count, last accessed    |

The dashboard also shows aggregate memory statistics: total episode count, total insight count, last ExpeL consolidation timestamp, and retention metrics (episodes retained vs. decayed).

#### Operator Feedback Integration

Operator directives submitted via the dashboard's feedback interface are stored as semantic insights with special properties:

```
category: operator_directive
confidence: 1.0          (never subject to time decay)
metadata: {
  feedbackType: "strategy_preference" | "decision_correction" | "market_context" | "goal_adjustment",
  priority: "low" | "medium" | "high",
  expiresAt: ISO 8601 | null,
  submittedAt: ISO 8601
}
```

**Context injection**: During the pre-tool-call middleware, the agent retrieves active operator directives and injects them into the context window. High-priority directives are injected first. Operator directives take precedence over learned insights when they conflict — they represent explicit operator intent.

**Expiry**: Directives with a non-null `expiresAt` are automatically archived when the expiry date passes. Archived directives remain queryable but are excluded from context injection.

#### Feedback Key Requirement

Reading memory data (episodes, insights, statistics) requires a **Read** key or higher. Modifying memory data (downvoting insights, archiving, adjusting confidence, submitting directives) requires a **Feedback** key or higher. See [prd/website/portal/03-api-keys.md](/docs/website/website/portal/03-api-keys.md) for the key model.

| Action            | Required Key Tier |
| ----------------- | ----------------- |
| Browse episodes   | Read              |
| Browse insights   | Read              |
| View memory stats | Read              |
| Downvote insight  | Feedback          |
| Archive insight   | Feedback          |
| Adjust confidence | Feedback          |
| Submit directive  | Feedback          |

***

### 9.5 Cybernetic Mapping

The DeFi Brain memory subsystem maps directly to classical cybernetic concepts. This section makes those mappings explicit. See [15-cybernetic-feedback.md](/docs/agents/agents/15-cybernetic-feedback.md) for full theoretical grounding with citations.

#### Memory Components as Cybernetic Elements

| Memory Component                  | Cybernetic Concept                 | Theorist                      | Mapping                                                                                                                                                                                                                                                   |
| --------------------------------- | ---------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 12 insight categories             | **Requisite variety**              | Ashby (1956)                  | The 12 categories (`slippage`, `gas_timing`, `route_selection`, etc.) provide the variety needed to regulate a complex DeFi domain. A system with only "general" insights lacks the regulatory capacity to match market complexity.                       |
| Episodic → semantic consolidation | **Single → double-loop learning**  | Argyris & Schon (1978)        | Raw episodes (single experiences) are distilled into semantic insights (general principles). This is the transition from "what happened" (single-loop) to "what does this mean" (double-loop).                                                            |
| ExpeL ADD operation               | **Positive feedback**              | Wiener (1948)                 | New patterns detected → amplified into explicit insights. Introduces new regulatory capacity. Bounded by minimum cluster size (3 episodes).                                                                                                               |
| ExpeL UPVOTE operation            | **Reinforcement**                  | Wiener (1948)                 | Validating evidence → confidence increases (+0.1). Strengthens existing regulatory rules.                                                                                                                                                                 |
| ExpeL DOWNVOTE operation          | **Negative feedback (dominant)**   | Wiener (1948)                 | Contradicting evidence → confidence decreases (-0.15). Asymmetric to ensure negative feedback dominates — bad insights decay faster than good ones accumulate. This is the core stability mechanism.                                                      |
| ExpeL EDIT operation              | **Adaptation**                     | Ashby (1956)                  | Insight refined without confidence reset. The regulatory rule adapts to better match the system being regulated, per the Good Regulator Theorem (Conant & Ashby, 1970).                                                                                   |
| Asymmetric confidence updates     | **Negative feedback bias**         | Wiener (1948)                 | DOWNVOTE (-0.15) > UPVOTE (+0.1). Dampening. Prevents runaway confidence and overfit heuristics. Follows FINSABER's cautionary findings.                                                                                                                  |
| Importance-weighted decay         | **Allostasis**                     | Sterling (2012)               | Predictive regulation — high-impact memories are retained proactively (5x slower decay) because the system anticipates they may be needed during future regime recurrences. Not reactive homeostasis but predictive allostasis.                           |
| `withMemory` middleware           | **Beer's S2 (coordination)**       | Beer (1972)                   | Coordinates memory retrieval across tool calls. Ensures each tool execution is informed by relevant past experience without tools needing to manage memory themselves.                                                                                    |
| ADWIN drift detection             | **Ashby's ultrastability trigger** | Ashby (1956)                  | When distributional shift is detected, the inner loop's adjustments are no longer sufficient. ADWIN triggers escalation: DOWNVOTE stale insights, re-evaluate in the new regime. The boundary between "keep adjusting parameters" and "change the rules." |
| Circuit breakers (`opossum`)      | **Homeostatic limits**             | Cannon (1932) / Wiener (1948) | Hard boundaries that prevent the system from entering dangerous states. Portfolio drawdown thresholds (3%/7%/13%) are homeostatic limits — the system shuts down before reaching non-viable states.                                                       |
| Regime classification             | **Beer's S4 (intelligence)**       | Beer (1972)                   | Scans the external environment for regime changes. When a new regime is detected, the system retrieves historically successful parameters — Lo's Adaptive Markets Hypothesis (2004) in practice.                                                          |

#### JSONL Transcript (Daemon Session History)

GottsLoop adds a **JSONL transcript** (`transcript.jsonl`) as a complementary persistence layer — append-only session history that captures both heartbeat ticks and operator interactions. This enables crash recovery and provides an audit trail alongside LanceDB (episodic) and SQLite (semantic). The transcript is the daemon's equivalent of working memory — what happened in this session — while LanceDB/SQLite store cross-session knowledge. See [16-gottsloop.md](/docs/agents/agents/16-gottsloop.md) §4.9.

#### ACE Delta-Based Updates

The ACE framework (Zhang et al., arXiv:2510.04618, ICLR 2026) provides an alternative consolidation mechanism that complements ExpeL. While ExpeL uses ADD/UPVOTE/DOWNVOTE/EDIT operations on insights, ACE introduces a **Generator → Reflector → Curator** cycle that produces *delta entries* rather than monolithic rewrites:

| ACE Role      | DeFi Brain Mapping                 | Function                                                        |
| ------------- | ---------------------------------- | --------------------------------------------------------------- |
| **Generator** | Heartbeat tick execution           | Produces experiences (episodes) from strategy execution         |
| **Reflector** | Post-tick reflection (double-loop) | Evaluates outcomes, produces delta entries with helpful/harmful |
| **Curator**   | Consolidation loop (meta-loop)     | Integrates deltas: append new, update existing, deduplicate     |

Delta-based updates prevent "context collapse" — the failure mode where monolithic insight rewrites lose nuance accumulated over many episodes. Each heuristic carries metadata: `helpful_count`, `harmful_count`, `created_tick`, `last_triggered_tick`, enabling fine-grained confidence tracking. GottsLoop ([16-gottsloop.md](/docs/agents/agents/16-gottsloop.md)) implements ACE's Curator as `curator.ts`.

#### Dabney et al. Distributional Reward Coding

The asymmetric confidence updates used throughout the memory system (+0.1 upvote / -0.15 downvote) have a neuroscience foundation in **distributional reward prediction** (Dabney et al., "A distributional code for value in dopamine-based reinforcement learning," *Nature* 577, January 2020). Dabney et al. discovered that dopamine neurons encode a *distribution* of value expectations, not a single point estimate — with individual neurons tuned to different quantiles of the reward distribution, creating naturally asymmetric optimistic and pessimistic channels.

The DeFi Brain's confidence asymmetry mirrors this: the -0.15 downvote (pessimistic channel) dominates the +0.1 upvote (optimistic channel), ensuring that negative evidence has outsized influence. This creates a system that is structurally cautious — it takes more positive evidence to build confidence than negative evidence to erode it. A distributional extension could track three confidence channels per insight (optimistic/median/pessimistic) for richer uncertainty representation.

#### Consolidation Loop as Cybernetic Feedback

The ExpeL consolidation loop (Part 1 §9) is a multi-level cybernetic feedback system:

```
Level 1 (Wiener feedback):     Episode → reflection → stored in LanceDB
Level 2 (Argyris single-loop): Episodes clustered → ExpeL operations → insight updates
Level 3 (Argyris double-loop): Insights inform → LLM reasoning context changes → different decisions
Level 4 (von Foerster meta):   GottsLoop curator → restructures playbook → changes how learning happens
```

Levels 1-3 exist in the current memory architecture. Level 4 is added by GottsLoop ([16-gottsloop.md](/docs/agents/agents/16-gottsloop.md)).

#### Design Rationale Through Cybernetic Lens

**Why asymmetric confidence?** Wiener's negative feedback: stability requires that dampening forces exceed amplifying forces. A system where good news (+0.1) and bad news (-0.1) have equal weight is neutrally stable — one sustained positive streak can push confidence to 1.0 and lock in a potentially wrong heuristic. The -0.15 asymmetry ensures the system self-corrects.

**Why 12 categories, not 3 or 50?** Ashby's requisite variety, practically bounded. Fewer categories lack regulatory capacity (can't distinguish slippage patterns from gas timing patterns). More categories fragment the insight pool below the minimum viable cluster size. 12 matches the empirically distinct DeFi knowledge domains.

**Why importance-weighted decay instead of time-decay?** Sterling's allostasis over Cannon's homeostasis. DeFi knowledge is regime-cycling — patterns from 2022's bear market become relevant again in the next bear market. Time-decay (Ebbinghaus) was derived from human memorization of nonsense syllables — semantically structured, regime-cycling knowledge requires predictive retention, not chronological forgetting.

***

### Cross-References

* **Tool specifications**: [07-tools-advanced.md](/docs/gotts-safe-mcp-server/mcp-server/07-tools-advanced.md) Memory and Knowledge Tools section
* **Dashboard specification**: [prd/website/portal/02-agent-dashboard.md](/docs/website/website/portal/02-agent-dashboard.md) Episode & Insight Browser, Agent Feedback Interface
* **API key model**: [prd/website/portal/03-api-keys.md](/docs/website/website/portal/03-api-keys.md) Three-tier key model
* **Research citations**: [research-citations.md](/docs/gotts-vaults/vault/research-citations.md) Memory Architecture, RAG Enhancements, Self-Improvement, DeFi ML, Causal Reasoning, and Production Reliability sections
* **Glossary**: [glossary.md](/docs/prd-shared/glossary.md) — CoALA, MemGPT, HippoRAG, RAPTOR, Self-RAG, CRAG, MRL, Voyager, LATS, ETO, Conformal Prediction, ADWIN, Contextual Retrieval, CDaR, TKG, Multi-Agent Debate
* **Dependencies**: [12-dependencies.md](/docs/gotts-vaults/vault/12-dependencies.md) — `@huggingface/transformers`, `opossum`, `graphology` (Tier 3)
* **Architecture**: [04-architecture.md](/docs/gotts-vaults/vault/04-architecture.md) — `memory/` directory layout
* **Cybernetic foundations**: [15-cybernetic-feedback.md](/docs/agents/agents/15-cybernetic-feedback.md) — theoretical grounding for memory as cybernetic regulation, Dabney distributional reward coding
* **GottsLoop**: [16-gottsloop.md](/docs/agents/agents/16-gottsloop.md) — daemon architecture (Lane Queue, JSONL transcript), double-loop learning that extends memory to strategic reasoning, ACE Generator→Reflector→Curator cycle
* **Autonomous strategies**: [14-autonomous-strategies.md](/docs/agents/agents/14-autonomous-strategies.md) — heartbeat runner, strategy bank, STRATEGY.md format