@hilbras/omninode 2.0.0-alpha.7 → 2.0.0-alpha.8

package/dist/index.d.ts

@@ -306,30 +306,63 @@ interface ChatStreamChunk {
 }
 
 /**
- * Memory abstraction. Remembera is the preferred Hilbras integration, but the
- * core depends only on this interface (memory-agnostic principle, §2, §19).
+ * Memory abstraction (§19). Remembera is the preferred implementation, but
+ * the core depends only on this interface (memory-agnostic principle, §2).
+ *
+ * v2 contract (roadmap §12): retrieve / store / search / metadata, across
+ * project / task / role scopes with structured categories.
  */
-type MemoryScope = "project" | "role" | "task" | "knowledge";
+type MemoryScope = "project" | "task" | "role" | "knowledge";
+/** Structured memory categories (roadmap §12, Memory Categories). */
+type MemoryCategory = "project" | "architecture" | "decisions" | "tasks" | "problems" | "solutions" | "conventions" | "agent_reports";
 interface MemoryEntry {
     key: string;
     scope: MemoryScope;
     content: string;
+    /** Structured category, when the backend supports it. */
+    category?: MemoryCategory;
     tags?: string[];
     createdAt?: string;
     updatedAt?: string;
     metadata?: Record<string, unknown>;
 }
 interface MemoryQuery {
+    /** Free-text relevance query. */
+    text?: string;
     scope?: MemoryScope;
+    category?: MemoryCategory;
     tags?: string[];
-    /** Free-text relevance query; implementations decide ranking. */
-    text?: string;
     limit?: number;
 }
+interface MemoryProviderMetadata {
+    name: string;
+    /** What the backend can do, so callers can adapt (e.g. no category support). */
+    capabilities: Array<"retrieve" | "store" | "search" | "categories" | "tags">;
+    /** True when the backend enforces relevance ranking itself. */
+    relevanceRanking: boolean;
+    /** Backend-specific info (gateway version, endpoint type…). */
+    backend?: Record<string, unknown>;
+}
+/**
+ * The memory contract. `query`/`write` are the v1 names, kept as aliases so
+ * existing integrations keep working — new code should use retrieve/store.
+ */
 interface IMemoryProvider {
     readonly name: string;
-    /** Retrieve relevant memory; only relevant context should reach a task (§20). */
+    /** Retrieve entries relevant to a query (task-oriented). */
+    retrieve(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** Store an entry (upsert by key). */
+    store(entry: MemoryEntry): Promise<void>;
+    /** Free-text search across scopes. */
+    search(text: string, options?: {
+        limit?: number;
+        scope?: MemoryScope;
+    }): Promise<MemoryEntry[]>;
+    /** Provider capabilities (contract introspection). */
+    metadata(): MemoryProviderMetadata;
+    /** @deprecated v1 alias of {@link retrieve}. */
     query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link store}. */
     write(entry: MemoryEntry): Promise<void>;
 }
 
@@ -1216,17 +1249,18 @@ declare const projectConfigSchema: z.ZodObject<{
         provider: z.ZodDefault<z.ZodString>;
         base_url: z.ZodOptional<z.ZodString>;
         api_key_env_var: z.ZodOptional<z.ZodString>;
-        timeout_ms: z.ZodOptional<z.ZodNumber>;
+        /** When true, memory failures fail tasks instead of being tolerated (§12). */
+        required: z.ZodOptional<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         provider: string;
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
-        timeout_ms?: number | undefined;
+        required?: boolean | undefined;
     }, {
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
-        timeout_ms?: number | undefined;
         provider?: string | undefined;
+        required?: boolean | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
     name: string;
@@ -1292,7 +1326,7 @@ declare const projectConfigSchema: z.ZodObject<{
         provider: string;
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
-        timeout_ms?: number | undefined;
+        required?: boolean | undefined;
     } | undefined;
 }, {
     name: string;
@@ -1357,8 +1391,8 @@ declare const projectConfigSchema: z.ZodObject<{
     memory?: {
         base_url?: string | undefined;
         api_key_env_var?: string | undefined;
-        timeout_ms?: number | undefined;
         provider?: string | undefined;
+        required?: boolean | undefined;
     } | undefined;
 }>;
 declare const appConfigSchema: z.ZodObject<{
@@ -1551,17 +1585,18 @@ declare const appConfigSchema: z.ZodObject<{
             provider: z.ZodDefault<z.ZodString>;
             base_url: z.ZodOptional<z.ZodString>;
             api_key_env_var: z.ZodOptional<z.ZodString>;
-            timeout_ms: z.ZodOptional<z.ZodNumber>;
+            /** When true, memory failures fail tasks instead of being tolerated (§12). */
+            required: z.ZodOptional<z.ZodBoolean>;
         }, "strict", z.ZodTypeAny, {
             provider: string;
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
-            timeout_ms?: number | undefined;
+            required?: boolean | undefined;
         }, {
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
-            timeout_ms?: number | undefined;
             provider?: string | undefined;
+            required?: boolean | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
         name: string;
@@ -1627,7 +1662,7 @@ declare const appConfigSchema: z.ZodObject<{
             provider: string;
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
-            timeout_ms?: number | undefined;
+            required?: boolean | undefined;
         } | undefined;
     }, {
         name: string;
@@ -1692,8 +1727,8 @@ declare const appConfigSchema: z.ZodObject<{
         memory?: {
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
-            timeout_ms?: number | undefined;
             provider?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     }>;
     logging: z.ZodOptional<z.ZodObject<{
@@ -1768,7 +1803,7 @@ declare const appConfigSchema: z.ZodObject<{
             provider: string;
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
-            timeout_ms?: number | undefined;
+            required?: boolean | undefined;
         } | undefined;
     };
     logging?: {
@@ -1838,8 +1873,8 @@ declare const appConfigSchema: z.ZodObject<{
         memory?: {
             base_url?: string | undefined;
             api_key_env_var?: string | undefined;
-            timeout_ms?: number | undefined;
             provider?: string | undefined;
+            required?: boolean | undefined;
         } | undefined;
     };
     logging?: {
@@ -1871,6 +1906,7 @@ interface AppConfig {
             provider: string;
             baseUrl?: string;
             apiKeyEnvVar?: string;
+            required?: boolean;
         };
     };
     logging?: {
@@ -2334,8 +2370,17 @@ declare function keywords(text: string): Set<string>;
 declare class LocalMemoryProvider extends JsonFileStore<MemoryEntry> implements IMemoryProvider {
     readonly name = "local";
     constructor(directory?: string);
+    metadata(): MemoryProviderMetadata;
+    search(text: string, options?: {
+        limit?: number;
+        scope?: MemoryQuery["scope"];
+    }): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link retrieve}. */
     query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link store}. */
     write(entry: MemoryEntry): Promise<void>;
+    retrieve(query: MemoryQuery): Promise<MemoryEntry[]>;
+    store(entry: MemoryEntry): Promise<void>;
     count(): Promise<number>;
 }
 
@@ -2351,9 +2396,20 @@ declare class RememberaMemoryProvider implements IMemoryProvider {
     private readonly env;
     private readonly log;
     constructor(config: RememberaConfig, log?: Logger);
+    private get authenticationConfigured();
     private headers;
+    /** Search delegates to the gateway's relevance query. */
+    search(text: string, options?: {
+        limit?: number;
+        scope?: MemoryQuery["scope"];
+    }): Promise<MemoryEntry[]>;
+    metadata(): MemoryProviderMetadata;
+    /** @deprecated v1 alias of {@link retrieve}. */
     query(query: MemoryQuery): Promise<MemoryEntry[]>;
+    /** @deprecated v1 alias of {@link store}. */
     write(entry: MemoryEntry): Promise<void>;
+    retrieve(query: MemoryQuery): Promise<MemoryEntry[]>;
+    store(entry: MemoryEntry): Promise<void>;
     private request;
     private toEntry;
 }
@@ -2361,31 +2417,66 @@ declare class RememberaMemoryProvider implements IMemoryProvider {
 type MemoryProviderConfig = NonNullable<AppConfig["project"]["memory"]>;
 declare function createMemoryProvider(config?: MemoryProviderConfig): IMemoryProvider;
 
-/**
- * Memory service (§19–§20): gathers relevant memory before a task runs and
- * records outcomes afterwards — the Task → memory → relevant context →
- * agents → reports → memory loop. Memory failures are best-effort: they log
- * a warning and never fail a task, because memory is an enhancement, not a
- * dependency (§2).
- */
-
 interface MemoryContextQuery {
     objective: string;
     role?: string;
     project?: string;
+    /** Maximum entries to consider (relevance-ranked by the provider). */
+    limit?: number;
+}
+interface MemoryTaskContext {
+    /** Prompt-ready context text ("" when nothing relevant was found). */
+    text: string;
+    entries: MemoryEntry[];
+    /** True when the character budget cut the context short. */
+    truncated: boolean;
+}
+declare const MAX_CONTEXT_CHARS = 4000;
+interface MemoryServiceOptions {
+    /** When true, backend failures propagate instead of being logged. */
+    required?: boolean;
+    maxContextChars?: number;
 }
 declare class MemoryService {
     private readonly provider;
     private readonly log;
-    constructor(provider: IMemoryProvider, log?: Logger);
+    private readonly required;
+    private readonly maxContextChars;
+    constructor(provider: IMemoryProvider, log?: Logger, options?: MemoryServiceOptions);
     get providerRef(): IMemoryProvider;
     get providerName(): string;
-    /** Relevant context for a task objective; empty string when nothing matches. */
+    get isRequired(): boolean;
+    /** Structured, budgeted context for a task (§12 — avoid loading all memory). */
+    contextFor(query: MemoryContextQuery): Promise<MemoryTaskContext>;
+    /** Prompt-ready context text (v1 convenience wrapper). */
     gatherContext(query: MemoryContextQuery): Promise<string>;
-    /** Records a finished task's outcome — best-effort. */
+    /** Records a finished task's outcome — task history plus "known problems" (§12). */
     recordTaskOutcome(task: Task): Promise<void>;
+    private format;
+    /**
+     * Failure policy (§12): continue unless memory is explicitly required.
+     */
+    private handleFailure;
 }
 
+/**
+ * Shared memory-contract helpers (roadmap §12). Adapters implement
+ * `retrieve` / `store`; these helpers supply the defaults for `search`,
+ * `metadata` and the v1 `query` / `write` aliases, so the contract is
+ * defined once.
+ */
+
+/** Free-text search defaults to a relevance retrieve. */
+declare function defaultSearch(provider: Pick<IMemoryProvider, "retrieve">, text: string, options?: {
+    limit?: number;
+    scope?: MemoryQuery["scope"];
+}): Promise<MemoryEntry[]>;
+declare function defaultMetadata(name: string, options?: {
+    capabilities?: MemoryProviderMetadata["capabilities"];
+    relevanceRanking?: boolean;
+    backend?: Record<string, unknown>;
+}): MemoryProviderMetadata;
+
 interface CreateTaskInput {
     objective: string;
     project?: string;
@@ -2702,6 +2793,6 @@ declare class ProjectStores {
     constructor(directory?: string);
 }
 
-declare const OMNINODE_VERSION = "2.0.0-alpha.7";
+declare const OMNINODE_VERSION = "2.0.0-alpha.8";
 
-export { AgentAdapterRegistry, type AgentConfig, type AgentConfigYaml, type AgentDescriptor, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigYaml, type ArtifactKind, type ArtifactPayload, type AskedQuestion, type AuditAction, type AuditEvent, type AuditSink, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatStreamChunk, type ChatUsage, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, ConsoleLogSink, type CreateTaskInput, type CwdValidation, DEFAULT_MAX_OUTPUT_BYTES, type DecodeResult, type DiscoveryResult, type EnvPolicy, type EnvelopeMeta, type ExecutionRecord, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingSeverity, type FindingSource, type HelloResult, HeuristicPlanner, type HttpRequestOptions, type HttpResponse, type IAgent, type IAgentAdapter, type IChatProvider, type IMemoryProvider, type IPipelineExecutor, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, type LoadConfigOptions, LocalMemoryProvider, type LogLevel, type LogSink, Logger, type LoggerOptions, MAX_MESSAGE_BYTES, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryQuery, type MemoryScope, MemoryService, type MessageEnvelope, type Modality, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelPlanner, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, PROTOCOL_V2, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunAttempt, type PipelineRunFilter, type PipelineRunOptions, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type Plan, type PlanFilter, type PlanRequest, type PlanStep, type PlanStore, type PlannerConfigYaml, PlannerError, ProcessAgent, ProcessAgentAdapter, type Project, type ProjectConfigYaml, ProjectStores, type ProtocolAgentToNodeType, ProtocolDecoder, type ProtocolEnvelope, ProtocolError, type ProtocolMessageType, type ProtocolNodeToAgentType, ProtocolSession, type ProtocolViolation, type ProtocolViolationCode, type ProviderAuthentication, type ProviderCapability, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderErrorKind, type ProviderHealth, type ProviderStatus, type ProviderType, type QuestionPayload, type QuestionResponder, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportFilter, type ReportPayload, ReportService, type ReportStore, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, SUPPORTED_PROTOCOL_VERSIONS, type SessionIds, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskPayload, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildChildEnv, buildHello, buildHelloAck, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, decodeMessage, decodeStream, defaultProjectConfigYaml, describeExit, encodeMessage, envelope, expandEnvRefs, extractMessage, extractReportFromText, findConfigFile, isNetworkError, isOmniNodeError, isRetryable, isSupportedProtocol, isTimeoutError, keywords, killTree, kindFromStatus, loadConfig, logger, newMessageId, parseHello, parsePlanJson, parseRetryAfter, pipelineConfigSchema, pipelineStepConfigSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, providerHttpError, providerTransportError, registryKey, requestJson, requireCompletion, resolveApiKey, resolveEnvPolicy, roleConfigSchema, sanitizeChunk, similar, validateEnvelope, validateWorkingDirectory };
+export { AgentAdapterRegistry, type AgentConfig, type AgentConfigYaml, type AgentDescriptor, AgentError, type AgentInfo, type AgentInputMode, type AgentIntegrationType, AgentRegistry, type AgentStatus, type AgentTaskInput, type AgentTaskOutput, type AgentToNodeMessage, type AggregateOptions, type AggregatedFinding, type AggregatedRecommendation, type AppConfig, type AppConfigYaml, type ArtifactKind, type ArtifactPayload, type AskedQuestion, type AuditAction, type AuditEvent, type AuditSink, type ChatFn, type ChatMessage, type ChatRequest, type ChatResponse, type ChatRole, type ChatStreamChunk, type ChatUsage, type CombinedMeta, type CombinedReport, type CombinedReportFilter, type Confidence, ConfigError, ConsoleLogSink, type CreateTaskInput, type CwdValidation, DEFAULT_MAX_OUTPUT_BYTES, type DecodeResult, type DiscoveryResult, type EnvPolicy, type EnvelopeMeta, type ExecutionRecord, type ExtractionMeta, FileAuditLog, FilePipelineRunStore, FilePlanStore, FileReportStore, FileTaskStore, type Finding, type FindingSeverity, type FindingSource, type HelloResult, HeuristicPlanner, type HttpRequestOptions, type HttpResponse, type IAgent, type IAgentAdapter, type IChatProvider, type IMemoryProvider, type IPipelineExecutor, type IPlanner, type IProvider, type JsonDocument, JsonFileStore, type JsonFileStoreOptions, type LoadConfigOptions, LocalMemoryProvider, type LogLevel, type LogSink, Logger, type LoggerOptions, MAX_CONTEXT_CHARS, MAX_MESSAGE_BYTES, type MemoryCategory, type MemoryContextQuery, type MemoryEntry, MemoryError, type MemoryProviderConfig, type MemoryProviderMetadata, type MemoryQuery, type MemoryScope, MemoryService, type MemoryServiceOptions, type MemoryTaskContext, type MessageEnvelope, type Modality, type ModelCapabilities, type ModelFilter, type ModelInfo, ModelPlanner, ModelRegistry, type ModelStatus, type NodeToAgentMessage, OMNINODE_VERSION, OPENAI_COMPATIBLE_TYPES, type OmniHilbrasConnectionResult, OmniHilbrasProvider, OmniNodeError, type OmniNodeErrorCode, type OmniNodeErrorOptions, OpenAICompatibleProvider, PROTOCOL_V2, type PipelineConfigYaml, type PipelineDefinition, PipelineEngine, type PipelineEngineOptions, PipelineError, type PipelineRun, type PipelineRunAttempt, type PipelineRunFilter, type PipelineRunOptions, type PipelineRunStatus, type PipelineRunStore, type PipelineStep, type PipelineStepCondition, type PipelineStepConfigYaml, type PipelineStepKind, type PipelineStepRun, type Plan, type PlanFilter, type PlanRequest, type PlanStep, type PlanStore, type PlannerConfigYaml, PlannerError, ProcessAgent, ProcessAgentAdapter, type Project, type ProjectConfigYaml, ProjectStores, type ProtocolAgentToNodeType, ProtocolDecoder, type ProtocolEnvelope, ProtocolError, type ProtocolMessageType, type ProtocolNodeToAgentType, ProtocolSession, type ProtocolViolation, type ProtocolViolationCode, type ProviderAuthentication, type ProviderCapability, type ProviderConfig, type ProviderConfigYaml, ProviderError, type ProviderErrorKind, type ProviderHealth, type ProviderStatus, type ProviderType, type QuestionPayload, type QuestionResponder, type RememberaConfig, RememberaMemoryProvider, type Report, type ReportFilter, type ReportPayload, ReportService, type ReportStore, type RoleConfigYaml, type RoleDefinition, RoleRegistry, type RunPipelineOptions, SUPPORTED_PROTOCOL_VERSIONS, type SessionIds, TERMINAL_TASK_STATUSES, type Task, type TaskContext, TaskEngine, type TaskEngineOptions, TaskError, type TaskPayload, type TaskResult, type TaskStatus, type TaskStore, type TaskStoreFilter, type WritableLike, agentConfigSchema, aggregateReports, appConfigSchema, authHeaders, buildAgentRegistry, buildChildEnv, buildHello, buildHelloAck, buildPipelineEngine, buildPlanner, buildPlannerContext, buildRoleRegistry, composeTaskText, createAgent, createDefaultChatFn, createMemoryProvider, createProvider, createTaskEngine, decodeMessage, decodeStream, defaultMetadata, defaultProjectConfigYaml, defaultSearch, describeExit, encodeMessage, envelope, expandEnvRefs, extractMessage, extractReportFromText, findConfigFile, isNetworkError, isOmniNodeError, isRetryable, isSupportedProtocol, isTimeoutError, keywords, killTree, kindFromStatus, loadConfig, logger, newMessageId, parseHello, parsePlanJson, parseRetryAfter, pipelineConfigSchema, pipelineStepConfigSchema, plannerConfigSchema, projectConfigSchema, providerConfigSchema, providerHttpError, providerTransportError, registryKey, requestJson, requireCompletion, resolveApiKey, resolveEnvPolicy, roleConfigSchema, sanitizeChunk, similar, validateEnvelope, validateWorkingDirectory };

package/dist/index.js

@@ -191,7 +191,8 @@ var projectConfigSchema = z.object({
     provider: z.string().min(1).default("local"),
     base_url: z.string().url().optional(),
     api_key_env_var: z.string().min(1).optional(),
-    timeout_ms: z.number().int().positive().optional()
+    /** When true, memory failures fail tasks instead of being tolerated (§12). */
+    required: z.boolean().optional()
   }).strict().optional()
 }).strict();
 var appConfigSchema = z.object({
@@ -273,7 +274,8 @@ function toAppConfig(yaml) {
         memory: {
           provider: yaml.project.memory.provider,
           baseUrl: yaml.project.memory.base_url,
-          apiKeyEnvVar: yaml.project.memory.api_key_env_var
+          apiKeyEnvVar: yaml.project.memory.api_key_env_var,
+          required: yaml.project.memory.required
         }
       } : {}
     },
@@ -2202,6 +2204,23 @@ var FileAuditLog = class {
   }
 };
 
+// src/memory/base.ts
+function defaultSearch(provider, text, options = {}) {
+  return provider.retrieve({
+    text,
+    ...options.scope !== void 0 ? { scope: options.scope } : {},
+    ...options.limit !== void 0 ? { limit: options.limit } : {}
+  });
+}
+function defaultMetadata(name, options = {}) {
+  return {
+    name,
+    capabilities: options.capabilities ?? ["retrieve", "store", "search"],
+    relevanceRanking: options.relevanceRanking ?? false,
+    ...options.backend !== void 0 ? { backend: options.backend } : {}
+  };
+}
+
 // src/memory/local.ts
 var STOPWORDS = /* @__PURE__ */ new Set([
   "the",
@@ -2264,9 +2283,27 @@ var LocalMemoryProvider = class extends JsonFileStore {
   constructor(directory) {
     super({ ...directory !== void 0 ? { directory } : {}, fileName: "memory.json" });
   }
-  async query(query) {
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "json-file", deterministicScoring: true }
+    });
+  }
+  search(text, options = {}) {
+    return defaultSearch(this, text, options);
+  }
+  /** @deprecated v1 alias of {@link retrieve}. */
+  query(query) {
+    return this.retrieve(query);
+  }
+  /** @deprecated v1 alias of {@link store}. */
+  write(entry) {
+    return this.store(entry);
+  }
+  async retrieve(query) {
     const entries = await this.readAll();
-    const filtered = entries.filter((entry) => query.scope ? entry.scope === query.scope : true).filter(
+    const filtered = entries.filter((entry) => query.scope ? entry.scope === query.scope : true).filter((entry) => query.category ? entry.category === query.category : true).filter(
       (entry) => query.tags && query.tags.length > 0 ? query.tags.every((tag) => (entry.tags ?? []).includes(tag)) : true
     );
     if (!query.text || query.text.trim().length === 0) {
@@ -2275,7 +2312,7 @@ var LocalMemoryProvider = class extends JsonFileStore {
     const queryKeywords = keywords(query.text);
     return filtered.map((entry) => ({ entry, score: relevanceScore(queryKeywords, entry) })).filter(({ score }) => score > 0).sort((a, b) => b.score - a.score).slice(0, query.limit ?? 10).map(({ entry }) => entry);
   }
-  write(entry) {
+  store(entry) {
     return this.mutate((entries) => {
       const index = entries.findIndex((e) => e.key === entry.key);
       const stamped = {
@@ -2306,11 +2343,40 @@ var RememberaMemoryProvider = class {
     this.env = config.env ?? process.env;
     this.log = log.child({ component: "remembera" });
   }
+  get authenticationConfigured() {
+    return this.apiKeyEnvVar === void 0 || Boolean(this.env[this.apiKeyEnvVar]);
+  }
   headers() {
     const key = this.apiKeyEnvVar ? resolveApiKey({ name: "remembera", apiKeyEnvVar: this.apiKeyEnvVar }, this.env) : void 0;
     return key ? { authorization: `Bearer ${key}` } : {};
   }
-  async query(query) {
+  /** Search delegates to the gateway's relevance query. */
+  search(text, options = {}) {
+    return defaultSearch(
+      this,
+      text,
+      {
+        ...options.scope !== void 0 ? { scope: options.scope } : {},
+        ...options.limit !== void 0 ? { limit: options.limit } : {}
+      }
+    );
+  }
+  metadata() {
+    return defaultMetadata(this.name, {
+      capabilities: ["retrieve", "store", "search", "categories", "tags"],
+      relevanceRanking: true,
+      backend: { kind: "http", baseUrl: this.baseUrl, authenticated: this.authenticationConfigured }
+    });
+  }
+  /** @deprecated v1 alias of {@link retrieve}. */
+  query(query) {
+    return this.retrieve(query);
+  }
+  /** @deprecated v1 alias of {@link store}. */
+  write(entry) {
+    return this.store(entry);
+  }
+  async retrieve(query) {
     const { status, body } = await this.request(`${this.baseUrl}/api/memory/query`, query);
     if (status !== 200) {
       throw new MemoryError(`Remembera query returned HTTP ${status}.`);
@@ -2321,7 +2387,7 @@ var RememberaMemoryProvider = class {
     }
     return entries.map((entry) => this.toEntry(entry)).filter((entry) => entry !== void 0);
   }
-  async write(entry) {
+  async store(entry) {
     const { status } = await this.request(`${this.baseUrl}/api/memory`, entry);
     if (status !== 200 && status !== 201) {
       throw new MemoryError(`Remembera write returned HTTP ${status}.`);
@@ -2356,6 +2422,7 @@ var RememberaMemoryProvider = class {
       content: entry.content,
       scope: scope === "project" || scope === "role" || scope === "task" || scope === "knowledge" ? scope : "knowledge",
       ...Array.isArray(entry.tags) ? { tags: entry.tags.filter((t) => typeof t === "string") } : {},
+      ...typeof entry.category === "string" ? { category: entry.category } : {},
       ...typeof entry.createdAt === "string" ? { createdAt: entry.createdAt } : {},
       ...typeof entry.updatedAt === "string" ? { updatedAt: entry.updatedAt } : {}
     };
@@ -2386,57 +2453,54 @@ function createMemoryProvider(config) {
 }
 
 // src/memory/service.ts
+var DEFAULT_ENTRY_LIMIT = 8;
 var MAX_CONTEXT_CHARS = 4e3;
 var MemoryService = class {
-  constructor(provider, log = logger) {
+  constructor(provider, log = logger, options = {}) {
     this.provider = provider;
     this.log = log.child({ component: "memory", provider: provider.name });
+    this.required = options.required ?? false;
+    this.maxContextChars = options.maxContextChars ?? MAX_CONTEXT_CHARS;
   }
   provider;
   log;
+  required;
+  maxContextChars;
   get providerRef() {
     return this.provider;
   }
   get providerName() {
     return this.provider.name;
   }
-  /** Relevant context for a task objective; empty string when nothing matches. */
-  async gatherContext(query) {
+  get isRequired() {
+    return this.required;
+  }
+  /** Structured, budgeted context for a task (§12 — avoid loading all memory). */
+  async contextFor(query) {
+    let entries;
     try {
-      const entries = await this.provider.query({
+      entries = await this.provider.retrieve({
         text: query.objective,
         ...query.role ? { tags: [query.role] } : {},
-        limit: 8
+        limit: query.limit ?? DEFAULT_ENTRY_LIMIT
       });
-      if (entries.length === 0) return "";
-      const byScope = /* @__PURE__ */ new Map();
-      for (const entry of entries) {
-        byScope.set(entry.scope, [...byScope.get(entry.scope) ?? [], entry]);
-      }
-      const parts = [];
-      for (const scope of ["project", "task", "role", "knowledge"]) {
-        const scopeEntries = byScope.get(scope) ?? [];
-        if (scopeEntries.length === 0) continue;
-        const lines = scopeEntries.map((entry) => `- ${entry.content}`).join("\n");
-        parts.push(`### Relevant memory (${scope})
-${lines}`);
-      }
-      const context = parts.join("\n\n");
-      return context.length > MAX_CONTEXT_CHARS ? `${context.slice(0, MAX_CONTEXT_CHARS)}\u2026` : context;
     } catch (error) {
-      this.log.warn(
-        `Memory query failed (continuing without memory): ${error instanceof Error ? error.message : String(error)}`
-      );
-      return "";
+      return this.handleFailure("retrieve", error, { text: "", entries: [], truncated: false });
     }
+    return this.format(entries);
   }
-  /** Records a finished task's outcome — best-effort. */
+  /** Prompt-ready context text (v1 convenience wrapper). */
+  async gatherContext(query) {
+    return (await this.contextFor(query)).text;
+  }
+  /** Records a finished task's outcome — task history plus "known problems" (§12). */
   async recordTaskOutcome(task) {
     const outcome = task.result?.summary ?? task.result?.error ?? "(no output)";
     try {
-      await this.provider.write({
+      await this.provider.store({
         key: `task:${task.id}`,
         scope: "task",
+        category: "tasks",
         content: `Objective: ${task.objective}
 Status: ${task.status}
 Outcome: ${outcome}`,
@@ -2447,18 +2511,53 @@ Outcome: ${outcome}`,
         (report) => report.findings.filter((finding) => finding.severity === "high" || finding.severity === "critical").map((finding) => ({ report, finding }))
       );
       for (const { report, finding } of significant) {
-        await this.provider.write({
+        await this.provider.store({
           key: `finding:${report.id}:${finding.id}`,
           scope: "project",
+          category: "problems",
           content: `[${finding.severity}] ${finding.title} \u2014 ${finding.detail}`,
           tags: ["known-problem", report.agent]
         });
       }
     } catch (error) {
-      this.log.warn(
-        `Memory write failed (continuing): ${error instanceof Error ? error.message : String(error)}`
+      this.handleFailure("store", error, void 0);
+    }
+  }
+  format(entries) {
+    if (entries.length === 0) return { text: "", entries, truncated: false };
+    const byScope = /* @__PURE__ */ new Map();
+    for (const entry of entries) {
+      byScope.set(entry.scope, [...byScope.get(entry.scope) ?? [], entry]);
+    }
+    const parts = [];
+    for (const scope of ["project", "task", "role", "knowledge"]) {
+      const scopeEntries = byScope.get(scope) ?? [];
+      if (scopeEntries.length === 0) continue;
+      const lines = scopeEntries.map((entry) => {
+        const category = entry.category ? `[${entry.category}] ` : "";
+        return `- ${category}${entry.content}`;
+      }).join("\n");
+      parts.push(`### Relevant memory (${scope})
+${lines}`);
+    }
+    let text = parts.join("\n\n");
+    const truncated = text.length > this.maxContextChars;
+    if (truncated) text = `${text.slice(0, this.maxContextChars - 1)}\u2026`;
+    return { text, entries, truncated };
+  }
+  /**
+   * Failure policy (§12): continue unless memory is explicitly required.
+   */
+  handleFailure(operation, error, fallback) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (this.required) {
+      throw new MemoryError(
+        `Memory is marked required, but ${operation} failed: ${message}`,
+        { cause: error }
       );
     }
+    this.log.warn(`Memory ${operation} failed (continuing without memory): ${message}`);
+    return fallback ?? { text: "", entries: [], truncated: false };
   }
 };
 
@@ -2470,7 +2569,11 @@ function createTaskEngine(config, log = logger, directory) {
     agents,
     roles,
     store: new FileTaskStore(directory),
-    ...config.project.memory !== void 0 ? { memory: new MemoryService(createMemoryProvider(config.project.memory), log) } : {},
+    ...config.project.memory !== void 0 ? {
+      memory: new MemoryService(createMemoryProvider(config.project.memory), log, {
+        required: config.project.memory.required
+      })
+    } : {},
     audit: new FileAuditLog(),
     log
   });
@@ -3552,7 +3655,11 @@ function buildPipelineEngine(config, log = logger) {
     agents,
     roles,
     store: new FileTaskStore(),
-    ...config.project.memory !== void 0 ? { memory: new MemoryService(createMemoryProvider(config.project.memory), log) } : {},
+    ...config.project.memory !== void 0 ? {
+      memory: new MemoryService(createMemoryProvider(config.project.memory), log, {
+        required: config.project.memory.required
+      })
+    } : {},
     audit: new FileAuditLog(),
     log
   });
@@ -3590,7 +3697,7 @@ var ProjectStores = class {
 };
 
 // src/version.ts
-var OMNINODE_VERSION = "2.0.0-alpha.7";
+var OMNINODE_VERSION = "2.0.0-alpha.8";
 export {
   AgentAdapterRegistry,
   AgentError,
@@ -3607,6 +3714,7 @@ export {
   JsonFileStore,
   LocalMemoryProvider,
   Logger,
+  MAX_CONTEXT_CHARS,
   MAX_MESSAGE_BYTES,
   MemoryError,
   MemoryService,
@@ -3655,7 +3763,9 @@ export {
   createTaskEngine,
   decodeMessage,
   decodeStream,
+  defaultMetadata,
   defaultProjectConfigYaml,
+  defaultSearch,
   describeExit,
   encodeMessage,
   envelope,