Appendix D: Glossary #

This glossary defines technical terms used throughout this book. Terms are listed alphabetically. Cross-references to other glossary entries are shown in italics.

Agentic RAG The most advanced RAG strategy in Neam. The agent autonomously decomposes complex queries into sub-queries, retrieves from multiple knowledge bases, cross- references results, and iterates until a confidence threshold is met. Unlike Corrective RAG, which simply reformulates a single query, agentic RAG operates as an autonomous retrieval loop. Configured with retrieval_strategy: "agentic".

Agent A first-class construct in Neam that wraps an LLM provider call with a system prompt, temperature, tools, memory, and cognitive features. Declared with the agent keyword. Agents are the primary unit of AI behavior in Neam. A stateless agent can be called interactively via .ask() or run autonomously on a schedule. See also: Claw Agent, Forge Agent.

Auto-Compaction The automatic compression of conversation history when a Claw Agent's context approaches its token budget. When context usage exceeds 80%, the oldest two-thirds of history turns are summarized by the LLM into a single message, preserving key facts while freeing context space. Configured via compaction: "auto" in the session block.

A2A (Agent-to-Agent Protocol) An open protocol (originated by Google) for inter-agent communication over HTTP. Neam's neam-api server supports A2A natively, allowing Neam agents to communicate with agents built in other frameworks. The protocol defines an Agent Card (capabilities), task submission, and streaming updates.

Bytecode The intermediate representation produced by the Neam compiler (neamc). Bytecode files use the .neamb extension and consist of a sequence of typed opcodes that the VM executes. Bytecode is platform-independent and can be distributed without source code.

Budget A set of daily limits applied to autonomous agent execution: maximum API calls, maximum token consumption, and maximum cost in USD. Budgets prevent runaway costs when agents operate without human supervision. Budget counters reset at midnight UTC. Interactive calls (.ask()) are not subject to autonomous budgets.

Channel A message I/O adapter that connects a Claw Agent to an external communication platform. Declared with the channel keyword. Each channel specifies a type ("cli" or "http"), authentication settings, and message routing policies. Channels are bound to claw agents via the channels field.

Channelable One of the six built-in NeamClaw Traits. Implementing Channelable enables multi-channel message routing for a Claw Agent. Required methods: channels(self) and on_message(self, msg). Only compatible with claw agents; produces a compile error on forge agents or stateless agents.

Checkpoint A saved state of a Forge Agent's workspace after a successful verification step. Three strategies are available: "git" (runs git add -A && git commit), "snapshot" (filesystem copy), and "none" (no checkpointing). Checkpoints enable reverting to known-good states if subsequent iterations fail.

Claw Agent A persistent, session-aware agent type declared with the claw agent keyword. Claw agents maintain conversation history across calls, support multi-channel I/O, lane-based concurrency, auto-compaction, and semantic memory. Designed for assistants, chatbots, and real-time workflow automation. See Chapters 24 and 26.

Capability In the A2A protocol, a capability describes what an agent can do. Capabilities are advertised in the Agent Card and include skills, supported input types, and supported output types. In Neam, capabilities are inferred from the agent's tools, handoffs, and cognitive features.

Circuit Breaker A resilience pattern implemented in the LLM Gateway. The circuit breaker monitors LLM provider failures and, after a configurable threshold of consecutive failures, temporarily blocks all requests to the failing provider. This prevents cascading failures and allows the system to failover to alternative providers. The circuit transitions through three states: Closed (normal), Open (blocked), and Half-Open (testing recovery).

Cognitive Features A collective term for the five agent capabilities introduced in Neam v0.5.0: Reasoning, Reflection, Learning, Evolution, and Autonomy. These features are opt-in and compound when combined. They enable agents to think more carefully, evaluate their own output, learn from experience, improve their prompts over time, and act independently on schedules.

Corrective RAG An advanced RAG strategy that adds a verification step after retrieval. A lightweight LLM call scores each retrieved chunk for relevance. If the average relevance falls below a threshold, the system reformulates the query and retrieves again. This reduces the impact of poor initial queries. Configured with retrieval_strategy: "corrective_rag" in a knowledge declaration.

dag_execute() A native function that executes a directed acyclic graph of agent tasks with dependency ordering. Each node specifies an agent name, a task description, and a list of dependency IDs. Nodes are executed in topological order using Kahn's algorithm, with independent nodes eligible for concurrent execution. Returns a map of node IDs to result strings. See Chapter 13.

DynamoDB Amazon's managed NoSQL database service. Neam supports DynamoDB as a distributed StateBackend for agent memory, learning data, and distributed locks. Requires the -DNEAM_BACKEND_AWS=ON compile flag. Connection string format: dynamodb://region/table-name.

Diagnostic Triage An observability feature (Ch. 22) that uses rolling-window baselines, error pattern analysis, and dependency graphing to automatically identify the root cause of agent system failures. The triage module generates diagnostic reports with severity classifications and actionable recommendations.

Embedding A dense vector representation of text, computed by an embedding model (e.g., text-embedding-3-small, nomic-embed-text). Embeddings capture semantic meaning and are used in RAG pipelines to find text passages similar to a query. Neam computes embeddings automatically when indexing a Knowledge Base.

Escalation Agent A specialized Agent pattern designed to handle cases that exceed the authority or capability of frontline agents. Escalation agents typically have higher spending authority, de-escalation training in their system prompt, and Reflection enabled on empathy and resolution quality dimensions. See Case Study 1.

Evolution A cognitive feature that enables an agent to refine its system prompt over time based on accumulated Learning data. Evolution preserves a declared core_identity string and supports version rollback. Configured with the evolve property on an agent declaration. See also: Prompt Evolution.

Forge Agent An iterative build-verify agent type declared with the forge agent keyword. Forge agents use fresh context per iteration, external verification callbacks, file-based state (plan, progress, learnings), and checkpoint strategies. Designed for TDD coding workflows, document generation, and long-horizon tasks. The .run() method executes the main loop. See Chapter 25.

Federation A planned capability (v0.7) for agent interoperability across organizational boundaries. Federated execution allows agents in separate deployments to communicate through the A2A protocol with mutual authentication, policy enforcement, and audit logging. See also: Marketplace.

Firestore Google Cloud's managed NoSQL document database. Neam supports Firestore as a distributed StateBackend for agent memory, learning data, and distributed locks. Uses a collection-per-type design with transaction-based locking. Authenticates via Application Default Credentials (ADC). Requires the -DNEAM_BACKEND_GCP=ON compile flag.

Fresh Context The execution model used by Forge Agents where each iteration starts with a clean context window. The agent reads current filesystem state, performs one task, and terminates. No conversation history accumulates between iterations, eliminating context rot and semantic drift. File-based state (plan files, progress JSONL, learnings JSONL) provides continuity across iterations.

Guardrail A validation or transformation step applied to agent input or output. Declared with the guard keyword. Input guardrails run before the agent receives the message (e.g., PII redaction). Output guardrails run before the response is returned to the user (e.g., quality checks, toxicity filtering). Guardrails are combined into guardchain sequences and attached to Runners.

Handoff The transfer of control from one agent to another during a Runner execution loop. Handoffs are declared in the handoffs property of an agent. The LLM decides when to hand off based on the tool descriptions provided in each handoff configuration. Handoffs can include callbacks (on_handoff), input filters, and conditional enabling.

HeartbeatAction A sealed type returned by the on_heartbeat method of the Schedulable trait. Variants: HeartbeatAction.Notify(message) (send a proactive message) and HeartbeatAction.Silent (take no action). Used to control proactive agent behavior.

HPA (Horizontal Pod Autoscaler) A Kubernetes resource that automatically scales the number of pod replicas based on CPU utilization, memory utilization, or custom metrics. Neam generates HPA manifests from the [deploy.kubernetes.scaling] section of neam.toml.

HNSW (Hierarchical Navigable Small World) A graph-based algorithm for approximate nearest neighbor search. Used internally by the uSearch vector store to efficiently find the most similar embeddings during RAG retrieval. HNSW provides sub-millisecond search times even with millions of vectors.

HyDE (Hypothetical Document Embeddings) An advanced RAG strategy where the system generates a hypothetical answer to the query, embeds that hypothetical answer, and uses it for retrieval instead of the original query. This often produces better results because the hypothetical answer is closer in embedding space to relevant documents than the query itself. Configured with retrieval_strategy: "hyde".

Ingest Pipeline A configurable document processing pipeline provided by the stdlib/ingest/ modules. Ingest pipelines define stages for sourcing, parsing, chunking, embedding, and indexing documents into Knowledge Bases. Source connectors support files, URLs, S3 buckets, GCS buckets, databases, and API endpoints. Parsers support PDF, HTML, Markdown, CSV, JSON, and plain text.

Initiative A boolean property on an agent (initiative: true) that indicates the agent can act proactively without being asked. Agents with initiative and a trigger schedule execute autonomously in the background. Without initiative: true, schedule triggers are ignored.

KEDA (Kubernetes Event-Driven Autoscaler) An open-source Kubernetes operator that extends the HPA with event-driven scaling triggers (e.g., scale based on message queue depth, HTTP request rate, or custom metrics). Neam can generate KEDA ScaledObject manifests when configured in neam.toml.

Knowledge Base A collection of documents indexed for RAG retrieval. Declared with the knowledge keyword. A knowledge base specifies a vector store, embedding model, chunking parameters, retrieval strategy, and data sources (files, directories, URLs). Connected to agents via the connected_knowledge property.

Lane A concurrency partition within a Claw Agent. Each lane has a name, a concurrency level (number of worker threads), and a priority. Messages are routed to lanes for processing. The default main lane has concurrency 1 (serial processing). Higher concurrency enables parallel message handling within the same agent.

LoopOutcome A sealed type representing the result of a Forge Agent's .run() method. Variants: Completed (all tasks verified), MaxIterations (iteration limit reached), Aborted (verify callback returned "abort"), and BudgetExhausted (cost or token limit exceeded). The result includes iteration count, total cost, and a descriptive message.

LLM (Large Language Model) A neural network trained on large text corpora that generates human-like text given a prompt. Neam supports multiple LLM providers: OpenAI (GPT-4o, GPT-4o-mini), Anthropic (Claude), Google (Gemini), Meta (Llama via Ollama), AWS Bedrock, GCP Vertex AI, and Azure OpenAI.

LLM Gateway An in-process component (v0.6.0) that sits between the VM and LLM providers. The gateway provides rate limiting (token bucket), circuit breaking, retry with exponential backoff, provider failover, response caching, and cost tracking. Configured in the [llm] section of neam.toml.

Marketplace A planned capability (v0.7) that provides a registry where published agents can be discovered, composed, and reused across organizations. The marketplace functions as a package manager for agent capabilities rather than code libraries, complementing neam-pkg which handles code-level packages. See also: Federation.

memory_search() A native function that performs semantic search across a Claw Agent's indexed workspace files. Accepts a query string and optional top_k parameter (default 5). Returns a list of maps containing file_path, chunk, and score fields. Scoring uses hybrid mode (70% vector cosine + 30% BM25) when configured with search: "hybrid". See Chapter 26.

Monitorable One of the six built-in NeamClaw Traits. Implementing Monitorable enables behavioral anomaly detection for an agent. Required methods: baseline(self) (returns a map of expected metrics) and on_anomaly(self, event) (handles detected anomalies). Compatible with both claw and forge agents. See Chapter 27.

MCP (Model Context Protocol) An open protocol (originated by Anthropic) that allows LLMs to access external tools and data sources through a standardized interface. Neam includes an MCP client that can connect to any MCP server, making its tools available to Neam agents.

MMR (Maximal Marginal Relevance) A RAG retrieval strategy that balances relevance and diversity. MMR penalizes retrieved documents that are too similar to each other, ensuring the agent receives a diverse set of information rather than multiple passages saying the same thing. Configured with retrieval_strategy: "mmr".

Module A Neam source file that exports agents, tools, functions, or other declarations for use by other files. Modules use the module keyword at the top of the file and import statements to reference other modules. The module system supports visibility control (pub keyword) and circular dependency detection.

NeamClaw The codename for the Neam release that introduced the distinct agent type system. NeamClaw adds two new agent keywords (claw agent and forge agent), six composable traits, a three-tier memory architecture, channel/lane systems, and the neam-forge CLI. See Chapters 24--28.

neam-forge A command-line tool for running Forge Agents directly from the terminal. Compiles a .neam file, locates the forge agent declaration, and executes the .run() loop. Supports override flags for workspace, iteration limits, and cost budgets. Returns a LoopOutcome map and exits with code 0 on success. See Appendix C.

Neam A domain-specific programming language for building AI agent systems. Neam source files (.neam) are compiled to bytecode (.neamb) and executed on a purpose-built virtual machine. The language provides first-class support for agents, tools, knowledge bases, handoffs, guardrails, runners, voice pipelines, and cognitive features.

neamc The Neam compiler and build system. Compiles .neam source files to .neamb bytecode. Also handles testing, deployment artifact generation, auditing, and package dependency management. See Appendix C.

neam-cli The Neam interactive development tool. Provides a REPL for exploratory programming, watch mode for hot-reloading during development, and direct program execution without producing bytecode files. See Appendix C.

neam-api The Neam HTTP server. Exposes agents as REST endpoints and supports the A2A protocol. Used for production deployment and inter-system communication. See Appendix C.

neam-gym The Neam evaluation framework. Supports five grading strategies: exact_match, contains, regex, llm_judge, and semantic_match. Systematically evaluates agent performance against labeled datasets with configurable judge models, multiple runs for statistical significance, and pass/fail thresholds. See Appendix C.

neam-pkg The Neam package manager. Installs, publishes, and manages reusable agent components from the community registry. Packages can contain agents, tools, guardrails, knowledge configurations, and standard library extensions. Dependencies are declared in the [dependencies] section of neam.toml. See Appendix C.

Orchestrable One of the six built-in NeamClaw Traits. Implementing Orchestrable enables multi-agent spawn/delegate callbacks. Methods: on_spawn(self, child) (called before a sub-agent is invoked) and on_delegate(self, result) (called after the sub-agent returns). Compatible with both claw and forge agents. See Chapter 27.

OTLP (OpenTelemetry Protocol) The wire protocol for OpenTelemetry data (traces, metrics, logs). Neam exports telemetry in OTLP/HTTP JSON format to any compatible collector (Jaeger, Grafana Tempo, Datadog, etc.). Configured in the [telemetry] section of neam.toml.

PDB (Pod Disruption Budget) A Kubernetes resource that limits the number of pods that can be simultaneously unavailable during voluntary disruptions (node drains, cluster upgrades). Neam generates PDB manifests from the [deploy.kubernetes.disruption] section.

Prompt Evolution The process by which an agent's system prompt is automatically refined based on accumulated learning data. The VM constructs a meta-prompt that asks the LLM to propose an improved system prompt, validates that the core_identity is preserved, and stores the new version. Prompt evolution is versioned and supports rollback. See also: Evolution.

Privacy Mode A telemetry configuration (Ch. 22) that controls how sensitive data is handled in traces and logs. Four modes are available: full (capture everything), redact (replace PII with placeholders), hash (one-way hash sensitive fields), and minimal (capture only structural data, no content). Privacy modes apply to all exported telemetry and can be overridden at runtime with time-limited capture windows.

Provider An LLM service that Neam can connect to for inference. Supported providers: "openai", "anthropic", "gemini", "ollama", "azure_openai", "bedrock", "vertex". Each provider has its own API format, authentication mechanism, and pricing model. Providers are specified in agent declarations via the provider property.

RAG (Retrieval-Augmented Generation) A technique that enhances LLM responses by retrieving relevant information from an external Knowledge Base before generating a response. Neam supports seven RAG strategies: basic, MMR, hybrid, HyDE, Self-RAG, Corrective RAG, and agentic RAG. RAG is configured through knowledge declarations and the connected_knowledge property on agents.

Red Team Testing Adversarial testing of agent safety using the stdlib/agents/redteam/ package. Includes benchmarks (BBQ, HarmBench, TruthfulQA), compliance checks (MITRE, NIST, OWASP LLM Top 10), fuzzing strategies, and CI/CD integration for automated safety gates. Red team testing evaluates agents against prompt injection, jailbreak, and data exfiltration attacks.

Rate Limiting The practice of limiting the number of requests sent to an LLM provider within a time window. Neam's LLM Gateway implements rate limiting using a Token Bucket algorithm. Configured per-provider in [llm.rate-limits.*].

Reasoning A cognitive feature that adds structured thinking to an agent's response process. Four strategies are available: chain_of_thought (step-by-step), plan_and_execute (multi-step planning), tree_of_thought (multi-branch evaluation), and self_consistency (majority voting). Configured with the reasoning property.

Reflection A cognitive feature that enables an agent to evaluate its own output against configurable quality dimensions (e.g., accuracy, relevance, completeness). The agent calls the LLM again to score its response, and can revise, retry, escalate, or acknowledge low-quality results. Configured with the reflect property.

Runner A first-class construct that manages the agent execution loop. Declared with the runner keyword. A runner specifies an entry agent, maximum turns, and optional input/output guardrail chains. The runner handles handoffs between agents, enforces turn limits, and collects execution traces.

Sandboxable One of the six built-in NeamClaw Traits. Implementing Sandboxable configures per-execution isolation parameters for an agent. Required method: sandbox_config(self) returning a map with keys like network, filesystem, and max_memory_mb. Compatible with both claw and forge agents. See Chapter 27.

Schedulable One of the six built-in NeamClaw Traits. Implementing Schedulable enables periodic heartbeat and cron-based scheduling for a Claw Agent. Required methods: on_heartbeat(self) (returns a HeartbeatAction) and heartbeat_interval(self) (returns milliseconds). Optional: on_cron(self, id). Only compatible with claw agents. See Chapter 27.

Searchable One of the six built-in NeamClaw Traits. Implementing Searchable configures RAG and search behavior for an agent. Required method: search_config(self) returning a map with keys like strategy, top_k, and min_score. Optional: on_index(self, doc). Compatible with all agent types. See Chapter 27.

Semantic Memory A searchable index of workspace files maintained by a Claw Agent. Supports three search modes: "hybrid" (70% vector cosine + 30% BM25), "vector" (cosine similarity only), and "keyword" (BM25 only). Files are chunked (400 characters, 80-character overlap) and indexed automatically. Queried via memory_search().

Session A persistent conversation context maintained by a Claw Agent. Sessions store message history as JSONL files on disk, support idle and daily reset policies, configurable history turn limits, and auto-compaction. Each session is identified by a session key and is isolated from other sessions on the same agent.

session_history() A native function that retrieves conversation history for a Claw Agent's session. Accepts an optional session key and turn limit. Returns a list of maps with role and content fields. See Chapter 26.

Sampling A telemetry strategy that controls which traces are exported to the collector. Four strategies are available: ratio (probabilistic), parent_based (inherits from parent span), always_on, and always_off. Configurable via [telemetry] in neam.toml or programmatically via the observability/sampling/ stdlib modules. Hash-based deterministic sampling ensures consistency within a trace.

Secrets Resolver A component that resolves sensitive values (API keys, passwords) at runtime. Supports multiple backends: environment variables, AWS Secrets Manager, GCP Secret Manager, Azure Key Vault, and dotenv files. Configured in the [secrets] section of neam.toml.

Self-RAG An advanced RAG strategy where the agent generates its initial response, then critically evaluates whether the response is fully supported by the retrieved evidence. If the response contains unsupported claims, the agent revises using only the retrieved context. Configured with retrieval_strategy: "self_rag".

Structured Logging A logging approach (Ch. 22) that produces JSON-formatted log records with trace correlation. Each log record includes timestamp, level, message, trace ID, span ID, and arbitrary structured fields. Log levels follow the standard hierarchy: debug, info, warn, error, fatal. Structured logs integrate with the OpenTelemetry Logs API for unified export alongside traces and metrics.

spawn A keyword for invoking another agent from within agent code. spawn agent_name(task) performs a single-turn LLM call to the named agent and returns the result as a string. The spawn resolution order checks claw agents, then forge agents, then stateless agents. When the spawning agent implements Orchestrable, callbacks fire automatically. See Chapter 13.

Skill In the A2A protocol, a named capability that an agent advertises. Skills have a name, description, and input/output schema. When a remote agent sends a task that matches a skill, the Neam agent handles it automatically.

StateBackend The interface for persistent storage of agent memory, learning interactions, prompt evolution history, autonomous action logs, budget tracking, and distributed locks. Implementations: SQLite (default), PostgreSQL, Redis, DynamoDB, CosmosDB.

STT (Speech-to-Text) The process of converting spoken audio to text. Neam supports STT providers: OpenAI Whisper, Gemini, and local whisper.cpp. STT is the first stage of a Voice Pipeline.

System Prompt The initial instruction given to an LLM that defines the agent's persona, behavior, and constraints. In Neam, the system prompt is set via the system property on an agent declaration. System prompts can be evolved over time via Prompt Evolution.

Terraform An infrastructure-as-code tool by HashiCorp. Neam can generate Terraform HCL modules via neamc deploy terraform, producing provider configuration, resource definitions, variables, outputs, and remote state backend configuration for AWS, GCP, or Azure deployments. The generated modules are composable and can be integrated into existing Terraform workflows.

Telemetry Observability data exported by the Neam runtime: distributed traces (spans), metrics (counters, histograms), and structured logs. Exported via OTLP to a compatible collector. Configured in [telemetry] in neam.toml.

Token Bucket An algorithm for rate limiting. The bucket holds tokens up to a maximum capacity (burst size). Tokens are added at a constant rate (requests per minute / 60). Each request consumes one token. If the bucket is empty, the request waits. Neam's LLM Gateway uses token buckets for per-provider rate limiting.

Tool A first-class construct that provides agents with access to external capabilities. Declared with the tool keyword. Each tool has a description (used by the LLM to decide when to invoke it), typed parameters (JSON Schema), and an implementation function. Tools enable agents to call APIs, query databases, process data, and perform actions in the world.

TTS (Text-to-Speech) The process of converting text to spoken audio. Neam supports TTS providers: OpenAI, Gemini, Kokoro, and Piper. TTS is the final stage of a Voice Pipeline.

VAD (Voice Activity Detection) An algorithm that detects when a user is speaking in a real-time audio stream. VAD is used in real-time Voice Pipeline configurations to determine when to start and stop processing audio. Neam supports configurable VAD thresholds for silence detection and barge-in (interruption).

Vector Store A specialized database for storing and searching high-dimensional vectors (embeddings). Neam uses uSearch as its built-in vector store, which implements the HNSW algorithm for fast approximate nearest neighbor search. Vector stores are used in Knowledge Base declarations.

VerifyResult A sealed type returned by a Forge Agent's verify callback. Variants: VerifyResult.Done(message) (task verified, proceed to checkpoint and next task), VerifyResult.Retry(feedback) (task not verified, retry with feedback string), and VerifyResult.Abort(reason) (stop the forge loop immediately). The verify callback can also return simple boolean values: true maps to Done, false/nil maps to Retry.

Voice Pipeline A three-stage pipeline for voice-enabled agents: STT (audio to text) -> Agent (text to text) -> TTS (text to audio). Declared with the voice keyword. Neam supports both batch pipelines (file-based) and real-time streaming (WebSocket-based). Multiple STT and TTS providers can be mixed.

Workspace An agent-scoped filesystem root directory used for persistent file I/O. Both Claw Agents and Forge Agents can declare a workspace via the workspace field. All file operations (workspace_read, workspace_write, workspace_append) are resolved relative to this directory. Path traversal (using ..) is rejected for security. Claw agent sessions and semantic memory indexes are stored within the workspace.

workspace_read() A native function that reads the contents of a file within an agent's Workspace. Accepts a relative path string. Returns the file content as a string, or nil if the file does not exist. Rejects paths containing .. for security.

workspace_write() A native function that writes content to a file within an agent's Workspace. Accepts a relative path and content string. Creates parent directories if needed. Truncates existing files. Returns true on success.

workspace_append() A native function that appends content to a file within an agent's Workspace. Accepts a relative path and content string. Creates the file if it does not exist. Returns true on success.