# @coda/memory

Cross-session memory for AI agents. Learns user preferences, tool effectiveness, and domain patterns through deterministic observation consolidation with pluggable confidence decay.

## Installation

```jsonc
{ "dependencies": { "@coda/memory": "workspace:*" } }
```

## Overview

Raw **observations** (tool outcomes, entity accesses, query patterns) are appended during a session, then **consolidated** into durable **facts** at the start of the next session. Each fact carries a confidence score that grows with reinforcement and decays over time via a pluggable **DecayStrategy**. Active facts are formatted into a compact system prompt section and used to derive tool affinity scores for search ranking.

### Exports

| Export                | Kind      | Description                                                                                                     |
| --------------------- | --------- | --------------------------------------------------------------------------------------------------------------- |
| `Observation`         | type      | Raw event recorded during a session                                                                             |
| `ObservationType`     | type      | `"tool_success"` \| `"tool_failure"` \| `"entity_access"` \| `"query_pattern"`                                  |
| `Fact`                | type      | Consolidated belief with confidence and reinforcement tracking                                                  |
| `FactCategory`        | type      | `"tool_affinity"` \| `"tool_avoidance"` \| `"entity_frequency"` \| `"domain_preference"` \| `"failure_pattern"` |
| `ObservationLog`      | interface | Append-only observation storage                                                                                 |
| `FactRepository`      | interface | CRUD for consolidated facts                                                                                     |
| `NullObservationLog`  | class     | No-op observation log (graceful degradation)                                                                    |
| `NullFactRepository`  | class     | No-op fact repository (graceful degradation)                                                                    |
| `DecayStrategy`       | interface | Pluggable confidence decay algorithm                                                                            |
| `ExponentialDecay`    | class     | Simple time-based exponential decay (half-life ~13.5 days)                                                      |
| `AdaptiveDecay`       | class     | SM-2 inspired adaptive decay with per-fact ease factors                                                         |
| `consolidate`         | function  | Core pipeline: observations to facts with decay                                                                 |
| `ConsolidateOptions`  | type      | Configuration for `consolidate()`                                                                               |
| `RedisObservationLog` | class     | Redis sorted-set backed observation log                                                                         |
| `RedisFactRepository` | class     | Redis hash backed fact repository                                                                               |

Checkpoint storage uses `AsyncMap<string, number>` from `@coda/collections` — no dedicated interface needed.

## Quick Start

```ts
import {
  RedisObservationLog,
  RedisFactRepository,
  ExponentialDecay,
  consolidate,
} from "@coda/memory";
import { AsyncMap } from "@coda/collections";

const obs = new RedisObservationLog(sortedStore, "coda:memory:obs:");
const facts = new RedisFactRepository(hashStore, "coda:memory:facts:");
const checkpoint = new AsyncMap<string, number>();

// At session start: consolidate new observations into facts
const activeFacts = await consolidate({
  identityId: "user-123",
  observationLog: obs,
  factRepository: facts,
  checkpoint,
  decay: new ExponentialDecay(),
});
```

## Documentation

- [Architecture](docs/architecture.md) -- data model, pipeline, decay strategies, storage