Setharkk

Agent IA autonome local avec memoire long terme et knowledge graph

---

Setharkk tourne 100% en local sur un GPU consumer (RTX 3060 12 Go).
Il raisonne, utilise des outils, apprend de ses conversations, et construit un graphe de connaissances.
Zero API cloud. Zero cle API. Zero donnees envoyees a l'exterieur.

flowchart TD
    A[User Input] --> B{Router}
    B -->|DIRECT_RESUME| C[Resume Session]
    B -->|DIRECT_RECALL| D[Neo4j Search]
    B -->|DIRECT_FILE| E[File System]
    B -->|SIMPLE_TOOL| F[State Machine Planner]

    F --> G[CALL_LLM]
    G --> H[PARSE_RESPONSE]
    H -->|tool calls| I[EXECUTE_TOOLS]
    H -->|text| J[CHECK_RESPONSE]
    I --> G
    J -->|empty / truncated| G
    J -->|content| K[REFLECT]
    K -->|checks ok| L[RESPOND]
    K -->|checks fail| G
    L --> M{Task Complete?}
    M -->|too short| G
    M -->|ok| N[Done]
    J -->|max steps| O[FORCE_RESPOND]
    O --> N

    style A fill:#1a1a2e,color:#fff
    style B fill:#16213e,color:#fff
    style F fill:#0f3460,color:#fff
    style G fill:#533483,color:#fff
    style K fill:#e94560,color:#fff
    style L fill:#0f3460,color:#fff
    style N fill:#1a1a2e,color:#fff
    style O fill:#e94560,color:#fff

7 etats : CALL_LLM > PARSE_RESPONSE > EXECUTE_TOOLS > CHECK_RESPONSE > REFLECT > RESPOND > FORCE_RESPOND

Le Router intercepte les cas simples sans appeler le LLM (recall memoire, lecture fichier, listing dossier, reprise de session). Tout le reste passe par le planner.

Specifique Qwen 3.5 9B : le planner inclut un parseur XML fallback pour les tool calls que Qwen met parfois dans le content au lieu du format natif.

flowchart LR
    subgraph PG["PostgreSQL"]
        direction TB
        CM["core_memory<br/><i>identite, regles, profil</i><br/>toujours dans le prompt"]
        RM["recall_memory<br/><i>log conversation / session</i><br/>reconstruction OpenAI format"]
    end

    subgraph N4J["Neo4j"]
        direction TB
        M[":Memory<br/><i>faits archivaux</i><br/>vector index 384d"]
        E[":Entity<br/><i>personnes, projets, tech</i>"]
        M -->|:MENTIONS| E
        E -->|:RELATES| E
    end

    PG -.->|operationnel| Agent((Agent))
    N4J -.->|long terme| Agent

    style PG fill:#4169E1,color:#fff
    style N4J fill:#008CC1,color:#fff
    style Agent fill:#533483,color:#fff

Chaque souvenir dans Neo4j est classe par un score composite (configurable dans agent.yaml) :

Le graphe Neo4j stocke des entites (personnes, projets, technologies, concepts) et leurs relations :

• add_entity() -- upsert avec MERGE Cypher, garde la description la plus longue
• add_relationship() -- upsert, incremente le poids a chaque occurrence
• link_memory_to_entities() -- lie un fait a ses entites (relation :MENTIONS)
• search_entities() -- recherche textuelle par nom/description
• get_neighbors() -- traversee Cypher multi-hop
• get_subgraph() -- recherche + traversee + faits lies

flowchart LR
    subgraph Boot["Boot (1er message)"]
        direction TB
        B1["Phase 1 : Identite<br/><i>k=5, query anglaise</i>"]
        B2["Phase 2 : Contexte adaptatif<br/><i>k=7, base sur le message user</i>"]
        B3["Phase 3 : Knowledge Graph<br/><i>k=3, entites liees</i>"]
        B1 --> B2 --> B3
    end

    subgraph Session["Session active"]
        direction TB
        S1["Messages persistes<br/>dans PostgreSQL"]
        S2["Compaction auto<br/><i>si > 40K chars</i>"]
        S3["DataCollector<br/><i>sauvegarde fine-tuning</i>"]
    end

    subgraph Close["Fermeture / /clear"]
        direction TB
        C1["Extraction deterministe<br/><i>Q/R, erreurs, fichiers</i>"]
        C2["Extraction LLM<br/><i>entites + relations</i>"]
        C3["Dedup similarite > 0.85"]
        C4["Store Neo4j + link"]
        C1 --> C2 --> C3 --> C4
    end

    Boot --> Session --> Close

    style Boot fill:#533483,color:#fff
    style Session fill:#0f3460,color:#fff
    style Close fill:#e94560,color:#fff

La dedup par similarite (seuil 0.85) empeche les doublons entre sessions. L'extraction LLM est optionnelle (si le serveur LLM est arrete, l'extraction deterministe fonctionne seule).

Tous les seuils et timeouts sont dans configs/agent.yaml. Zero hardcode.

Pas de LLM-as-judge : un 9B qui juge sa propre sortie cause la "degeneration of thought" et degrade le win rate (arxiv 2604.07236). Tous les checks sont deterministes.

Max 1 reflexion par run au niveau planner, max 1 relance au niveau agent. Pas de boucle infinie.

Gere le budget tokens automatiquement pendant la conversation :

• Compaction : si le contexte depasse 40K chars, les anciens messages sont compresses en resume deterministe (objectif/actions/progres) et sauvegardes en Neo4j
• Truncation tool results : les anciens resultats de tools sont tronques a 5K chars, les 6 derniers messages sont preserves intacts
• Summary dans le prompt : le resume est injecte DANS le system message (Qwen --jinja exige un seul message system)

Terminal Rich avec commandes slash :

FastAPI + WebSocket sur http://127.0.0.1:8090. Chaque connexion WebSocket obtient son propre Agent + Memory isoles (multi-session).

Le 9B est le modele par defaut (rapide, contexte large). Le 35B-A3B est disponible pour les taches complexes.

Chaque interaction est sauvegardee automatiquement en format ChatML dans training/data/interactions.jsonl. Ces donnees peuvent etre utilisees pour un LoRA fine-tuning via Unsloth.

Application single-page (1430 lignes HTML/CSS/JS) avec :

• Chat en temps reel via WebSocket
• Affichage des etapes d'execution (THINK / ACT / OBSERVE / RESPONSE)
• Upload de fichiers comme prompt
• Commandes slash intégrées
• Multi-session isole (chaque connexion a son propre Agent + Memory)

Le systeme collecte automatiquement les interactions pour un futur LoRA fine-tuning :

training/
|-- finetune.py              QLoRA via Unsloth (Qwen 3.5)
|-- merge_and_export.py      Fusion LoRA + export GGUF
+-- data/
    |-- interactions.jsonl    260+ interactions reelles (ChatML)
    +-- synthetic_examples.jsonl  49 exemples synthetiques

finetune.py lance un QLoRA sur les interactions collectees. merge_and_export.py fusionne le LoRA avec le modele de base et exporte en GGUF quantise pret pour llama.cpp.

setharkk/
|-- main.py                          Entry point CLI
|-- web_main.py                      Entry point FastAPI
|-- docker-compose.yml               Neo4j container
|-- configs/
|   |-- agent.yaml                   Config complete (100% config-driven)
|   |-- model.yaml                   Qwen 3.5 9B
|   +-- model_35b.yaml              Qwen 3.5 35B-A3B (alternative)
|-- agent/
|   |-- core/
|   |   |-- agent.py                 Agent + boot 3 phases + resume + task check
|   |   |-- planner.py              State machine (7 etats + REFLECT)
|   |   |-- memory.py               PostgreSQL + Neo4j + KG + SessionExtractor
|   |   |-- context_manager.py      Budget tokens + compaction + truncation
|   |   |-- router.py               Classification intent (5 intents)
|   |   +-- data_collector.py       Sauvegarde ChatML pour fine-tuning
|   |-- models/
|   |   |-- local_model.py          Client llama-server (chat + chat_with_tools + stream)
|   |   +-- prompts.py              System prompt dynamique (tools depuis ToolRegistry)
|   |-- tools/                       12 tools (8 fichiers)
|   +-- ui/
|       +-- cli.py                   CLI Rich avec commandes slash
+-- web/
|   |-- server.py                    FastAPI + WebSocket (multi-session isole)
|   +-- index.html                   Interface web
+-- training/
|   |-- finetune.py                  QLoRA fine-tuning via Unsloth
|   |-- merge_and_export.py          Fusion LoRA + export GGUF
|   +-- data/                        Interactions collectees (ChatML)
+-- scripts/
    |-- start_server.bat             Lancement 9B
    |-- start_server_35b.bat         Lancement 35B-A3B
    |-- build_llama.bat              Compilation llama.cpp depuis source
    |-- quantize_model.bat           Quantization GGUF (F16 -> Q4_K_M)
    |-- setup_db.py                  Init PostgreSQL
    |-- migrate_memory_v2.py         Migration memoire v1 -> v2
    |-- migrate_archival_to_neo4j.py Migration PostgreSQL -> Neo4j
    +-- cleanup_pgvector.py          Nettoyage ancien backend pgvector

Toutes les valeurs sont dans configs/agent.yaml. Zero constante hardcodee.

# Infrastructure
docker compose up -d                    # Neo4j

# Serveur LLM
scripts/start_server.bat                # Qwen 3.5 9B sur port 8080

# Agent
python main.py                          # CLI
python web_main.py                      # Web --> http://127.0.0.1:8090