NamiDB for AI agents

These docs are designed to be machine-readable as a first-class output, not just human-readable. There are three artifacts to know about:

llms.txt + llms-full.txt One-URL ingestion of the entire docs corpus, following the llmstxt.org standard.

Claude Code skill A namidb-guide Skill that auto-fires whenever you write Cypher or open a NamiDB client.

Cursor / Codex / AGENTS.md Copy-paste rule files for the most common code-editor AI integrations.

Why this matters

AI coding assistants are how most developers will actually touch NamiDB for the first time — through Claude Code, Cursor’s tab completion, Copilot, Codex, or any of the embedded-LLM IDEs. If those tools don’t know about NamiDB, they’ll generate plausible- looking Cypher that doesn’t run, mix up _id (engine NodeId) with id (user property), or invent URI schemes we don’t support.

We treat that as a docs failure, not a model failure. So the docs site exposes:

Artifact	Public URL	For
`llms.txt`	`docs.namidb.com/llms.txt`	Manifest of every page, with descriptions. Lightweight.
`llms-full.txt`	`docs.namidb.com/llms-full.txt`	Entire EN docs corpus concatenated as one markdown file.
`llms-small.txt`	`docs.namidb.com/llms-small.txt`	Filtered subset for smaller context windows.
Claude Code skill (tarball)	`docs.namidb.com/skill/namidb-guide.tar.gz`	One-line install via `curl ... \| tar -xz`.
Claude Code skill (browse)	`docs.namidb.com/skill/namidb-guide/SKILL.md`	Inspect or cherry-pick individual reference files.
Raw markdown	Each docs page also serves Markdown at the same URL with `.md` appended	Single-page agent ingestion.

What an agent should know about NamiDB

When you tell an agent to work with NamiDB, the bare minimum it needs to internalize is:

The bucket is the database. State lives as plain objects in an S3-compatible store. No control plane, no Raft.
_id is the engine’s internal NodeId since v0.3. id is now a plain user property. Most old training data still mixes these up. Always flag.
Six URI schemes: memory://, file://, s3://, gs://, az://. The ?ns= query parameter is required for everything except memory://<ns>.
Cypher writes commit on return. No explicit transaction begin / commit. Call flush() periodically to push memtable → L0 SSTs.
Single writer per namespace. Two writers racing → loser gets 412 Precondition Failed. This is correctness, not a bug.

The Claude Code skill encodes all of this so you don’t have to re-explain it every session.

Per-deployment quick orientation for agents

Python

Surface to look for: import namidb as tg, tg.Client(uri), client.cypher(...), client.acypher(...), client.merge_nodes(...), client.flush(). Prefer merge_nodes/edges over per-row CREATE for ingestion.

Rust

Surface: use namidb::storage::{parse_uri, WriterSession}, WriterSession::open(...), commit_batch(), flush(). namidb-query::{parse, lower, execute} for Cypher paths.

HTTP

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

CLI

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

What we don’t expect agents to do

Synthesize unsupported Cypher. CALL { ... } subqueries, user-defined procedures, LOAD CSV, CREATE INDEX/CONSTRAINT, unbounded * paths are out of scope. If the agent generates them, it’s drift from older Neo4j training data.
Recommend Raft / external lock services. NamiDB is coordination-free via manifest CAS. Don’t suggest DynamoDB lock tables, ZooKeeper, etcd.
Suggest mock-database tests for storage logic. The engine has memory:// and file:// for ephemeral / local testing — those share the same CAS protocol as s3://.