Human Memory Database · v1.0

MNHEME

La memoria non si sovrascrive.
Si stratifica.

Database append-only ispirato alla memoria umana.
Engine binario custom. Indici in RAM.
Filesystem-aware. LLM-agnostico.
Zero dipendenze esterne.

Esplora Download
DB

01 — Filosofia

La memoria umana
come modello di dati

I ricordi non si aggiornano. Non si cancellano. Si accumulano nel tempo, ognuno legato a un sentimento, a un momento preciso, irripetibile. MNHEME traduce questo principio in un sistema di storage.

I

Append-Only per Principio

Nessun metodo update(), nessun delete(). Il dataclass Memory è frozen=True: fisicamente immutabile dopo la creazione. Come i ricordi veri.

II

Concetto + Sentimento

Ogni ricordo ha una chiave concettuale (Debito, Famiglia) e un sentimento preciso tra 15 valori. Lo stesso concetto può portare emozioni diverse nel tempo — quella storia si chiama timeline.

III

Engine Binario Custom

Nessun SQLite. Nessun ORM. Il file .mnheme è un log binario append-only con magic bytes, frame SIZE+PAYLOAD, e fsync atomico su ogni scrittura. Crash-safe by design.

IV

Zero Dipendenze Esterne

Solo Python stdlib: json, struct, hashlib, uuid, urllib. Nessun pip install obbligatorio. Il provider LLM comunica via HTTP puro.

"Non puoi sovrascrivere ciò che hai vissuto. Puoi solo ricordarlo diversamente."

— MNHEME Design Principles

02 — Architettura

Quattro livelli.
Un'unica mente.

Ogni livello fa una cosa sola. MemoryDB non sa nulla dell'LLM. Il Brain non sa nulla del filesystem. La separazione non è convenzione — è architettura cognitiva.

Brain
→ perceive · ask · reflect · dream · introspect · summarize
LLMProvider
→ agnostico .env · Anthropic + OpenAI-compat · rate limiting · fallback
MemoryDB
→ remember · recall · search · reflect · export_json · import_json
StorageEngine
+
IndexEngine
+
FileStore
→ log binario · indici RAM · file fisici (hard link / reflink)
FsProbe
→ ext4 · btrfs · NFS · NTFS · FAT32 · 9p · APFS · ZFS · HDFS · tmpfs
📁

Storage Engine

Ogni record: [MAGIC 4B][SIZE 4B][JSON UTF-8]. Append-only. Atomico. Record troncati saltati silenziosamente al riavvio.

storage.py
🧠

Index Engine

Indici in RAM: concept → offsets, feeling → offsets, tag → offsets. Ricostruiti da zero al boot. Lookup O(1) via read_at(offset).

index.py
🔗

File Store

Hard link → Reflink → Symlink → Copy atomica. Deduplicazione SHA-256. Pool con sharding per hash. Un inode per ogni contenuto unico.

filestore.py
💽

Filesystem Probe

Rileva il filesystem via /proc/mounts, magic number statfs(2), e probe live di hardlink/reflink/symlink nella directory target.

fsprobe.py
🌐

REST API

FastAPI opzionale. Endpoints per tutti i metodi: /memories, /concepts, /feelings, /search, /export.

mnheme_api.py
📊

Benchmark Suite

7 sezioni: scrittura con/senza fsync, lettura via indici, full-text search, cold start, scalabilità, dimensioni file. Output JSON esportabile.

mnheme_benchmark.py

03 — Sentimenti

15 stati emotivi.
Ogni ricordo ne porta uno.

Gioia
Tristezza
Rabbia
Paura
Nostalgia
Amore
Malinconia
Serenità
Sorpresa
Ansia
Gratitudine
Vergogna
Orgoglio
Noia
Curiosità
TEXT IMAGE VIDEO AUDIO ✦ nuovo DOC ✦ nuovo

04 — Brain

L'LLM come
strato cognitivo

Il database è la memoria a lungo termine. L'LLM è il cervello che percepisce, associa, ragiona, riflette. Sei operazioni cognitive. Zero lock-in.

# Input grezzo → concept + feeling + tags estratti dall'LLM → Memory salvato r = brain.perceive("Ho aperto la busta dalla banca. Le mani tremavano.") # L'LLM ha estratto automaticamente: print(r.extracted_concept) # "Debito" print(r.extracted_feeling) # "paura" print(r.extracted_tags) # ["banca", "corpo", "ansia"] print(r.enriched_content) # testo arricchito con profondità psicologica # Il ricordo è già nel database, immutabile. print(r.memory) # Memory(id=a3f9bc12… concept='Debito' feeling='paura')
# RAG personale — risponde usando SOLO i ricordi reali come contesto ans = brain.ask("Come mi sento rispetto al denaro?") print(ans.answer) # risposta basata sui tuoi ricordi print(ans.memories_used) # [Memory(...), Memory(...), ...] ricordi usati come contesto print(ans.confidence_note) # "Certezza: alta — dati diretti dai ricordi" print(ans.provider_used) # "groq" quale provider ha risposto
# Analisi dell'evoluzione emotiva di un concetto nel tempo ref = brain.reflect("Debito") print(ref.arc) # "da terrore silenzioso a serenità faticosamente conquistata" print(ref.reflection) # analisi approfondita dell'arco emotivo print(len(ref.memories)) # tutti i ricordi del concetto, in ordine cronologico
# Associazione libera — connessioni inattese tra ricordi distanti # Simula il consolidamento onirico: ricordi da sentimenti diversi, filo nascosto dream = brain.dream(n_memories=8) print(dream.connections) # il filo invisibile, il tema latente, la metafora for m in dream.memories: print(f"[{m.concept}/{m.feeling}]", m.content[:50])
# Ritratto psicologico completo basato su tutti i ricordi intro = brain.introspect() print(intro.portrait) # ritratto: chi sei, pattern, tensioni, risorse print(intro.dominant_concepts) # ["Famiglia", "Lavoro", "Debito", ...] print(intro.emotional_map) # {"ansia": 8, "amore": 5, "nostalgia": 3, ...} print(intro.total_memories) # 247
# Setup completo — 4 righe from mnheme import MemoryDB from llm_provider import LLMProvider from brain import Brain db = MemoryDB("mente.mnheme") llm = LLMProvider.from_env(".env") # legge il .env brain = Brain(db, llm) # Cambia provider a runtime senza riavviare llm.use("groq") # passa a Groq llm.use("lm-studio") # locale, zero costi llm.use("anthropic") # Claude

05 — Provider

Agnostico per
principio di design

Un solo file .env. La convenzione NOME_URL + NOME_MODEL attiva qualsiasi provider. Anthropic viene rilevato automaticamente dall'URL. Tutti gli altri usano il formato OpenAI-compatibile.

LM STUDIO

local-model

60 RPM · no key

OLLAMA

llama3 / mistral

60 RPM · no key

ANTHROPIC

claude-opus-4-5

5 RPM · native API

GROQ

llama-3.3-70b

30 RPM

MISTRAL

mistral-large

5 RPM

SAMBANOVA

Llama-3.3-70B

12 RPM

OPENROUTER

llama-3.1-405b

10 RPM

GOOGLE AI

gemini-1.5-pro

15 RPM

CEREBRAS

llama3.1-70b

30 RPM

TOGETHER

Llama-3.1-70B

10 RPM

FIREWORKS

llama-v3p1-70b

10 RPM

+ 20 ALTRI

qualsiasi _URL + _MODEL

auto-discovery

Se l'URL contiene anthropic.com usa il formato nativo Anthropic.
Qualsiasi altro endpoint usa OpenAI-compat.
LM Studio, Ollama, qualsiasi server locale — senza chiave API.

06 — Benchmark

Numeri reali.
2.000 record.

Misurati su filesystem 9p (virtuale). Tutte le operazioni di lettura usano gli indici RAM — solo i byte necessari vengono letti dal file fisico.

Operazione media/op throughput note
remember() con fsync1.8 ms552 ops/sdurabilità garantita
remember() senza fsync0.2 ms4.632 ops/s8.4× più veloce
count() — pura RAM~0 ms2.774.322 ops/sO(1) da indice
feeling_distribution()0.003 ms277.865 ops/sO(1) da indice
recall(concept, limit=10)1.5 ms636 ops/s10 read_at dal file
recall_by_feeling(limit=20)3.0 ms332 ops/s20 read_at dal file
recall_all() — 2.000 rec300 ms3 ops/scarica tutto in RAM
search(full-text)40 ms24 ops/s~49k record/sec scansionati
search(limit=5)0.1 ms8.348 ops/ssi ferma al 5° match
MemoryDB() cold start40 ms—49k record indicizzati/sec

DIMENSIONE FILE

374 B / record in media

~36 MB per 100k record

~357 MB per 1M record

COLD START STIMATO

10k record → ~200 ms

100k record → ~2 s

1M record → ~20 s

FILESYSTEM SUPPORT

HARDLINK: ext4, NTFS, ZFS, NFS

REFLINK: btrfs, xfs, APFS

COPY: FAT32, exFAT, HDFS

07 — Struttura

13 file.
Zero dipendenze.

.py

mnheme.py

Core pubblico — MemoryDB, Feeling, MediaType, Memory. L'unica API che devi conoscere.

.py

storage.py

Engine binario append-only. Frame MAGIC+SIZE+PAYLOAD. fsync atomico. Crash-resilient.

.py

index.py

Indici in RAM: concept, feeling, tag, timeline. Ricostruiti dal log al boot.

.py

fsprobe.py

Rilevamento filesystem. Probe live di hardlink/reflink/symlink nella directory target.

.py

filestore.py

Storage file fisici. Pool SHA-256 deduplicata. Strategia adattiva per filesystem.

.py

llm_provider.py

Provider agnostico da .env. Rate limiting, retry, fallback multi-provider. Zero SDK.

.py

brain.py

Strato cognitivo LLM: perceive, ask (RAG), reflect, dream, introspect, summarize.

.py

mnheme_api.py

REST API FastAPI opzionale. Swagger auto-generato. CORS configurato.

.py

mnheme_benchmark.py

Suite completa: write/read/search/coldstart/scalabilità/file. Output JSON.

.env

.env.example

Template configurazione con tutti i 30+ provider pre-configurati.