Option

Default

Effect

clients

claude-code and codex, each read, write and delete, tokens generated

Who may call: name, scopes, and optionally ip (reads only, by source address) or token_sha256 (a token made elsewhere).

github_owner

unset: every owner

Narrows memory_namespace to GitHub remotes under this owner.

forge_hosts, forge_owner

none, unset

Gitea or Forgejo hosts whose remotes become gitea/<owner>/<repo>, optionally only under this owner.

project_links

none

Repository namespaces that share a projects/<name> scope.

hubs

none

Namespaces whose search and task match reach every other repository namespace.

namespace_renames

none

{from, to} owner prefixes moved at start after an owner rename.

review_at

03:00

Local time of the nightly candidate review; off turns it off.

candidate_expiry_days

14

Days an extracted candidate waits for review before the nightly review forgets it; 0 off.

summary_candidates

false

Keep each session's closing summary as a candidate.

anchor_sweep_hours

6

Interval of the entity anchor check, 1 to 168.

context_budget_tokens, hard_context_limit_tokens

4000, 8000

Default and maximum project_context packet.

retention_deleted_days

30

Forgotten records and recorded queries are purged after it.

ollama_url, ollama_fallback_url, ollama_direct_urls

unset: no enrichment

Ollama, or an OpenAI-style server when the URL ends in /v1 (Model server).

ollama_model, ollama_models, ollama_timeout_s

qwen3.5:9b, unset, 120

Default model, per-kind chains, call limit (Model routing).

embed_url, embed_model, embed_timeout_s

unset: full-text only, qwen3-emb-0.6b, 2

Encoder for embedding retrieval (Embedding retrieval).

Piece

Choice

Storage

SQLite in WAL mode under /data, FTS5 over title and content (stemmed, porter), append-only audit, durable job queue

Agent interface

MCP over streamable HTTP with JSON responses: POST http://<ha>:8765/mcp; the same tools as REST under /api/

Namespaces

github/<owner>/<repo> and gitea/<owner>/<repo> from git remotes (other owners are refused), projects/<name>, topics/<name>, global, local/<name>

Retrieval order

repository, its linked projects, given topics, global; a hub's search and task match then reach every other repository namespace

Ranking

reciprocal rank fusion of FTS5 and cosine over record embeddings when the encoder answers, FTS5 otherwise (Embedding retrieval)

Budgets

bootstrap 500 tokens over the whole response (2,000 bytes), search 750, records 2000, packet 4000 (hard limit 8000); every response reports its estimate and truncation

Auth

per-client bearer token (generated by the add-on, or a sha256 in options) or source address; scopes read, write, delete, export, admin, checked by one rule for MCP tools and REST routes; an address client gets read at most; a token client is recorded as the writer

Requests

a request with an Origin header gets 403; a POST must be application/json (415) with a Content-Length from 0 to 1 MiB (400, 413)

Filtering

every persisted field and queued payload: credentials, key material, JWTs, URL passwords and the do-not-store marker are refused and audited by field and pattern name; every database write passes the same screen, and audit context carrying a secret is kept as [screened:<pattern>]

Health

GET /health carries the add-on version; the MCP serverInfo and the HTTP server report the same version; the image's HEALTHCHECK reads GET /healthz

Page

ingress only, dark, drawn as graphics: status tiles, records by type and status, namespaces, audit rows per hour, model servers and encoder, nightly review and anchor sweep, unused records, latest audit rows

Status

set by the server: memory_store writes active; extraction and import write candidate through Store.store_candidate; a session close's summary is a candidate when the summary_candidates option is on, and is not kept otherwise (extraction reads it in the notes). States active, candidate, superseded, deleted; memory_update moves candidate to active and back; only a supersession makes superseded and only memory_forget makes deleted

Writer

a token client's name replaces agent; only a token client writes

Revision

an integer on every record, advanced by every mutation (content, anchors, anchor state, evidence, status, supersession, forget, rename). memory_update(id, revision, changes) applies only at that revision, anchors and status in the same transaction; a mismatch returns revision and current (MCP isError, REST 409)

Transactions

each mutation and the reads it depends on commit together: an update, a store with its supersession, an anchor report with its evidence, an extraction's candidates with the job's completion, an answer with its job's. Every statement runs under the store lock, so no read sees another thread's open transaction

Supersede

supersedes on a store retires a live active record in the same namespace; never the record itself, never a cycle, and only from an active replacement; checked in the store's transaction

Screen

every persisted string, list and job payload; a URL anchor with userinfo or a query or fragment parameter named as a credential (judged by the name's words: access_token, apiKey, session_id refused; author, session_count kept) is refused; session notes carrying do-not-store anywhere in the text as sent are refused, and the summary is still stored

Session close

op_id (8-64 of A-Za-z0-9_-) keeps the result as a receipt in the close's transaction, bound to the client and every input; a replay by that client with the same inputs returns it with replayed: true; the id from another client or for another close is refused (409); past retention_deleted_days the receipt is a tombstone and a replay is refused as expired (410)

Bootstrap

the 500-token budget is 2,000 bytes on the wire: the REST body, or the whole JSON-RPC reply over MCP; an item that does not fit is left out, the first included, and left_out counts them. A namespace is at most 160 characters, topics at most 8 of 1-40 characters; a base that does not fit is refused

Anchor

Checked by

Where

entity:

the add-on's sweep, every anchor_sweep_hours, and memory_anchor_sweep

the add-on, against Home Assistant's states through the Supervisor

path:

a client that can see the path, through memory_anchor_report, for example a session-start hook that resolves a relative path against the checkout of the record's repository namespace and reports unavailable when it has none

the host holding the path

host:

a client, through memory_anchor_report

any host on the LAN

url:

a client, through memory_anchor_report

any host that can reach the URL

Search arguments

min_cosine keeps hits at least that similar, and none under FTS ranking; exclude drops hits whose id starts with an entry of 8 or more characters; recall: true writes no row to the demand signal. A client hook searching with each prompt sets all three

Counted

returned: hits of search, recall and project context; fetched: records memory_get returned. Bootstrap and timeline are not counted

Storage

table usage(record_id, returned, fetched, last_returned_at, last_fetched_at), apart from memories so a read never re-indexes full text; purge and hard forget drop rows

Unused

the page lists active records older than 30 days that nothing returned in 30 days, oldest first, once counting has run 30 days (audit row usage-start)

Store

Queries

FTS5

Cosine alone

Fusion

24 records

72

0.83

0.94

150 records

42 (targets still live)

0.74

0.82 (-0.023 to +0.178)

0.81 (+0.014 to +0.122; better on 11 targets, worse on none)

Used when

the encoder answered its last probe, the query's vector arrives within embed_timeout_s, and every record the search could return has a current vector

Otherwise

FTS5; ranking in the response says which answered

Records ranked

every live record in the scopes and hub reach, the same set full-text search reads

Fusion

the FTS5 list and the cosine list, each cut to max(limit, 20); score is the sum of 1/(60 + position) over the lists holding the record; then multiplied by the record's evidence factor, its earned confidence over the confidence its writer asserted (1 for a record no one has corroborated or contradicted; why says evidence x<factor> otherwise); ties to the higher cosine, then the lower id; ranking is rrf

Query text

Instruct: Given a web search query, retrieve relevant passages that answer the query\nQuery: then the query

Record text

title\ncontent, no instruction

Storage

table embeddings(record_id, digest, model, vector), float32; digest is sha256 of model, snapshot and text

Stale

an edit, another model or another snapshot changes the digest; search uses FTS until the worker re-embeds

Worker

embeds missing and stale records at start and after each store or edit; probes the encoder every 30 s

Snapshot

the last path segment of root in the server's /v1/models, or from llama-swap's /upstream/<model>/v1/models

Removed

memory_forget and purge drop the vector

Not sent

a query that screens as carrying a secret

Cosine

each hit carries cosine, rounded to 4 places; FTS hits carry none

Not affected

the demand signal counts FTS hits; standing answers take FTS sources

Verdict

Applied when

Effect

duplicate

the named record was shown, is not a session summary standing in for another type, and holds every number, version, path, identifier and quoted phrase in the candidate

forgotten

session-state

the candidate was extracted from session notes, or an agent stored it as a type other than decision, constraint, requirement, procedure or preference

forgotten

keep, a failed call, or a guard refusing

always

stays for the agent review at session start

Where questions come from

memory_questions ranks what sessions actually asked; memory_question_add declares one

Demand signal

asked often AND answered badly; a well-answered question scores near zero

Who answers

the existing job queue and model worker, one refresh per idle poll, no scheduler

Reading

memory_answer is a database read: no retrieval, no model call

Freshness

basis digests the id, timestamp and text of every source record, so staleness is a string comparison

Grounding

the answer cites source_ids; nothing in scope gives No record in scope answers this.

Brevity

at most four sentences, and cut to ANSWER_CHARS on the way into the store

ollama_url

Client

Availability

Chat

Thinking off

Extraction JSON

ends in /v1

OpenAI-style (llama-server, llama-swap)

GET /v1/models

POST /v1/chat/completions

chat_template_kwargs.enable_thinking: false

response_format json_schema requiring a memories array

anything else

Ollama

GET /api/tags

POST /api/chat

think: false

format: json

Live

a server that answered its last availability probe; a probe runs at least every 15 s from the worker's poll, never inside a call; a server not yet probed counts as live

Chosen

the live server with the fewest calls in flight, ollama_url first on a tie; the nightly review runs one worker per live server and at least two, so its candidates split between the hosts

Tiers

ollama_url and ollama_fallback_url first; ollama_direct_urls only while neither is live, for example a router in front of several hosts as ollama_url and the hosts themselves as direct URLs

A server that does not answer a call

marked down until its next probe; the call moves to the next live server

An HTTP error from a server that answered

that model's failure: the next model in the chain on the same server, then the next server

A model that is not running

the call goes to the server anyway; llama-swap loads a configured model on its first request

Stances

corroborates, contradicts

Derived

proof_count, refutation_count, effective_confidence

Unwitnessed record

keeps the confidence it was given

Each corroboration

closes a third of the remaining distance to 1.0

Each contradiction

halves what is left, so one refusal outweighs two agreements

Ranking

search uses effective_confidence; why reads N for/M against or asserted, unwitnessed