Remembered, not assumed.

L1 is the only memory tier that reaches the prompt as an index. L2 and L3 stay invisible to the model until something promotes them or recall pulls them, which is what keeps the index a fixed size rather than a function of how long you have worked in a directory.

Nothing here is required for the agent loop to run — memory is an additive layer you construct yourself. It is off by default: the runtime does not inject anything until you pass a memory option. The tiers above are one implementation of the framework’s NahMemory interface; swap in a vector DB or Mastra and the runtime calls the same hooks without changing.

Naive memory only catches phrasings like 'always use kebab-case' and silently drops everything else. These rules exist because that made memory look broken: a stated fact simply never reached the tiers.

A newly taught memory lands in L1 immediately. Waiting for the arbiter to promote it added a turn of latency, so a fact you taught on one turn was still missing from the next prompt.

The engine owns the tiers, the budget, the ranking and the merge rules. Everything model-shaped is wiring, and the CLI supplies four pieces. Build your own and the question filter becomes yours too — the engine has no opinion about questions.

Always injecting every memory body is expensive and injects distractors by construction. Instead each turn gets a one-line index of the hot cache, and a full body is spent only where a deterministic signal earns it.

The trigger is the same idea Aider uses for its repo map: pull identifiers out of your message — URLs, hostnames, paths, SCREAMING_SNAKE, alphanumeric codes, camelCase, long kebab-case, hex-ish codes — and keep only those absent from the visible transcript. If you name something concrete the model cannot already see, and a memory mentions it, that memory's body is included. No model decision is involved, and hostnames are in the set because a host like internal-hbr-2291.example is exactly the value a memory holds and a dotted-name pattern used to miss.

## Cognitive Memory State
### Memory index — established earlier in this project
One line per remembered item. Use `recall` to pull a full item, then treat it as true.
- staging build ID (deployment)
- file naming: kebab-case (naming)
- internal staging host is internal-hbr-2291.example (infra)

maxTotalTokens caps everything injected in one prompt, index and bodies together, and when the cap bites the report is flagged as truncated instead of quietly losing the tail.

Two things move an entry out of the index, and neither deletes it. An L1 item the turn never mentions is demoted to L2 once the cache holds more than five, and if L1 outgrows maxL1Tokens the least recently used are demoted the same way. A demoted memory still answers recall and can be promoted back.

Pre-staging is a best-effort optimisation: a model may not read the index, and a question sharing no words with a memory will not have it staged. The recall tool lets the agent ask directly. Ranking runs in-process, scoring content-word overlap normalised by the shorter side so the score is comparable across memories of different lengths, and the same scoring promotes to L1 — so recall quality does not depend on model quality.

recall { query: 'staging build id', limit: 6 }

// Remembered (1 match):
// - The staging build ID is ZQ7X4M2K. (deployment) [L1, relevance 0.75]

Results that are the same fact restated collapse to the best-scoring one, so a paraphrase cannot take two slots in a single answer. search defaults to 8; the tool asks for 6 and caps the request at 20. When nothing matches it says so, and tells the model to say it was not told rather than guessing. It is read-only, so it is not approval-gated, and the CLI registers it automatically alongside the coding tools.

There is no published benchmark for pre-inject versus on-demand retrieval for coding-agent project memory, so the only way to tune the tradeoff is to watch it. Every injection is recorded with its reason, its tier and its token cost, for the last 20 turns.

/memory

Cognitive Memory Cache State
  Turns processed: 7
  Active tensions: 0
  L1 Hot cache items: 9
  L2 Warm store items: 2
  L3 Cold archive items: 0

Prompt injection log (what memory added, and why)
  7 turn(s) · avg 58 tokens · max 83
  index=25
  turn 7: 58 tokens
    index [index/L1] staging build ID (deployment)
    body  [trigger/L1] internal staging host is internal-hbr-2291.example

Use it to decide whether the budget is too tight, whether the trigger is firing when it should, and whether an index line is enough or the model keeps reaching for recall. The cost is ceil(chars / 4) over the gist, the tags and any body — cheap enough to compute on the critical path and good enough for relative tuning, but it is an estimate rather than a provider token count.

The arbiter runs at the top of postTurnAsync, over warm candidates left by earlier turns. Anything learned in the current turn has already gone to L1, so a fact you teach is indexed from the very next prompt and is first judged for promotion on the turn after that.

With no arbiter configured, promotion is deterministic: warm candidates are scored against the current turn by content-word overlap and the best three above the floor are promoted. Scoring used to compare a single domain tag against the turn text with a substring match, which almost never fired — a memory tagged naming-conventions cannot match a question that says 'naming'. Promotion was effectively random.

Supply arbiter to decide tiers with a model instead, or take createModelArbiter, which is exported from the package root and lives in its own entry point so a consumer who only wants the deterministic core does not have to install a model SDK. An arbiter receives the turn text, the assistant reply, the L0 prompt, the L1 summaries and the L2 candidates, and returns a structured ArbiterEvaluationResult.

import { CognitiveMemory, createModelArbiter } from 'not-another-harness';

const memory = new CognitiveMemory({
  extract: myExtractor,       // omit to use only the built-in patterns
  reconcile: myReconciler,    // omit to collapse exact matches only
  arbiter: createModelArbiter({ model: arbiterModel }),
  maxTotalTokens: 2000,
  onPersist: (snapshot) => db.save(snapshot),
});

The self-model tracks per-domain reliability as a moving average, plus known failure patterns and recommended strategies. A domain in the active list below 75% reliability is rendered into L0 as a guardrail on every prompt, so weak areas get explicit attention instead of confident guesses.

Nothing populates it by itself. A guardrail needs the domain in activeDomains — from initialSelfModel, or by passing detectedDomains to postTurnAsync — and at least one recorded outcome. recordDomainOutcome is the only writer, and the CLI never calls it, so a fresh install shows an empty self-model and injects no guardrails until you wire it yourself.

Active tensions are pinned into every prompt block until resolved, each paired with an actionable question so the agent asks rather than guesses. This is the one part of L0 the CLI fills on its own, because the turn extractor may report a contradiction it saw. addTension and resolveTension drive it from outside; /tensions resolve <id> closes one in the CLI.

The CLI stores memory per working directory at ~/.nah/memory/<cwd-hash>.sqlite — twelve hex characters of a SHA-1 over the resolved directory path, so two projects never share a store and a path with spaces in it is still a filename — and reloads it on the next run, so a fact you taught yesterday is available in a session that starts today. It uses node:sqlite, so there is no native module to install, and a memory file from an earlier version is imported once and kept as .json.imported rather than deleted.

Memory is stored independently of the transcript, so a turn can be persisted while its memory is not and the other way round. Three switches control it:

Memory is entirely in-process plus that database; the agent is never asked to author or maintain memory files by hand.

Everything above runs in-process against a SQLite file under ~/.nah. The same cognitive layer is also available as a hosted service, and /cogmem switches between them without changing what the model sees — same tiers, same index/body split, same deterministic recall. Only where the memories live changes.

> /cogmem setup
Service URL [https://cogmem.astracollab.app]:
Key: 1) device credential store  2) paste here  3) use COGNITIVE_MEMORY_KEY  [1]:
  service ok · version 1.4.0 · extractor rules+model
memory → hosted · https://cogmem.astracollab.app

> /cogmem
Cognitive Memory
  backend   hosted · https://cogmem.astracollab.app
  key       cmk_…1f (40 chars) from the credential store
  memories  14 L1 · 2 L2 · 0 L3

> /cogmem local
memory → local · everything you already learned is still there

Two things are deliberately not done for you. The local store is never touched when you connect, so /cogmem local brings everything back and nothing is copied anywhere until /cogmem import is confirmed. And a service that is unreachable never fails a turn: the prompt block is skipped, the reason is shown in /cogmem and /memory, and the same is true at startup — hosted memory with no usable key falls back to local and says why, because a silent fallback is indistinguishable from working memory until a fact fails to arrive.

The key comes from COGNITIVE_MEMORY_KEY if that is set, and from the platform credential store otherwise, in the same place provider keys live. COGNITIVE_MEMORY_URL overrides the service URL, which is what makes a self-hosted deployment one variable away. In hosted mode the service does the extraction, so the turns you have are sent to it to learn from — the trade for not spending a model call per turn on your own provider.

Methods

Constructor options

Types for every item above — MemoryItem, MemoryInjectionReport, MemoryInclusionReason, MemoryReconciliation, KnowledgeTension, CognitiveMemoryOptions — are exported from the package root alongside the class, as are the deterministic primitives it ranks with: extractDeterministic, extractIdentifiers, isInteractionScoped, runFastGate, relevanceTokens and overlapScore.

There is also packages/nah/eval-memory.mts, which teaches facts containing unguessable tokens, wipes the transcript, and asks again — so anything the model can still answer came out of memory rather than context.