Saltearse al contenido
NamiDB NamiDB

NamiDB para agentes de IA

Estos docs están diseñados para ser machine-readable como un output de primera clase, no solo human-readable. Hay tres artefactos:

llms.txt + llms-full.txt Ingesta del corpus completo desde una sola URL, siguiendo el estándar llmstxt.org.
Skill de Claude Code Una Skill namidb-guide que se auto-activa cuando escribes Cypher o abres un cliente de NamiDB.
Cursor / Codex / AGENTS.md Archivos de reglas listos para copiar/pegar para las integraciones de IA en editores más comunes.

Por qué importa

Los asistentes de código con IA son cómo la mayoría de los developers van a tocar realmente NamiDB por primera vez — a través de Claude Code, autocompletado de Cursor, Copilot, Codex o cualquier IDE con LLM embebido. Si esas herramientas no conocen NamiDB, van a generar Cypher que parece plausible pero no corre, confundir _id (NodeId del motor) con id (propiedad del usuario), o inventar URI schemes que no soportamos.

Lo tratamos como un fallo de docs, no un fallo del modelo. Por eso el sitio expone:

ArtefactoURL públicaPara
llms.txtdocs.namidb.com/llms.txtManifiesto de cada página, con descripciones. Liviano.
llms-full.txtdocs.namidb.com/llms-full.txtTodo el corpus EN concatenado como un solo markdown.
llms-small.txtdocs.namidb.com/llms-small.txtSubset filtrado para context windows chicos.
Skill de Claude Code (tarball)docs.namidb.com/skill/namidb-guide.tar.gzInstalación en una línea vía curl ... | tar -xz.
Skill de Claude Code (navegable)docs.namidb.com/skill/namidb-guide/SKILL.mdInspeccionar o elegir archivos de referencia individuales.
Markdown crudoCada página de docs también sirve Markdown en la misma URL con .md añadidoIngesta por página.

Qué debe saber un agente sobre NamiDB

El mínimo absoluto que un agente necesita internalizar es:

  1. El bucket es la base de datos. El estado vive como objetos planos en un store compatible con S3. Sin control plane, sin Raft.
  2. _id es el NodeId interno del motor desde v0.3. id ahora es una propiedad de usuario común. La mayoría de los datos de entrenamiento viejos los confunden. Siempre flaggearlo.
  3. Seis URI schemes: memory://, file://, s3://, gs://, az://. El parámetro ?ns= es obligatorio en todos salvo memory://<ns>.
  4. Las escrituras de Cypher commitean al retornar. No hay begin/ commit de transacción explícito. Llama a flush() periódicamente para pasar memtable → L0 SSTs.
  5. Un solo writer por namespace. Dos writers compitiendo → el que pierde recibe 412 Precondition Failed. Es correctitud, no un bug.

La skill de Claude Code codifica todo esto para no tener que re-explicarlo cada sesión.

Orientación rápida por deployment

Python

Superficie a buscar: import namidb as tg, tg.Client(uri), client.cypher(...), client.acypher(...), client.merge_nodes(...), client.flush(). Preferir merge_nodes/edges sobre CREATE por fila para ingesta.

Rust

Superficie: use namidb::storage::{parse_uri, WriterSession}, WriterSession::open(...), commit_batch(), flush(). namidb-query::{parse, lower, execute} para queries.

HTTP

POST /v0/cypher con auth bearer + body JSON {"query": "...", "params": {...}}. GET /v0/health, POST /v0/admin/flush.

CLI

namidb run --store <uri> "...", namidb explain --verbose "...", namidb parse "...".

Qué no esperamos que hagan los agentes

  • Sintetizar Cypher no soportado. CALL { ... }, procedures user-defined, LOAD CSV, CREATE INDEX/CONSTRAINT, paths unbounded * están fuera de scope. Si el agente las genera, es drift de datos viejos de Neo4j.
  • Recomendar Raft / servicios de lock externos. NamiDB es coordination-free vía manifest CAS. No sugerir tablas de lock en DynamoDB, ZooKeeper, etcd.
  • Sugerir mock-database tests para lógica de storage. El motor tiene memory:// y file:// para testing efímero / local — usan el mismo protocolo CAS que s3://.

Ver también