mnemonexus 0.2.0

Cliente Python para mnemonexus — memória pra agentes de IA, open source, em português.

mnemonexus

Cliente Python oficial para o mnemonexus — memória pra agentes de IA, open source, em português.

Paridade com mem0 nas operações CRUD, mais o diferencial: compilação Karpathy, twice-rule pra lessons, grafo de entidades, staleness/supersede automáticos.

Instalação

pip install mnemonexus

Uso

from mnemonexus import Nexus

nexus = Nexus(api_url="http://localhost:8080", token="seu-token-sanctum")

# Paridade mem0
nexus.add("Reunião terça 14h", domain="memory")
result = nexus.search("quando é a reunião?")
print(result.answer)

# Twice rule — lesson aprendida
nexus.lesson(
    title="Sempre validar embedding dim antes de inserir em pgvector",
    body="Dim 1536 ≠ 1024 → INSERT explode silenciosamente",
    severity="critical",
)

# Decision com rationale
nexus.decision(
    title="Adotar pgvector em vez de Weaviate",
    description="Reduz containers; busca híbrida fica dentro de Eloquent",
    category="architecture",
)

# Grafo de entidades
graph = nexus.entity("foxpulse").graph()
for edge in graph.edges:
    print(edge.from_entity_slug, "→", edge.kind, "→", edge.to_entity_slug)

# Async também (recomendado em apps async)
import asyncio
from mnemonexus import AsyncNexus

async def main():
    async with AsyncNexus(token="...") as nexus:
        await nexus.add("…")
        r = await nexus.search("…")
asyncio.run(main())

API resumida

Paridade mem0

Método	Endpoint	O que faz
add(content, **)	POST /ingest	Adiciona memória
search(query, **)	POST /query	Recall híbrido (FTS + vetor)
get(slug)	GET /pages/{slug}	Lê página
update(slug, content)	PUT /pages/{slug}	Supersede
delete(slug)	DELETE /pages/{slug}	Hard delete
history(slug)	GET /pages/{slug}	Cadeia de versões

Diferencial mnemonexus

Método	Endpoint	O que faz
compile(slug)	POST /pages/{slug}/compile	Recompila wiki page
extract_facts(text)	POST /facts/extract	Facts + entidades + relações
lesson(title, body)	POST /lessons	Lesson com twice-rule
decision(title, description)	POST /decisions	Decisão com rationale
compact_session(id)	PUT /sessions/{id}	Fecha + sumariza sessão
entity(slug).graph()	GET /entities/{slug}/graph	Grafo BFS da entidade
search_entity(q)	GET /entities	Busca grafo de entidades

Errors

NexusError é a base. Subclasses:

• AuthError — 401/403
• NotFoundError — 404
• ValidationError — 422

Cookbook

Veja examples/:

1. 01_hello_world.py — add + search
2. 02_with_karpathy.py — wiki compilada
3. 03_with_lessons.py — twice rule
4. 04_multi_tenant.py — isolamento por agent_id/tenant
5. 05_rag_over_wiki.py — RAG com histórico

Dev

git clone https://github.com/lrdeoliveira/mnemonexus-python
cd mnemonexus-python
pip install -e ".[dev]"
pytest

Licença

MIT.