--- name: aerospike description: Work with the Aerospike core database end to end — run a local instance with Docker and verify a first write and read, build or review client code with the official SDKs (Python, Node.js, Go, Java, C#), and design or review a data model, whether from requirements or against a schema that already exists. Covers namespaces, sets, bins, primary key design, TTL and NSUP, collection data types, expressions, secondary indexes, batch and scan workflows, client policies, connection pooling, record sizing, and schema deliverables. Use when the user sets up Aerospike, writes or debugs Aerospike client code, chooses keys or models data for it, reviews an Aerospike schema before building, or evaluates it as a persistent replacement for Redis or Memcached in real-time, low-latency, feature-store, or user-profile workloads. Core database only — not Aerospike Graph, and not cluster operations, sizing, XDR, or backup and restore, which belong to Aerospike Operations documentation. license: Apache-2.0 metadata: last_verified: "2026-04-21" server_versions: "7.0+" ---

_Auto-generated from `skills/aerospike-getting-started`, `skills/aerospike-development`, `skills/aerospike-data-modeling` in https://github.com/aerospike/agent-skills. Rule files cited below by bare filename live under `skills/<skill>/` or its `references/` folder in that repository. Edit the skills under `skills/`, not this file._

# Aerospike agent rules

## aerospike-getting-started

### 1. Critical rules (anti-hallucination) - Docker image: Default to aerospike/aerospike-server (Community Edition). Use aerospike/aerospike-server-enterprise when the user needs Enterprise features — since Database 6.1.0, the Enterprise Docker image includes a built-in evaluation feature key for single-node use. - Ports: Always map the core service ports: -p 3000-3002:3000-3002. Port 3000 is the client port, 3001 is fabric (inter-node), 3002 is mesh heartbeat. Port 3003: on Database 8.1.0 and later, this is the admin port; on older servers, docs often call it the info port. Add -p 3003:3003 when the user needs admin or legacy info access. Do not confuse these ports with HTTP or generic app ports like 8080. - Default namespace: The default namespace is test. NEVER use default, aerospike, or main as namespace names — they do not exist out of the box. - Default set: Sets are created dynamically on first write. No pre-creation needed. - Connection defaults: Host 127.0.0.1, port 3000 for local Docker deployments. - Config file path: Inside the container, the config lives at /etc/aerospike/aerospike.conf. When mounting a custom config, mount to /opt/aerospike/etc/aerospike.conf and pass --config-file /opt/aerospike/etc/aerospike.conf. - TTL requires nsup-period: By default, namespaces reject writes with a TTL, and NSUP does not run, but this behavior is configurable. nsup-period controls how often NSUP runs, and the default value 0 means NSUP does not run. If the user wants expiring records, configure nsup-period to a value greater than 0 (for example nsup-period 10) so NSUP runs and checks for expired records. When nsup-period is 0, writes with a positive integer TTL require allow-ttl-without-nsup true, which Aerospike documents as a testing-only setting. - Key storage policy: The Aerospike client docs describe the send-key policy this way: it stores the user defined key with the record, and returns it with read commands. The default Node.js key read policy is Aerospike.policy.key.DIGEST. If the user needs the user defined key returned with reads, set the write policy to send/store the key when writing records (for example, key: Aerospike.policy.key.SEND in Node.js, key: aerospike.POLICY_KEY_SEND in Python, or policy.SendKey = true in Go). - No auth by default: Community Edition has no authentication. Do not generate username/password connection code unless the user is on Enterprise Edition. - Data model terminology: Aerospike uses "namespace" (like a database), "set" (like a table), "record" (like a row), "bin" (like a column). Never use incorrect analogies.

### 2. Hallucination blacklist (never use these) - Wrong: aerospike/aerospike-server-enterprise when the user only needs Community features — Use: aerospike/aerospike-server for Community; Enterprise includes a built-in evaluation key but is a larger image. - Wrong: Namespace default or aerospike — Use: test. - Wrong: Port 8080 for Aerospike — Use: 3000-3002 for client/fabric/heartbeat; 3003 for admin (Database 8.1.0+, often described as info on older versions). - Wrong: client.connect() as a required separate call in Python — aerospike.client(config) connects on instantiation. .connect() exists but is a no-op on a fresh client; it is only needed to reconnect after client.close(). - Wrong: aerospike.Client() or aerospike.client.Client() in Python — Use: the factory function aerospike.client({...}). - Wrong: require('aerospike-client') in Node.js — Use: require('aerospike'). - Wrong: Setting a positive integer TTL while nsup-period is 0, unless allow-ttl-without-nsup is explicitly enabled for testing. - Wrong: Any REST API endpoints — Aerospike uses a binary wire protocol via client SDKs, not HTTP. - Wrong: CREATE NAMESPACE or CREATE SET SQL-like commands — namespaces are defined in config; sets are auto-created.

### 3. Concept mapping - "real-time database" / "low-latency store" / "fast database" → Docker quick setup with in-memory storage - "cache replacement" / "replace Redis" / "replace Memcached" → In-memory namespace, emphasize sub-ms latency and clustering - "persistent storage" / "durable database" → File-backed or device-backed namespace config (see reference.md) - "production deployment" / "cloud deployment" → Official docs only; use Choose a path first path 1 - "time-series" / "TTL" / "expiring data" → default-ttl namespace config and per-record TTL in write policy - "transactions" / "ACID" → Strong consistency mode (Enterprise feature) or record-level atomicity (Community)

## aerospike-development

### Client best practices (enforce in generated or reviewed code) - Singleton client: One AerospikeClient (or language equivalent) per process; it is thread-safe and holds pools and cluster state. Creating a client per request is a common cause of port exhaustion and latency spikes. - Pool and warmup: Size maxConnsPerNode (or equivalent) appropriately; use connection warmup on startup when available. - Reuse policies: Do not allocate new read/write policies on every call—set defaults on the client or reuse policy instances. - Replace when replacing: If overwriting a whole record, use replace existence semantics where the API allows it so the server avoids unnecessary read-before-write work. - Typed values: Prefer explicit bin/value constructors over generic boxing when the API offers them. - Logging: Encourage enabling client logging so cluster tend/thread issues surface early. - Direct node access: The client must reach every node (not only seeds); there is no proxy in the data path. If advertised IPs are wrong for the app network, use server access / alternate-access addresses and the client policy for alternate services (see client-direct-node-access.md).

### Common pitfalls - Load balancer or proxy only to seeds; app cannot reach all node addresses -> Clients need direct TCP to every node; use access-address / alternate-access-address (and client useServicesAlternate when needed)—not a proxy in the data path; see client-direct-node-access.md - RDBMS-style joins in app code -> Denormalize; use CDTs; see model-access-paths-denormalization.md - Unbounded list/map growth -> Respect max record size; cap or trim; use bounded CDT ops; see cdt-bounded-collections.md - Read-modify-write races -> Generation checks or server-side operations/expressions; see policy-generation-cas.md, expr-compute-to-data.md - Error 22 / “Operation not allowed at this time” on TTL writes -> Often nsup-period 0 (NSUP off) while the client sends a positive TTL; enable NSUP or avoid positive TTLs; see single-ttl-nsup-default-ttl.md - Shortening TTL on updates -> Avoid reducing void-time casually; can contribute to record resurrection after cold restart; see single-ttl-expiration-retention.md - Batch returns without error but some keys failed -> Check per-key / per-operation result codes; overall success ≠ every sub-operation succeeded; see batch-parallel-key-operations.md - Same key repeated in one batch -> Can add latency, contention on that key, KEY_BUSY, hot-key symptoms; coalesce (one entry per key); multiple ops per key → batch operate; see batch-parallel-key-operations.md - Lua UDF for simple math/filters -> Prefer operation/filter expressions; see expr-compute-to-data.md

### Rule set - client- -> Connection lifecycle, pools, warmup, tend, error-rate backoff, direct node reachability - policy- -> Timeouts/retries, client-level defaults, replica & AP/SC read modes, sendKey, commit level, generation/CAS, replace - cdt- -> Lists/maps, nesting (K-order, context), growth limits, server-side collection ops - expr- -> Filter/operation/path expressions vs heavier alternatives - query- -> Secondary indexes, cardinality/cost, and deriving index needs from access paths - batch- -> Many primary-key reads/writes; one key per batch entry, coalesce, batch operate - binop- -> operate, one record lock, mixed read/write, atomic multi-bin updates - single- -> Whole-record vs partial/bin operations; TTL void-time and NSUP/default-ttl; delete and durable deletes (EE) - model- -> Namespace and set boundaries; flat bins vs CDTs vs multiple records; keys, denormalization, access paths; operate / batch / expressions; record size vs index RAM and disk; hot keys and error 14 / KEY_BUSY - sec- -> TLS and access control on the client

### Use batch APIs for many primary-key operations [MEDIUM] - When reading or writing many records by known primary keys, use the client’s batch APIs instead of serial single-key calls, subject to reasonable batch sizes and error-handling needs. - Prefer: Chunked batches if the SDK or service limits batch size; One entry per key per batch; merge or drop duplicates on the client before batch_*; Batch operate (or equivalent) when one key needs multiple operations atomically in the batch; After each batch: walk every entry’s result code or exception slot—partial success is normal for batch APIs; Retrying or compensating only for keys that actually failed (once you have per-key status) - Avoid: Thousands of sequential gets when a batch interface exists; Duplicate keys in the same batch when you can coalesce or combine into operate—especially on keys that are already hot or latency-sensitive; Assuming no exception or overall OK means every key in the batch succeeded

### Use operate for multi-bin atomic updates on one key [HIGH] - When a single logical update touches multiple bins or uses CDT ops on one record, use operate (multi-operation) so the server applies the sequence atomically for that record, rather than separate put/get cycles that can interleave with other writers. - Prefer: One operate call combining the bin ops you need; Generations when you need compare-and-swap across clients - Avoid: Multiple independent puts racing without coordination; Mixing a whole-record read with bin-scoped ops in one operate (use per-bin reads only; see binop-operate-record-lock-read-write.md)

### Use operate for one record lock, many ops, and mixed reads and writes [HIGH] - Use the operate command when you need multiple bin-level changes on the same record key in one server round trip. The server acquires a record lock, runs an ordered list of bin operations atomically and in isolation against an in-memory copy of the record, then persists if any write occurred. Mix read and write operations in the same operate call when you need updated values back without a separate get: later operations see the effects of earlier ones in the list (including writes before reads). This cut

--- name: aerospike description: Work with the Aerospike core database end to end — run a local instance with Docker and verify a first write and read, build or review client code with the official SDKs (Python, Node.js, Go, Java, C#), and design or review a data model, whether from requirements or against a schema that already exists. Covers namespaces, sets, bins, primary key design, TTL and NSUP, collection data types, expressions, secondary indexes, batch and scan workflows, client policies, connection pooling, record sizing, and schema deliverables. Use when the user sets up Aerospike, writes or debugs Aerospike client code, chooses keys or models data for it, reviews an Aerospike schema before building, or evaluates it as a persistent replacement for Redis or Memcached in real-time, low-latency, feature-store, or user-profile workloads. Core database only — not Aerospike Graph, and not cluster operations, sizing, XDR, or backup and restore, which belong to Aerospike Operations documentation. license: Apache-2.0 metadata: last_verified: "2026-04-21" server_versions: "7.0+" ---

_Auto-generated from `skills/aerospike-getting-started`, `skills/aerospike-development`, `skills/aerospike-data-modeling` in https://github.com/aerospike/agent-skills. Rule files cited below by bare filename live under `skills/<skill>/` or its `references/` folder in that repository. Edit the skills under `skills/`, not this file._

# Aerospike agent rules

## aerospike-getting-started

### 1. Critical rules (anti-hallucination) - Docker image: Default to aerospike/aerospike-server (Community Edition). Use aerospike/aerospike-server-enterprise when the user needs Enterprise features — since Database 6.1.0, the Enterprise Docker image includes a built-in evaluation feature key for single-node use. - Ports: Always map the core service ports: -p 3000-3002:3000-3002. Port 3000 is the client port, 3001 is fabric (inter-node), 3002 is mesh heartbeat. Port 3003: on Database 8.1.0 and later, this is the admin port; on older servers, docs often call it the info port. Add -p 3003:3003 when the user needs admin or legacy info access. Do not confuse these ports with HTTP or generic app ports like 8080. - Default namespace: The default namespace is test. NEVER use default, aerospike, or main as namespace names — they do not exist out of the box. - Default set: Sets are created dynamically on first write. No pre-creation needed. - Connection defaults: Host 127.0.0.1, port 3000 for local Docker deployments. - Config file path: Inside the container, the config lives at /etc/aerospike/aerospike.conf. When mounting a custom config, mount to /opt/aerospike/etc/aerospike.conf and pass --config-file /opt/aerospike/etc/aerospike.conf. - TTL requires nsup-period: By default, namespaces reject writes with a TTL, and NSUP does not run, but this behavior is configurable. nsup-period controls how often NSUP runs, and the default value 0 means NSUP does not run. If the user wants expiring records, configure nsup-period to a value greater than 0 (for example nsup-period 10) so NSUP runs and checks for expired records. When nsup-period is 0, writes with a positive integer TTL require allow-ttl-without-nsup true, which Aerospike documents as a testing-only setting. - Key storage policy: The Aerospike client docs describe the send-key policy this way: it stores the user defined key with the record, and returns it with read commands. The default Node.js key read policy is Aerospike.policy.key.DIGEST. If the user needs the user defined key returned with reads, set the write policy to send/store the key when writing records (for example, key: Aerospike.policy.key.SEND in Node.js, key: aerospike.POLICY_KEY_SEND in Python, or policy.SendKey = true in Go). - No auth by default: Community Edition has no authentication. Do not generate username/password connection code unless the user is on Enterprise Edition. - Data model terminology: Aerospike uses "namespace" (like a database), "set" (like a table), "record" (like a row), "bin" (like a column). Never use incorrect analogies.

### 2. Hallucination blacklist (never use these) - Wrong: aerospike/aerospike-server-enterprise when the user only needs Community features — Use: aerospike/aerospike-server for Community; Enterprise includes a built-in evaluation key but is a larger image. - Wrong: Namespace default or aerospike — Use: test. - Wrong: Port 8080 for Aerospike — Use: 3000-3002 for client/fabric/heartbeat; 3003 for admin (Database 8.1.0+, often described as info on older versions). - Wrong: client.connect() as a required separate call in Python — aerospike.client(config) connects on instantiation. .connect() exists but is a no-op on a fresh client; it is only needed to reconnect after client.close(). - Wrong: aerospike.Client() or aerospike.client.Client() in Python — Use: the factory function aerospike.client({...}). - Wrong: require('aerospike-client') in Node.js — Use: require('aerospike'). - Wrong: Setting a positive integer TTL while nsup-period is 0, unless allow-ttl-without-nsup is explicitly enabled for testing. - Wrong: Any REST API endpoints — Aerospike uses a binary wire protocol via client SDKs, not HTTP. - Wrong: CREATE NAMESPACE or CREATE SET SQL-like commands — namespaces are defined in config; sets are auto-created.

### 3. Concept mapping - "real-time database" / "low-latency store" / "fast database" → Docker quick setup with in-memory storage - "cache replacement" / "replace Redis" / "replace Memcached" → In-memory namespace, emphasize sub-ms latency and clustering - "persistent storage" / "durable database" → File-backed or device-backed namespace config (see reference.md) - "production deployment" / "cloud deployment" → Official docs only; use Choose a path first path 1 - "time-series" / "TTL" / "expiring data" → default-ttl namespace config and per-record TTL in write policy - "transactions" / "ACID" → Strong consistency mode (Enterprise feature) or record-level atomicity (Community)

## aerospike-development

### Client best practices (enforce in generated or reviewed code) - Singleton client: One AerospikeClient (or language equivalent) per process; it is thread-safe and holds pools and cluster state. Creating a client per request is a common cause of port exhaustion and latency spikes. - Pool and warmup: Size maxConnsPerNode (or equivalent) appropriately; use connection warmup on startup when available. - Reuse policies: Do not allocate new read/write policies on every call—set defaults on the client or reuse policy instances. - Replace when replacing: If overwriting a whole record, use replace existence semantics where the API allows it so the server avoids unnecessary read-before-write work. - Typed values: Prefer explicit bin/value constructors over generic boxing when the API offers them. - Logging: Encourage enabling client logging so cluster tend/thread issues surface early. - Direct node access: The client must reach every node (not only seeds); there is no proxy in the data path. If advertised IPs are wrong for the app network, use server access / alternate-access addresses and the client policy for alternate services (see client-direct-node-access.md).

### Common pitfalls - Load balancer or proxy only to seeds; app cannot reach all node addresses -> Clients need direct TCP to every node; use access-address / alternate-access-address (and client useServicesAlternate when needed)—not a proxy in the data path; see client-direct-node-access.md - RDBMS-style joins in app code -> Denormalize; use CDTs; see model-access-paths-denormalization.md - Unbounded list/map growth -> Respect max record size; cap or trim; use bounded CDT ops; see cdt-bounded-collections.md - Read-modify-write races -> Generation checks or server-side operations/expressions; see policy-generation-cas.md, expr-compute-to-data.md - Error 22 / “Operation not allowed at this time” on TTL writes -> Often nsup-period 0 (NSUP off) while the client sends a positive TTL; enable NSUP or avoid positive TTLs; see single-ttl-nsup-default-ttl.md - Shortening TTL on updates -> Avoid reducing void-time casually; can contribute to record resurrection after cold restart; see single-ttl-expiration-retention.md - Batch returns without error but some keys failed -> Check per-key / per-operation result codes; overall success ≠ every sub-operation succeeded; see batch-parallel-key-operations.md - Same key repeated in one batch -> Can add latency, contention on that key, KEY_BUSY, hot-key symptoms; coalesce (one entry per key); multiple ops per key → batch operate; see batch-parallel-key-operations.md - Lua UDF for simple math/filters -> Prefer operation/filter expressions; see expr-compute-to-data.md

### Rule set - client- -> Connection lifecycle, pools, warmup, tend, error-rate backoff, direct node reachability - policy- -> Timeouts/retries, client-level defaults, replica & AP/SC read modes, sendKey, commit level, generation/CAS, replace - cdt- -> Lists/maps, nesting (K-order, context), growth limits, server-side collection ops - expr- -> Filter/operation/path expressions vs heavier alternatives - query- -> Secondary indexes, cardinality/cost, and deriving index needs from access paths - batch- -> Many primary-key reads/writes; one key per batch entry, coalesce, batch operate - binop- -> operate, one record lock, mixed read/write, atomic multi-bin updates - single- -> Whole-record vs partial/bin operations; TTL void-time and NSUP/default-ttl; delete and durable deletes (EE) - model- -> Namespace and set boundaries; flat bins vs CDTs vs multiple records; keys, denormalization, access paths; operate / batch / expressions; record size vs index RAM and disk; hot keys and error 14 / KEY_BUSY - sec- -> TLS and access control on the client

### Use batch APIs for many primary-key operations [MEDIUM] - When reading or writing many records by known primary keys, use the client’s batch APIs instead of serial single-key calls, subject to reasonable batch sizes and error-handling needs. - Prefer: Chunked batches if the SDK or service limits batch size; One entry per key per batch; merge or drop duplicates on the client before batch_*; Batch operate (or equivalent) when one key needs multiple operations atomically in the batch; After each batch: walk every entry’s result code or exception slot—partial success is normal for batch APIs; Retrying or compensating only for keys that actually failed (once you have per-key status) - Avoid: Thousands of sequential gets when a batch interface exists; Duplicate keys in the same batch when you can coalesce or combine into operate—especially on keys that are already hot or latency-sensitive; Assuming no exception or overall OK means every key in the batch succeeded

### Use operate for multi-bin atomic updates on one key [HIGH] - When a single logical update touches multiple bins or uses CDT ops on one record, use operate (multi-operation) so the server applies the sequence atomically for that record, rather than separate put/get cycles that can interleave with other writers. - Prefer: One operate call combining the bin ops you need; Generations when you need compare-and-swap across clients - Avoid: Multiple independent puts racing without coordination; Mixing a whole-record read with bin-scoped ops in one operate (use per-bin reads only; see binop-operate-record-lock-read-write.md)

### Use operate for one record lock, many ops, and mixed reads and writes [HIGH] - Use the operate command when you need multiple bin-level changes on the same record key in one server round trip. The server acquires a record lock, runs an ordered list of bin operations atomically and in isolation against an in-memory copy of the record, then persists if any write occurred. Mix read and write operations in the same operate call when you need updated values back without a separate get: later operations see the effects of earlier ones in the list (including writes before reads). This cut

--- name: aerospike description: Work with the Aerospike core database end to end — run a local instance with Docker and verify a first write and read, build or review client code with the official SDKs (Python, Node.js, Go, Java, C#), and design or review a data model, whether from requirements or against a schema that already exists. Covers namespaces, sets, bins, primary key design, TTL and NSUP, collection data types, expressions, secondary indexes, batch and scan workflows, client policies, connection pooling, record sizing, and schema deliverables. Use when the user sets up Aerospike, writes or debugs Aerospike client code, chooses keys or models data for it, reviews an Aerospike schema before building, or evaluates it as a persistent replacement for Redis or Memcached in real-time, low-latency, feature-store, or user-profile workloads. Core database only — not Aerospike Graph, and not cluster operations, sizing, XDR, or backup and restore, which belong to Aerospike Operations documentation. license: Apache-2.0 metadata: last_verified: "2026-04-21" server_versions: "7.0+" ---

_Auto-generated from `skills/aerospike-getting-started`, `skills/aerospike-development`, `skills/aerospike-data-modeling` in https://github.com/aerospike/agent-skills. Rule files cited below by bare filename live under `skills/<skill>/` or its `references/` folder in that repository. Edit the skills under `skills/`, not this file._

# Aerospike agent rules

## aerospike-getting-started

### 1. Critical rules (anti-hallucination) - Docker image: Default to aerospike/aerospike-server (Community Edition). Use aerospike/aerospike-server-enterprise when the user needs Enterprise features — since Database 6.1.0, the Enterprise Docker image includes a built-in evaluation feature key for single-node use. - Ports: Always map the core service ports: -p 3000-3002:3000-3002. Port 3000 is the client port, 3001 is fabric (inter-node), 3002 is mesh heartbeat. Port 3003: on Database 8.1.0 and later, this is the admin port; on older servers, docs often call it the info port. Add -p 3003:3003 when the user needs admin or legacy info access. Do not confuse these ports with HTTP or generic app ports like 8080. - Default namespace: The default namespace is test. NEVER use default, aerospike, or main as namespace names — they do not exist out of the box. - Default set: Sets are created dynamically on first write. No pre-creation needed. - Connection defaults: Host 127.0.0.1, port 3000 for local Docker deployments. - Config file path: Inside the container, the config lives at /etc/aerospike/aerospike.conf. When mounting a custom config, mount to /opt/aerospike/etc/aerospike.conf and pass --config-file /opt/aerospike/etc/aerospike.conf. - TTL requires nsup-period: By default, namespaces reject writes with a TTL, and NSUP does not run, but this behavior is configurable. nsup-period controls how often NSUP runs, and the default value 0 means NSUP does not run. If the user wants expiring records, configure nsup-period to a value greater than 0 (for example nsup-period 10) so NSUP runs and checks for expired records. When nsup-period is 0, writes with a positive integer TTL require allow-ttl-without-nsup true, which Aerospike documents as a testing-only setting. - Key storage policy: The Aerospike client docs describe the send-key policy this way: it stores the user defined key with the record, and returns it with read commands. The default Node.js key read policy is Aerospike.policy.key.DIGEST. If the user needs the user defined key returned with reads, set the write policy to send/store the key when writing records (for example, key: Aerospike.policy.key.SEND in Node.js, key: aerospike.POLICY_KEY_SEND in Python, or policy.SendKey = true in Go). - No auth by default: Community Edition has no authentication. Do not generate username/password connection code unless the user is on Enterprise Edition. - Data model terminology: Aerospike uses "namespace" (like a database), "set" (like a table), "record" (like a row), "bin" (like a column). Never use incorrect analogies.

### 2. Hallucination blacklist (never use these) - Wrong: aerospike/aerospike-server-enterprise when the user only needs Community features — Use: aerospike/aerospike-server for Community; Enterprise includes a built-in evaluation key but is a larger image. - Wrong: Namespace default or aerospike — Use: test. - Wrong: Port 8080 for Aerospike — Use: 3000-3002 for client/fabric/heartbeat; 3003 for admin (Database 8.1.0+, often described as info on older versions). - Wrong: client.connect() as a required separate call in Python — aerospike.client(config) connects on instantiation. .connect() exists but is a no-op on a fresh client; it is only needed to reconnect after client.close(). - Wrong: aerospike.Client() or aerospike.client.Client() in Python — Use: the factory function aerospike.client({...}). - Wrong: require('aerospike-client') in Node.js — Use: require('aerospike'). - Wrong: Setting a positive integer TTL while nsup-period is 0, unless allow-ttl-without-nsup is explicitly enabled for testing. - Wrong: Any REST API endpoints — Aerospike uses a binary wire protocol via client SDKs, not HTTP. - Wrong: CREATE NAMESPACE or CREATE SET SQL-like commands — namespaces are defined in config; sets are auto-created.

### 3. Concept mapping - "real-time database" / "low-latency store" / "fast database" → Docker quick setup with in-memory storage - "cache replacement" / "replace Redis" / "replace Memcached" → In-memory namespace, emphasize sub-ms latency and clustering - "persistent storage" / "durable database" → File-backed or device-backed namespace config (see reference.md) - "production deployment" / "cloud deployment" → Official docs only; use Choose a path first path 1 - "time-series" / "TTL" / "expiring data" → default-ttl namespace config and per-record TTL in write policy - "transactions" / "ACID" → Strong consistency mode (Enterprise feature) or record-level atomicity (Community)

## aerospike-development

### Client best practices (enforce in generated or reviewed code) - Singleton client: One AerospikeClient (or language equivalent) per process; it is thread-safe and holds pools and cluster state. Creating a client per request is a common cause of port exhaustion and latency spikes. - Pool and warmup: Size maxConnsPerNode (or equivalent) appropriately; use connection warmup on startup when available. - Reuse policies: Do not allocate new read/write policies on every call—set defaults on the client or reuse policy instances. - Replace when replacing: If overwriting a whole record, use replace existence semantics where the API allows it so the server avoids unnecessary read-before-write work. - Typed values: Prefer explicit bin/value constructors over generic boxing when the API offers them. - Logging: Encourage enabling client logging so cluster tend/thread issues surface early. - Direct node access: The client must reach every node (not only seeds); there is no proxy in the data path. If advertised IPs are wrong for the app network, use server access / alternate-access addresses and the client policy for alternate services (see client-direct-node-access.md).

### Common pitfalls - Load balancer or proxy only to seeds; app cannot reach all node addresses -> Clients need direct TCP to every node; use access-address / alternate-access-address (and client useServicesAlternate when needed)—not a proxy in the data path; see client-direct-node-access.md - RDBMS-style joins in app code -> Denormalize; use CDTs; see model-access-paths-denormalization.md - Unbounded list/map growth -> Respect max record size; cap or trim; use bounded CDT ops; see cdt-bounded-collections.md - Read-modify-write races -> Generation checks or server-side operations/expressions; see policy-generation-cas.md, expr-compute-to-data.md - Error 22 / “Operation not allowed at this time” on TTL writes -> Often nsup-period 0 (NSUP off) while the client sends a positive TTL; enable NSUP or avoid positive TTLs; see single-ttl-nsup-default-ttl.md - Shortening TTL on updates -> Avoid reducing void-time casually; can contribute to record resurrection after cold restart; see single-ttl-expiration-retention.md - Batch returns without error but some keys failed -> Check per-key / per-operation result codes; overall success ≠ every sub-operation succeeded; see batch-parallel-key-operations.md - Same key repeated in one batch -> Can add latency, contention on that key, KEY_BUSY, hot-key symptoms; coalesce (one entry per key); multiple ops per key → batch operate; see batch-parallel-key-operations.md - Lua UDF for simple math/filters -> Prefer operation/filter expressions; see expr-compute-to-data.md

### Rule set - client- -> Connection lifecycle, pools, warmup, tend, error-rate backoff, direct node reachability - policy- -> Timeouts/retries, client-level defaults, replica & AP/SC read modes, sendKey, commit level, generation/CAS, replace - cdt- -> Lists/maps, nesting (K-order, context), growth limits, server-side collection ops - expr- -> Filter/operation/path expressions vs heavier alternatives - query- -> Secondary indexes, cardinality/cost, and deriving index needs from access paths - batch- -> Many primary-key reads/writes; one key per batch entry, coalesce, batch operate - binop- -> operate, one record lock, mixed read/write, atomic multi-bin updates - single- -> Whole-record vs partial/bin operations; TTL void-time and NSUP/default-ttl; delete and durable deletes (EE) - model- -> Namespace and set boundaries; flat bins vs CDTs vs multiple records; keys, denormalization, access paths; operate / batch / expressions; record size vs index RAM and disk; hot keys and error 14 / KEY_BUSY - sec- -> TLS and access control on the client

### Use batch APIs for many primary-key operations [MEDIUM] - When reading or writing many records by known primary keys, use the client’s batch APIs instead of serial single-key calls, subject to reasonable batch sizes and error-handling needs. - Prefer: Chunked batches if the SDK or service limits batch size; One entry per key per batch; merge or drop duplicates on the client before batch_*; Batch operate (or equivalent) when one key needs multiple operations atomically in the batch; After each batch: walk every entry’s result code or exception slot—partial success is normal for batch APIs; Retrying or compensating only for keys that actually failed (once you have per-key status) - Avoid: Thousands of sequential gets when a batch interface exists; Duplicate keys in the same batch when you can coalesce or combine into operate—especially on keys that are already hot or latency-sensitive; Assuming no exception or overall OK means every key in the batch succeeded

### Use operate for multi-bin atomic updates on one key [HIGH] - When a single logical update touches multiple bins or uses CDT ops on one record, use operate (multi-operation) so the server applies the sequence atomically for that record, rather than separate put/get cycles that can interleave with other writers. - Prefer: One operate call combining the bin ops you need; Generations when you need compare-and-swap across clients - Avoid: Multiple independent puts racing without coordination; Mixing a whole-record read with bin-scoped ops in one operate (use per-bin reads only; see binop-operate-record-lock-read-write.md)

### Use operate for one record lock, many ops, and mixed reads and writes [HIGH] - Use the operate command when you need multiple bin-level changes on the same record key in one server round trip. The server acquires a record lock, runs an ordered list of bin operations atomically and in isolation against an in-memory copy of the record, then persists if any write occurred. Mix read and write operations in the same operate call when you need updated values back without a separate get: later operations see the effects of earlier ones in the list (including writes before reads). This cut

--- name: aerospike description: Work with the Aerospike core database end to end — run a local instance with Docker and verify a first write and read, build or review client code with the official SDKs (Python, Node.js, Go, Java, C#), and design or review a data model, whether from requirements or against a schema that already exists. Covers namespaces, sets, bins, primary key design, TTL and NSUP, collection data types, expressions, secondary indexes, batch and scan workflows, client policies, connection pooling, record sizing, and schema deliverables. Use when the user sets up Aerospike, writes or debugs Aerospike client code, chooses keys or models data for it, reviews an Aerospike schema before building, or evaluates it as a persistent replacement for Redis or Memcached in real-time, low-latency, feature-store, or user-profile workloads. Core database only — not Aerospike Graph, and not cluster operations, sizing, XDR, or backup and restore, which belong to Aerospike Operations documentation. license: Apache-2.0 metadata: last_verified: "2026-04-21" server_versions: "7.0+" ---

_Auto-generated from `skills/aerospike-getting-started`, `skills/aerospike-development`, `skills/aerospike-data-modeling` in https://github.com/aerospike/agent-skills. Rule files cited below by bare filename live under `skills/<skill>/` or its `references/` folder in that repository. Edit the skills under `skills/`, not this file._

# Aerospike agent rules

## aerospike-getting-started

### 1. Critical rules (anti-hallucination) - Docker image: Default to aerospike/aerospike-server (Community Edition). Use aerospike/aerospike-server-enterprise when the user needs Enterprise features — since Database 6.1.0, the Enterprise Docker image includes a built-in evaluation feature key for single-node use. - Ports: Always map the core service ports: -p 3000-3002:3000-3002. Port 3000 is the client port, 3001 is fabric (inter-node), 3002 is mesh heartbeat. Port 3003: on Database 8.1.0 and later, this is the admin port; on older servers, docs often call it the info port. Add -p 3003:3003 when the user needs admin or legacy info access. Do not confuse these ports with HTTP or generic app ports like 8080. - Default namespace: The default namespace is test. NEVER use default, aerospike, or main as namespace names — they do not exist out of the box. - Default set: Sets are created dynamically on first write. No pre-creation needed. - Connection defaults: Host 127.0.0.1, port 3000 for local Docker deployments. - Config file path: Inside the container, the config lives at /etc/aerospike/aerospike.conf. When mounting a custom config, mount to /opt/aerospike/etc/aerospike.conf and pass --config-file /opt/aerospike/etc/aerospike.conf. - TTL requires nsup-period: By default, namespaces reject writes with a TTL, and NSUP does not run, but this behavior is configurable. nsup-period controls how often NSUP runs, and the default value 0 means NSUP does not run. If the user wants expiring records, configure nsup-period to a value greater than 0 (for example nsup-period 10) so NSUP runs and checks for expired records. When nsup-period is 0, writes with a positive integer TTL require allow-ttl-without-nsup true, which Aerospike documents as a testing-only setting. - Key storage policy: The Aerospike client docs describe the send-key policy this way: it stores the user defined key with the record, and returns it with read commands. The default Node.js key read policy is Aerospike.policy.key.DIGEST. If the user needs the user defined key returned with reads, set the write policy to send/store the key when writing records (for example, key: Aerospike.policy.key.SEND in Node.js, key: aerospike.POLICY_KEY_SEND in Python, or policy.SendKey = true in Go). - No auth by default: Community Edition has no authentication. Do not generate username/password connection code unless the user is on Enterprise Edition. - Data model terminology: Aerospike uses "namespace" (like a database), "set" (like a table), "record" (like a row), "bin" (like a column). Never use incorrect analogies.

### 2. Hallucination blacklist (never use these) - Wrong: aerospike/aerospike-server-enterprise when the user only needs Community features — Use: aerospike/aerospike-server for Community; Enterprise includes a built-in evaluation key but is a larger image. - Wrong: Namespace default or aerospike — Use: test. - Wrong: Port 8080 for Aerospike — Use: 3000-3002 for client/fabric/heartbeat; 3003 for admin (Database 8.1.0+, often described as info on older versions). - Wrong: client.connect() as a required separate call in Python — aerospike.client(config) connects on instantiation. .connect() exists but is a no-op on a fresh client; it is only needed to reconnect after client.close(). - Wrong: aerospike.Client() or aerospike.client.Client() in Python — Use: the factory function aerospike.client({...}). - Wrong: require('aerospike-client') in Node.js — Use: require('aerospike'). - Wrong: Setting a positive integer TTL while nsup-period is 0, unless allow-ttl-without-nsup is explicitly enabled for testing. - Wrong: Any REST API endpoints — Aerospike uses a binary wire protocol via client SDKs, not HTTP. - Wrong: CREATE NAMESPACE or CREATE SET SQL-like commands — namespaces are defined in config; sets are auto-created.

### 3. Concept mapping - "real-time database" / "low-latency store" / "fast database" → Docker quick setup with in-memory storage - "cache replacement" / "replace Redis" / "replace Memcached" → In-memory namespace, emphasize sub-ms latency and clustering - "persistent storage" / "durable database" → File-backed or device-backed namespace config (see reference.md) - "production deployment" / "cloud deployment" → Official docs only; use Choose a path first path 1 - "time-series" / "TTL" / "expiring data" → default-ttl namespace config and per-record TTL in write policy - "transactions" / "ACID" → Strong consistency mode (Enterprise feature) or record-level atomicity (Community)

## aerospike-development

### Client best practices (enforce in generated or reviewed code) - Singleton client: One AerospikeClient (or language equivalent) per process; it is thread-safe and holds pools and cluster state. Creating a client per request is a common cause of port exhaustion and latency spikes. - Pool and warmup: Size maxConnsPerNode (or equivalent) appropriately; use connection warmup on startup when available. - Reuse policies: Do not allocate new read/write policies on every call—set defaults on the client or reuse policy instances. - Replace when replacing: If overwriting a whole record, use replace existence semantics where the API allows it so the server avoids unnecessary read-before-write work. - Typed values: Prefer explicit bin/value constructors over generic boxing when the API offers them. - Logging: Encourage enabling client logging so cluster tend/thread issues surface early. - Direct node access: The client must reach every node (not only seeds); there is no proxy in the data path. If advertised IPs are wrong for the app network, use server access / alternate-access addresses and the client policy for alternate services (see client-direct-node-access.md).

### Common pitfalls - Load balancer or proxy only to seeds; app cannot reach all node addresses -> Clients need direct TCP to every node; use access-address / alternate-access-address (and client useServicesAlternate when needed)—not a proxy in the data path; see client-direct-node-access.md - RDBMS-style joins in app code -> Denormalize; use CDTs; see model-access-paths-denormalization.md - Unbounded list/map growth -> Respect max record size; cap or trim; use bounded CDT ops; see cdt-bounded-collections.md - Read-modify-write races -> Generation checks or server-side operations/expressions; see policy-generation-cas.md, expr-compute-to-data.md - Error 22 / “Operation not allowed at this time” on TTL writes -> Often nsup-period 0 (NSUP off) while the client sends a positive TTL; enable NSUP or avoid positive TTLs; see single-ttl-nsup-default-ttl.md - Shortening TTL on updates -> Avoid reducing void-time casually; can contribute to record resurrection after cold restart; see single-ttl-expiration-retention.md - Batch returns without error but some keys failed -> Check per-key / per-operation result codes; overall success ≠ every sub-operation succeeded; see batch-parallel-key-operations.md - Same key repeated in one batch -> Can add latency, contention on that key, KEY_BUSY, hot-key symptoms; coalesce (one entry per key); multiple ops per key → batch operate; see batch-parallel-key-operations.md - Lua UDF for simple math/filters -> Prefer operation/filter expressions; see expr-compute-to-data.md

### Rule set - client- -> Connection lifecycle, pools, warmup, tend, error-rate backoff, direct node reachability - policy- -> Timeouts/retries, client-level defaults, replica & AP/SC read modes, sendKey, commit level, generation/CAS, replace - cdt- -> Lists/maps, nesting (K-order, context), growth limits, server-side collection ops - expr- -> Filter/operation/path expressions vs heavier alternatives - query- -> Secondary indexes, cardinality/cost, and deriving index needs from access paths - batch- -> Many primary-key reads/writes; one key per batch entry, coalesce, batch operate - binop- -> operate, one record lock, mixed read/write, atomic multi-bin updates - single- -> Whole-record vs partial/bin operations; TTL void-time and NSUP/default-ttl; delete and durable deletes (EE) - model- -> Namespace and set boundaries; flat bins vs CDTs vs multiple records; keys, denormalization, access paths; operate / batch / expressions; record size vs index RAM and disk; hot keys and error 14 / KEY_BUSY - sec- -> TLS and access control on the client

### Use batch APIs for many primary-key operations [MEDIUM] - When reading or writing many records by known primary keys, use the client’s batch APIs instead of serial single-key calls, subject to reasonable batch sizes and error-handling needs. - Prefer: Chunked batches if the SDK or service limits batch size; One entry per key per batch; merge or drop duplicates on the client before batch_*; Batch operate (or equivalent) when one key needs multiple operations atomically in the batch; After each batch: walk every entry’s result code or exception slot—partial success is normal for batch APIs; Retrying or compensating only for keys that actually failed (once you have per-key status) - Avoid: Thousands of sequential gets when a batch interface exists; Duplicate keys in the same batch when you can coalesce or combine into operate—especially on keys that are already hot or latency-sensitive; Assuming no exception or overall OK means every key in the batch succeeded

### Use operate for multi-bin atomic updates on one key [HIGH] - When a single logical update touches multiple bins or uses CDT ops on one record, use operate (multi-operation) so the server applies the sequence atomically for that record, rather than separate put/get cycles that can interleave with other writers. - Prefer: One operate call combining the bin ops you need; Generations when you need compare-and-swap across clients - Avoid: Multiple independent puts racing without coordination; Mixing a whole-record read with bin-scoped ops in one operate (use per-bin reads only; see binop-operate-record-lock-read-write.md)

### Use operate for one record lock, many ops, and mixed reads and writes [HIGH] - Use the operate command when you need multiple bin-level changes on the same record key in one server round trip. The server acquires a record lock, runs an ordered list of bin operations atomically and in isolation against an in-memory copy of the record, then persists if any write occurred. Mix read and write operations in the same operate call when you need updated values back without a separate get: later operations see the effects of earlier ones in the list (including writes before reads). This cut