> ## Documentation Index
> Fetch the complete documentation index at: https://srk-e37e8aa3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Memory

> Three layers of memory. The brain gets quieter every run.

# Memory

Plexa stacks three layers between the body and the LLM. Each one answers more situations than the next, so the brain gets called less and less.

```
PatternStore        per body         exact / near-exact match     0.1 ms
AdaptiveMemory      per body         similarity-scored match      1 to 5 ms
VerticalMemory      per Space        cross-session world states   5 ms (sqlite)
LLM brain           shared           novel situations only        500 ms+
```

## PatternStore

Per body. Caches exact and very-similar (entity, decision) pairs. Lives in `scp-protocol`.

```javascript theme={null}
const { PatternStore } = require("scp-protocol")

const store = new PatternStore({
  featureExtractor: (entity) => ({ kind: entity.kind }),
  failureThreshold: 3,
})
```

Full reference: see [SCP memory layers](/scp/pattern-store).

## AdaptiveMemory

Per body. Generalizes to "this looks like one we have seen before" using weighted euclidean distance and top-k confidence blending.

```javascript theme={null}
const { AdaptiveMemory } = require("scp-protocol")

const mem = new AdaptiveMemory({
  threshold: 0.8,
  k: 5,
  storage: "sqlite",
  storageKey: "scp_adaptive.db",
})
```

Wired into a body via `new SCPBody({ patternStore, adaptiveMemory })`.

## VerticalMemory

Per Space. Cross-session memory of brain decisions for a given world state. This is what lets Plexa skip the LLM on repeated tasks.

```javascript theme={null}
const { VerticalMemory } = require("@srk0102/plexa")

const mem = new VerticalMemory({
  spaceName: "robot",
  dbPath: "./plexa-memory.db",
  hitThreshold: 0.85,
})

const space = new Space("robot", { verticalMemory: mem })
```

On each brain tick, Plexa calls `mem.search(worldState)` first. If the top match scores above `hitThreshold`, Plexa uses the remembered decision and skips the LLM. The `memory_hit` event fires.

```javascript theme={null}
space.on("memory_hit", (e) => {
  console.log("served from memory, conf=", e.confidence)
})
```

Otherwise the brain runs and the response is written back via `mem.store`.

Stats:

```javascript theme={null}
space.getStats().memoryHits
space.getStats().memoryMisses
space.getStats().memoryHitRate
space.getStats().verticalMemory   // { total, sessionsCount, hitRate, byBody, ... }
```

## How they work together

```
brain decision arrives
  -> body.learnFromBrain(entity, decision)
     -> patternStore.learn       (exact replay)
     -> adaptiveMemory.store     (generalization)
  -> Space.verticalMemory.store  (cross-session, world-state keyed)
```

Three layers of write-through. Three layers of read-through on the next tick. The further you get into a session, the rarer the LLM call.

## Cost reduction

Sample run on a Plexa stub workload, 100 brain decisions during ramp-up:

| Session | LLM calls | Cache + memory hits | Brain cost (Nova Micro) |
| ------- | --------: | ------------------: | ----------------------: |
| 1       |        80 |                  20 |                \$0.0042 |
| 2       |        30 |                  70 |                \$0.0016 |
| 3       |         8 |                  92 |                \$0.0004 |
| 4       |         1 |                  99 |                \$0.0001 |

Numbers vary by task. The shape is the same: brain decisions get cached locally, repeated situations skip the LLM, latency stops bottlenecking on the brain. Novel situations always wake the brain. Cost is proportional to novelty.

## Persistence

`AdaptiveMemory` and `VerticalMemory` use `better-sqlite3`. Plexa lists it as a `devDependency`, not a runtime one, so production users opt in:

```bash theme={null}
npm install better-sqlite3
```

If `better-sqlite3` is not installed, both stores still work in memory; persistence calls return `0` and the warning shows up at startup.

## Auto-save on shutdown

```javascript theme={null}
space.installShutdownHandlers()
```

On `SIGINT` or `SIGTERM`, Plexa calls `space.stop()`, which saves the vertical memory and every body's pattern store and adaptive memory.