Pattern store and adaptive memory

How brain decisions become local muscle memory.

Pattern store and adaptive memory

Two cache layers sit between the body and the LLM. The pattern store handles exact and very-similar situations. Adaptive memory handles “this looks like one we have seen before” situations.

PatternStore

A feature-keyed cache. You give it a function that turns an entity into a small object of strings, numbers, and booleans.

const { PatternStore } = require("scp-protocol")

const store = new PatternStore({
  featureExtractor: (entity) => ({
    kind: entity.kind,
    distance_bucket: entity.distance < 5 ? "near" : "far",
  }),
})

Exact match

lookup first hashes the feature vector and looks for that exact hash.

store.learn({ kind: "drone", distance: 3 }, "engage")
store.lookup({ kind: "drone", distance: 4 })
// { decision: "engage", confidence: 0.05, source: "exact" }

The hash is order-independent. Same features, same hash.

Similarity match

If the exact hash misses, lookup walks every other pattern and scores numeric distance plus string equality.

store.lookup({ kind: "drone", distance: 50 })
// returns the closest pattern only if similarity > 0.8 AND its confidence > threshold

The default similarity threshold is 0.8. Patterns below the confidence threshold are skipped.

Confidence

Confidence is a simple count: how many times the same decision has been seen for this exact feature vector. It saturates at 20.

for (let i = 0; i < 10; i++) store.learn({ kind: "ally" }, "wave")
store.lookup({ kind: "ally" })
// confidence: 0.5  (10 of 20)

Confidence below confidenceThreshold (default 0.6) is treated as “not yet trusted” and forces a brain call.

Exploration rate

Even confident hits get re-checked every now and then so the cache does not drift.

new PatternStore({ explorationRate: 0.1 })   // 10% of hits return null

explorationRate: 0 makes the cache deterministic. Useful in tests.

Success rate monitoring

After every cached decision, report what happened.

const hit = store.lookup(entity)
if (hit) {
  await execute(hit.decision)
  store.report(entity, observed_success)   // true or false
}

The store tracks consecutive failures per pattern. After failureThreshold (default 3) the entry is purged and the store emits pattern_invalidated.

store.on("pattern_invalidated", (info) => {
  console.log("dropped pattern", info.features)
})

store.stats() returns hit rate, average success rate, low-confidence count, and totals.

AdaptiveMemory

Adaptive memory is a similarity-scored decision store that generalizes from past LLM decisions when the pattern store cannot.

const { AdaptiveMemory } = require("scp-protocol")

const mem = new AdaptiveMemory({
  threshold: 0.8,           // minimum similarity to count as a hit
  k: 5,                     // top-k neighbors used for confidence blending
  maxHistory: 500,
  weights: { kind: 5, distance: 1 },   // optional per-feature weights
})

mem.store({ kind: "enemy", distance: 4 }, "halt")
mem.lookup({ kind: "enemy", distance: 4.2 })
// { decision: "halt", confidence: 0.78 }

Scoring

Distance is weighted euclidean over normalized feature space. The final confidence is similarity * stored confidence * fraction of top-k that agree on the decision. Disagreement among neighbors dilutes confidence.

Outcome reporting

Same shape as PatternStore:

mem.report(features, success)

Success bumps the entry’s confidence. Failure decays it. After failureThreshold consecutive failures the entry is purged.

Persistence

const mem = new AdaptiveMemory({ storage: "sqlite", storageKey: "scp_adaptive.db" })
mem.save()    // writes the in-memory entries to SQLite
mem.load()    // hydrates from disk on startup

better-sqlite3 is an optional peer dep. If it is not installed, persistence calls return 0 and the store stays in memory.

Wiring both layers into a body

SCPBody.decideLocally consults the pattern store first, then the adaptive memory.

const body = new MyBody({
  patternStore:   new PatternStore({ featureExtractor: f }),
  adaptiveMemory: new AdaptiveMemory({ threshold: 0.8 }),
})

const local = body.decideLocally(entity)
if (local) {
  execute(local.decision)
} else {
  const fromBrain = await brain.call(entity)
  body.learnFromBrain(entity, fromBrain)   // writes to both layers
  execute(fromBrain)
}

learnFromBrain is the only call that needs to know about both stores. The decision flow takes care of the rest.