Memory & Familiarity

Two different things, often confused:

• Memory is what your character knows about someone. It expires.
• Familiarity is how well you know them. It makes scans faster, never more certain, and it survives memory expiry.

#Memory lifetime

Tiers = {
    { minPct = 100, seconds = 432000 },   -- 5 days
    { minPct = 80,  seconds = 86400 },    -- 24 hours
    { minPct = 50,  seconds = 7200 },     -- 2 hours
},

Checked from the top: the first line whose minPct the result reaches wins. A memory is at full strength until it runs out, then it is gone — a hard cut, no fading.

#What "upgrade" means in practice

You see someone badly through a rainy window: 66 %, two-hour memory. Next day you have a proper conversation with them in daylight. With UpgradeOnRecognize = true, that two-hour memory becomes a 100 % / 5-day memory — the tier comes from the refreshed memory, not from the old one. The timer is still never shortened.

#The memory line

Players see a memory as where and when they first met the person, never as a list of clothes: "Met him on Vinewood Blvd in the evening", "The guy from the tattoo shop", "Heard of a woman seen in Davis". The line is written once, at the first meeting, and never changes. The time is only the part of the day (morning, afternoon, evening, night). From Config.Familiarity.KnownWellLevel on, the line becomes "I know him well". A name the person introduced himself with still shows next to it.

The old clothing words are still stored, and admins see them in the panel and in Discord next to the full detail (place, street, area, part of day and hour). A memory saved before this line existed keeps its clothing words.

A known place wins over the street. Config.Places lists them:

Config.Places = {
    { id = 'tattoo_vinewood', kind = 'tattoo', coords = vector3(322.62, 180.34, 103.59), radius = 15.0 },
    -- ...
}

The shipped list covers the GTA V clothing, barber and tattoo shops, the hospitals, the police stations, the airport terminal and the Del Perro pier. The place is worked out by the server from where the scanner stood. Players only ever see the words of the kind ("the tattoo shop"), never the id or the position.

#Disguises

A disguised acquaintance is scanned, scored and reported exactly like a stranger — result Noted, an automatic label like "the hoodie guy", and a second memory row. Your memory of the real person is untouched.

DisguiseMatchFloorPct is used only while the face is hidden. Once the face has been seen, the scan always goes to the real person. The same outfit with a different cap scores about 94 %, far above the default floor of 40.

#MergeDisguises

#The live scene

After a successful scan the result stays on the HUD and updates live while the person is around.

The live scene is also what nametag and chat scripts ask about by default — see Config.Api below.

#Familiarity

Knowing someone well makes re-learning them faster: a full scan of somebody whose memory ran out. It never changes the 2–3 second quick look of somebody you still remember, and it never adds a single percentage point.

Levels = {
    { name = 'stranger',     at = 0,  mult = 1.0 },
    { name = 'acquaintance', at = 3,  mult = 1.25 },
    { name = 'familiar',     at = 7,  mult = 1.5 },
    { name = 'close',        at = 15, mult = 2.0 },
},

Familiarity is per character pair: only recognitions of the real person count. While someone is disguised you do not know who they are, so there is nothing to grow familiar with.

Familiarity survives memory expiry. It is reset only by the death rule or by the other person's face implant.

#Identity changes from other scripts

#Answers given to other scripts