Skip to content

Learning & Ranking

Facts need a model (the observer). Everything on this page needs none. It is counted from what the hooks see, in plain SQL, on the hook path or in the daily consolidation.

Five signals (corrections, failures and fixes, reverts, accesses, co-occurrence) feed rules, recipes, dead ends, usage stats and Hebbian edges, which show up as notes or blocks, fix hints, file history, ranking and graph ties.
Open in Excalidraw

Memories used often and recently rank higher. Unused ones fade, but nothing is deleted for being old.

B = ln Σ_j max(t_j, 1) ^ -0.5 t_j = hours since retrieval j (the newest 20 exactly,
older ones approximated with the age of the oldest of those 20)
activation_factor = 0.5 + 0.5 · σ(B) σ = logistic function; a memory never retrieved gets B = -10 → 0.5

What counts as a retrieval: created, get, used, cited. What does not: shown and injected. An injection is an exposure. Counted as a retrieval, it would raise the activation of whatever was injected and make it injected again, so the briefing would feed itself.

Hours since one retrievalt^-0.5Bfactor
≤ 11.000.000.75
240.20−1.590.58
168 (a week)0.077−2.560.54
five retrievals within the last hour5.001.610.92
usefulness = (used + 1) / (shown + 2) Laplace-smoothed, neutral 0.5
usefulness_factor = 0.5 + usefulness 0.5 … 1.5, used in every search score
briefing_factor = 0.5 + (used + 1) / (injected + 2) used for the session-start briefing

A memory counts as used when the agent:

SignalAccess kindRecorded by
opens it with mem_getgetmemory/views.details
edits a file the memory is linked to, after it was shown or injected this sessionusedcapture._feedback_used
writes its id (T12, M3) in the final answercitedcapture._on_stop

A memory injected at many session starts and never used makes room for something else (briefing_factor falls toward 0.5). One shown for every prompt and never opened sinks in search.

importance (0–1) is set when a row is written and only goes up:

EventImportance
a read0.1
a command0.3
an edit, a test0.5
an error, a long answer (over 200 characters)0.6
a decision, a dead end, a commit0.7
a correction0.8
a lesson0.8
an extracted rule (preference)0.85
a fix (a failing command passed again)0.9
a preference stated in two projects (global)0.9

In a score it counts as 0.7 + 0.3 · importance, so it never dominates.

trust says who wrote the text: user (1.0, what you typed), agent (0.9, mem_remember, imported notes), observer (0.8, extracted facts), tool_local (0.8), tool_external (0.5, web pages, third-party MCP servers), raw (0.8, a turn kept word for word).

you type: "Use pnpm instead of npm"
→ rules(kind='avoid_command', pattern='npm', message='Use `pnpm` instead of `npm`', evidence=1, enabled=0)
again: evidence = 2 = rules.min_corrections
→ memories(kind='preference', title='Use `pnpm` instead of `npm` (corrected 2x)', trust='user', importance 0.85)
→ with rules.auto_enable: enabled = 1
Rule stateBefore npm install
suggested (enabled = 0, default)a note: - Note (R1): earlier correction — Use pnpm instead of npm (1x).
enabled (agent-mem rules enable 1 or rules.auto_enable)the call is denied: agent-mem rule R1: Use pnpm instead of npm (you were corrected 2x).

The statements agent-mem recognizes in a prompt you typed:

PatternExampleRule
use / nutze / verwende / benutze / nimm X instead of / statt / anstatt / anstelle von / not Yuse pnpm instead of npmavoid npm, prefer pnpm
X statt / anstatt Y (short, or with backticks)`uv` statt `pip` | avoid pip, prefer uv
nicht / kein / not / no X [benutzen], sondern / but / use Ynicht pip benutzen, sondern uvavoid pip, prefer uv
never use / don't use / do not use / nie / niemals / kein / keine / nicht Xnever use yarnavoid yarn (no preferred tool)

A bare X statt Y inside a long sentence without backticks is ignored: “Redo anstatt Reuse zu nennen” is a word swap, not a tool rule.

Rules for counting:

  • One turn is one statement. The prompt hook and later the observer read the same prompt; counted twice, a sentence typed once would become a preference. The key rule.turn|<project>|<avoid>|<prefer>|<turn> in meta makes each count unique.
  • The newer statement wins. “Use npm instead of pnpm” after “use pnpm instead of npm” disables the old rule and retires its preference; with both on, npm and pnpm would both be blocked.
  • Only your words. A rule extracted by the observer is created only if both tool names appear in what you typed, not just in a README the agent read.
  • A rule matches programs, not substrings. The command is split at &&, ||, ; and |, redirects and leading VAR=value assignments are removed, and the rule’s pattern is compared with the programs that run.
  • Overrides. Typing trotzdem, egal, anyway, do it anyway, ignore the rule or mach es trotzdem within 15 minutes after a rule fired counts as an override; the second override switches the rule off.
  • Expiry. An enabled rule that has not fired for rules.expire_days (90) is switched off by the daily consolidation.

Manage rules with agent-mem rules list|enable|disable|delete <id>.

When a test, build, lint or install command fails and the same tool later passes in the session, agent-mem records an error-to-fix recipe:

ColumnExample
error_sighash of the normalized error (paths, numbers, hex ids, quoted names removed)
error_textE ImportError: cannot import name 'subtract' from 'calc' (calc.py)
command_keyuv run pytest
files_json["calc.py"], the files edited between the failure and the pass
successes, recurrenceshow often it was fixed, how often it came back

The next failure with the same signature gets This error was seen before with uv run pytest and fixed by changing calc.py (see T1). Seen 1x, fixed 1x. A failed cat, grep or ls is looking around and never makes a recipe; a non-zero exit without an error line (grep with no match) is not an error that was fixed. The daily consolidation drops recipes that slipped through from older releases.

A successful git revert, git restore, git checkout -- <file> or git reset --hard turns the session’s reverted edits into a dead_end memory linked to those files:

Changes to calc.py were reverted (`git checkout`) — context: Make subtract accept strings

Before the next read or edit of calc.py in any session, the file history shows it first, labelled Caution.

Every finished turn links its files, the working part of its commands (uv run pytest, not the whole line), its error lines and error signatures as entities. Entities of one turn are connected pairwise with a Hebbian update:

w ← w + 0.1 · (1 − w) per co-occurrence, at most 12 entities (66 pairs) per turn
w ← w · 0.5 ^ (days / 60) decay in the daily consolidation; edges under 0.05 are removed

At search time, entities named in the query seed a Personalized PageRank (restart probability 0.5, 30 iterations) over the project’s edges; the top 30 nodes and the seeds weight the memories and turns linked to them. Frequent “hub” entities (a test command in every turn) are damped like IDF: weight / (1 + ln(1 + degree)), and only their 50 newest links are read. The graph reorders hits that text and vectors found (× (1 + 0.3 · tie)); it adds no candidates of its own.

Separately, the observer reads memories into a typed graph of concepts and relations (“search.py uses SQLite FTS5”) that the viewer draws. See Observer Pipeline.

The indexer runs this at most once per 24 hours (meta.consolidated_at):

StepWhat
1decay and prune Hebbian edges
2a preference you stated in two or more projects becomes a global preference (across projects), importance 0.9; it is withdrawn when the projects take it back
3of facts, decisions and summaries with the same normalized title in a project, the newest wins
4enabled rules unused for rules.expire_days are switched off
5recorded commands keep only their reusable part (… 2>&1 | tail; git status → uv run pytest -q)
6recipes whose “error” is no error are dropped
7entities that are whole command lines or scratch files are merged into their working part or removed
8git blob hashes are recorded for linked files (anchors)
9a dead end or decision whose every anchored file was deleted is retired
10with vectors: new memories add related: <title> as a search key to up to four neighbours with cosine ≥ 0.85 in the same project

The vector side also retires an older observer or agent memory when a newer one of the same project says the same thing (cosine ≥ semantic.duplicate_min_cosine, 0.90). What you wrote is never retired this way.

search score = rrf_norm × activation_factor × (0.7 + 0.3 · importance) × usefulness_factor × trust × project_boost
briefing = activation_factor × briefing_factor × (0.7 + 0.3 · importance) × kind priority
kind priority: preference 1.3 · dead_end 1.25 · decision 1.2 · correction 1.1 · lesson 1.1 · other 1.0

See Search Architecture and Context Injection.