Manuale truenex-mem

Crea lo store di progetto nella directory corrente. È il prerequisito di index, search, add: senza, quei comandi non hanno un database su cui lavorare. Creates the project store in the current directory. It is the prerequisite for index, search and add: without it, those commands have no database to work against.

Diagnostica: esistenza del database, conteggi di documenti e memorie, backend vettoriale attivo. Il primo comando da lanciare quando qualcosa non funziona. Diagnostics: whether the database exists, how many documents and memories it holds, which vector backend is active. The first command to run when something misbehaves.

truenex-mem doctor --privacy

--privacy aggiunge la diagnostica su cosa viene inviato all'esterno e cosa no. --privacy adds a report on what does and does not leave the machine.

La prima stampa la versione in chiaro, la seconda tutte le versioni dei componenti in JSON. Entrambe leggono importlib.metadata, quindi riportano i metadata installati: in un venv editable con dist-info stantio mostrano il numero sbagliato anche se il codice è aggiornato. The first prints the version in plain text, the second every component version as JSON. Both read importlib.metadata, so they report the installed metadata: in an editable venv with stale dist-info they show the wrong number even when the code is current.

Gestione dello schema del database.Database schema management.

Il comando da lanciare dopo aver aggiornato il pacchetto: mette a posto i dati con il programma nuovo. Fa tre cose in un colpo — migra lo schema con backup che precede la migrazione, ricostruisce i grafi già esistenti, riscrive il profilo nei client installati — e stampa una riga per ciascuna. The command to run after upgrading the package: it brings the data in line with the new program. It does three things in one pass — migrates the schema with a backup taken before the migration, rebuilds the graphs that already exist, and rewrites the profile in the installed clients — printing one line for each.

truenex-mem upgrade
truenex-mem upgrade --skip-graphs --skip-profile

È idempotente: su un archivio già aggiornato dice 8 -> 8 e non copia niente. Non crea grafi nuovi — ricostruisce quelli che ci sono: il primo grafo di un progetto lo fa solo un graph build esplicito. It is idempotent: on an already-current store it says 8 -> 8 and copies nothing. It does not create graphs — it rebuilds the ones that exist: a project's first graph comes only from an explicit graph build.

Gestione della licenza Pro. status mostra lo stato, activate attiva una chiave (richiede internet), deactivate la rimuove, require verifica se la licenza attuale soddisfa un tier minimo — è quello che i comandi Pro chiamano internamente. Pro licence management. status shows the current state, activate registers a key (needs internet), deactivate removes it, and require checks whether the current licence meets a minimum tier — this is what the Pro commands call internally.

check verifica se esiste una versione più recente senza inviare dati di progetto. self aggiorna il pacchetto via pipx o pip. check looks for a newer release without sending any project data. self upgrades the package via pipx or pip.

Indicizza i file locali nello store di progetto: legge, spezza in chunk, scrive. Indexes local files into the project store: reads, splits into chunks, writes.

truenex-mem index src --chunk-size 800 --chunk-overlap 100 --exclude "*.min.js"

Indicizza le fonti dichiarate in un file manifest, invece di passare i path a mano. È la via per ingestioni ripetibili e versionabili. Indexes the sources declared in a manifest file instead of passing paths by hand. This is the route to repeatable, version-controlled ingestion.

Scrive un memory node manuale: una decisione, un vincolo, una nota che non vive in nessun file. --type ne definisce la natura (nota, decisione, ...). Writes a manual memory node: a decision, a constraint, a note that lives in no file. --type sets its nature (note, decision, ...).

truenex-mem add "Reindex must follow every refresh" --type decision

Cambia lo stato del ciclo di vita di un memory node. È il meccanismo con cui una memoria diventa active, resta unverified o viene marcata obsoleta senza essere cancellata. Il recupero tratta gli stati in modo diverso, quindi questo comando governa direttamente cosa l'agente vedrà. Changes a memory node's lifecycle status. This is how a memory becomes active, stays unverified, or is marked obsolete without being deleted. Retrieval treats these states differently, so this command directly governs what an agent will see.

Ricerca nello store di progetto.Searches the project store.

truenex-mem search "vector cache invalidation" --top-k 5 --json

Elenca i memory node manuali — non i chunk dei documenti. --status filtra per stato del ciclo di vita, --json dà output strutturato. È il modo per vedere cosa hai scritto tu, separato da ciò che è stato indicizzato. Lists manual memory nodes — not document chunks. --status filters by lifecycle state, --json gives structured output. This is how you see what you wrote yourself, separate from what was indexed.

Ogni ricerca lascia una traccia. logs --limit N elenca le tracce recenti, trace show TRACE_ID ne apre una con tutti i dettagli dei risultati. Every search leaves a trace. logs --limit N lists recent traces, trace show TRACE_ID opens one with full result detail.

Sono gli unici strumenti per capire perché una ricerca ha risposto male, e quindi i primi da usare quando il recupero delude. Ricorda il puntamento: una traccia generata via MCP vive nello store globale. These are the only tools for working out why a search answered badly, and so the first to reach for when retrieval disappoints. Mind which store you're pointing at: a trace generated over MCP lives in the global store.

Scopre progetti, documenti e server a partire dai client agent installati sulla macchina. Produce candidati, non fonti attive: nulla viene indicizzato finché non è confermato. Discovers projects, documents and servers from the agent clients installed on the machine. It produces candidates, not live sources: nothing is indexed until it is confirmed.

Cerca directory di agent non ancora note e opzionalmente le aggiunge alla discovery. Da lanciare quando installi un nuovo client. Scans for agent directories not yet known and optionally adds them to discovery. Run it when you install a new client.

Rivedere, confermare e aggiungere voci nel catalogo sources.json. È il punto di controllo di tutto il sistema: solo le fonti confermate vengono indicizzate da refresh. Review, confirm and add entries in the sources.json catalog. This is the control point of the whole system: only confirmed sources are indexed by refresh.

Refresh incrementale: carica le fonti confermate, gira i parser, confronta col ledger e indicizza solo nuovo o modificato, deduplicando per hash del contenuto. Incremental refresh: loads the confirmed sources, runs the parsers, checks them against the ledger, and indexes only what is new or modified, deduplicating by content hash.

Ri-incorpora i chunk con l'embedder semantico. Resumable: salta quelli già sul modello attivo, e ogni batch viene committato a parte, quindi si può interrompere e rilanciare. Re-embeds chunks with the semantic embedder. Resumable: it skips chunks already on the active model, and commits each batch separately, so it can be interrupted and relaunched.

Senza --yes stampa solo i conteggi — e lo fa senza istanziare il modello, quindi è istantaneo. Without --yes it prints counts only — and does so without instantiating the model, so it returns instantly.

Manutenzione automatica della memoria. run è un wrapper sopra global refresh che, con --auto-memory, genera memory node dal contenuto appena indicizzato. Automatic memory maintenance. run is a wrapper over global refresh which, with --auto-memory, generates memory nodes from the freshly indexed content.

Report read-only: catalogo, database, ledger, conteggi indicizzati, problemi. La sezione problems distingue error, missing e skipped — e gli skipped di tipo server_alias sono normali, perché non c'è indicizzazione via SSH. Read-only report: catalog, database, ledger, indexed counts, problems. The problems section separates error, missing and skipped — and server_alias entries under skipped are expected, because there is no indexing over SSH.

Contesto di un progetto confermato: root del catalogo, ledger, documenti e chunk indicizzati. Accetta nome, path o alias e prova a risolverli. Se risponde resolved: false, il progetto non è tra le fonti confermate — si corregge con global sources, non con un refresh. Context for a confirmed project: catalog roots, ledger, indexed documents and chunks. It accepts a name, path or alias and attempts to resolve it. If it answers resolved: false, the project is not among the confirmed sources — fix that with global sources, not with a refresh.

Ricerca nello store globale senza mutare i log di retrieval né lo stato del DB. È la variante da usare per valutare la qualità del recupero senza inquinare le tracce con i propri esperimenti. Searches the global store without mutating retrieval logs or DB state. This is the variant to use when assessing retrieval quality, so your experiments don't pollute the traces.

Gestisce il manifest di discovery degli agent: list, add, remove. Il manifest (~/.truenex-memory/agent_manifest.json) dichiara per ogni agent la sua directory e quali sottopercorsi contengono sessioni, cronologia e memorie — è così che global discover sa dove guardare. Manages the agent discovery manifest: list, add, remove. The manifest (~/.truenex-memory/agent_manifest.json) declares each agent's directory and which subpaths hold sessions, history and memories — this is how global discover knows where to look.

Aggiungere qui un client nuovo è il modo per far entrare le sue sessioni nello store senza toccare codice. Adding a new client here is how you get its sessions into the store without touching any code.

Genera il testo delle istruzioni per gli agent: agents-md per AGENTS.md (Codex e simili), claude-md per CLAUDE.md. Stampa su stdout, non scrive file. Generates instruction text for agents: agents-md for AGENTS.md (Codex and similar), claude-md for CLAUDE.md. It prints to stdout; it does not write files.

Oggi produce quattro righe di testo statico, uguali per entrambi i target a parte il nome del file: cercare in memoria prima di scrivere codice, preferire i risultati active, trattare gli unverified come tentativi, non usare gli obsoleti. Non esiste una policy come sorgente né un target per client diversi da questi due. Today it emits four lines of static text, identical for both targets bar the filename: search memory before writing code, prefer active results, treat unverified ones as tentative, don't use superseded ones. There is no policy acting as the source, and no target for clients beyond these two.

Registra le pipeline di task in modo strutturato, con i passi e un giudizio finale. È l'unico gruppo esposto anche via MCP, quindi l'unico che un agente può usare da solo durante il lavoro. Records task pipelines in structured form, with their steps and a closing judgment. It is the only group also exposed over MCP, and therefore the only one an agent can use by itself mid-task.

Il giudizio umano alla chiusura è ciò che alimenta calibration: senza chiudere i task con un verdetto, la statistica resta vuota. The human judgment at close is what feeds calibration: leave tasks unclosed or unjudged and the statistics stay empty.

Loop multi-agente ricorsivo. run esegue un loop da un file di configurazione JSON; converge-check verifica se due round persistiti sono byte-identici, che è il criterio di convergenza per fermare la ricorsione. Recursive multi-agent loop. run executes a loop from a JSON config file; converge-check tests whether two persisted rounds are byte-identical, which is the convergence criterion for stopping the recursion.

È il gruppo più sperimentale: la configurazione vive solo nel JSON, e il design è descritto in docs/recursive-orchestrator-design.md. This is the most experimental group: configuration lives only in the JSON, and the design is written up in docs/recursive-orchestrator-design.md.

Avvia il server stdio MCP. È il comando che ogni client agent lancia dietro le quinte: non si esegue a mano, si configura. Con --project-root si decide su quale store punta. Starts the stdio MCP server. This is the command every agent client launches behind the scenes: you configure it rather than run it. --project-root decides which store it points at.

truenex-mem mcp --project-root C:\Users\marco

Il controllo automatico degli aggiornamenti è disattivato per questo sottocomando, per non sporcare stderr e rompere il protocollo. The automatic update check is disabled for this subcommand, so it cannot pollute stderr and break the protocol.

Avvia l'API HTTP che serve la GUI desktop. Opzioni: --host, --port, --project-root. Espone anche /health con la versione. Come mcp, salta il controllo aggiornamenti. Starts the HTTP API behind the desktop GUI. Options: --host, --port, --project-root. It also exposes /health with the version. Like mcp, it skips the update check.

Esporta e reimporta i dati della memoria locale. La coppia più semplice per un backup manuale o per spostare uno store di progetto. Exports and re-imports local memory data. The simplest pair for a manual backup, or for moving a project store.

Sincronizzazione della memoria via Git: la memoria di progetto viaggia come repository, quindi versionata e condivisibile col team. Memory synchronisation over Git: project memory travels as a repository, so it is versioned and shareable with a team.

Costruisce il grafo di un progetto e lo salva nella cache (~/.truenex-memory/code_graphs/). Su una soluzione .NET di media taglia sono decine di secondi; il risultato è riusabile finché il codice non cambia. Builds a project's graph and saves it to the cache (~/.truenex-memory/code_graphs/). On a mid-sized .NET solution this takes tens of seconds; the result is reusable until the code changes.

truenex-mem graph build D:\Project_sw\ProjectPy\truenex-memory
truenex-mem graph build . --if-stale

--if-stale esce senza fare niente se il grafo è già aggiornato, in circa mezzo secondo: è ciò che rende il comando chiamabile a ogni salvataggio, o da un hook. --if-stale exits without doing anything when the graph is already current, in about half a second: this is what makes the command safe to call on every save, or from a hook.

La domanda vera: chi chiama questa entità, e quali test la coprono. Le due risposte sono separate, perché sono due domande diverse che prima finivano nello stesso elenco. The real question: who calls this entity, and which tests cover it. The two answers are kept separate, because they are two different questions that used to land in one list.

truenex-mem graph explain build_file_graph
truenex-mem graph explain build_file_graph --json

Il rapporto dichiara sempre i totals e se l'elenco è stato troncato: un elenco tagliato in silenzio si legge come completo. The report always states the totals and whether the list was truncated: a silently cut list reads as a complete one.

Elenca i grafi in cache con file e archi, senza costruire niente, e dice se l'estrattore è presente. Segnala anche le voci che non sono progetti — una cartella graficata per sbaglio — e quale comando le toglie. Lists the cached graphs with their file and edge counts, building nothing, and says whether the extractor is present. It also flags entries that are not projects — a folder graphed by mistake — and which command removes them.

Toglie un grafo dalla cache. Serve perché un grafo si poteva costruire e non rimuovere: una cartella graficata per sbaglio restava una radice nota per sempre, e ogni upgrade la ripercorreva. Removes a graph from the cache. It exists because a graph could be created and never removed: a folder graphed by mistake stayed a known root forever, and every upgrade walked it again.

truenex-mem graph forget --not-projects --dry-run
truenex-mem graph forget --not-projects

--not-projects toglie in un colpo le cartelle di configurazione dei client e la cartella dati di memory. Non tocca un progetto vero che risulta vuoto per un'altra ragione — un progetto in un linguaggio senza grammatica ha zero file esattamente come .claude, ma è un progetto. --not-projects sweeps client config folders and memory's own data folder in one go. It does not touch a real project that comes out empty for another reason — a project in a language with no grammar has zero files exactly like .claude, but it is a project.

Stampa il blocco che memory scrive, con i suoi marcatori. Sola lettura: serve a vedere cosa verrebbe scritto prima di scriverlo, e a leggere cosa un agente riceve oggi. --raw dà solo il testo, per incollarlo altrove. Prints the block memory writes, with its markers. Read-only: it is how you see what would be written before writing it, and what an agent receives today. --raw gives the text alone, for pasting elsewhere.

Quali client hanno il profilo, quali no, e chi è rimasto a una versione precedente. È la fotografia che rende visibile la deriva: senza, un client col profilo di tre versioni fa è indistinguibile da uno aggiornato. Which clients have the profile, which don't, and who is stuck on an older version. This is the snapshot that makes drift visible: without it, a client carrying a three-versions-old profile is indistinguishable from an up-to-date one.

Scrive o aggiorna il blocco nei client installati, lasciando intatto tutto il resto del file. È idempotente: rieseguirlo dice invariato. --dry-run mostra cosa farebbe senza toccare niente, --project lo scrive nell'AGENTS.md di un progetto invece che nella cartella utente. Writes or updates the block in the clients that are installed, leaving the rest of each file untouched. It is idempotent: run it again and it says invariato. --dry-run shows what it would do without touching anything; --project writes into a project's AGENTS.md instead of the user folder.

truenex-mem profile apply --dry-run
truenex-mem profile apply

Chi si è collegato davvero, e come è stato riconosciuto: dal nome dichiarato nell'handshake MCP, oppure risalendo l'albero dei processi quando il nome è generico (mcp, mcp-client). Un client che si presenta senza nome altrimenti sarebbe invisibile. Who actually connected, and how they were recognised: from the name declared in the MCP handshake, or by walking the process tree when that name is generic (mcp, mcp-client). A client that introduces itself anonymously would otherwise be invisible.

Misura il comportamento, non la presenza del file. Un profilo consegnato non è un profilo seguito: questo comando guarda quali strumenti ogni client ha davvero chiamato, e distingue chi cerca da chi usa solo il grafo (graph-only) e da chi non registra niente (no-recording). It measures behaviour, not whether the file exists. A delivered profile is not a followed profile: this command looks at which tools each client actually called, and separates those who search from those who only use the graph (graph-only) and those who record nothing (no-recording).