Rules (Beta)
A Rule is a durable constraint an Agent must follow when its conditions hold, such as an obligation, prohibition, or boundary. OpenViking compiles source material in batches into self-contained rules, then retrieves applicable rules for the current task so the Agent can check them before acting or answering.
The current Beta supports explicit imports and on-demand recall. Ordinary session commits do not automatically compile rules, and there is no built-in flow that forcibly injects them on every user message or at the start of every session.
How rules differ from other context types
| Type | Question it answers | Example |
|---|---|---|
| Resource | What source material can I consult? | An agreement, code repository, or technical specification |
| Memory | What facts, preferences, and experience are known? | A user prefers concise answers; a project uses a particular framework |
| Skill | How do I carry out this kind of task? | Repository review steps or a report generation method |
| Rule | Under which conditions must I do something, or refrain from doing it? | A repository declaring itself open source must provide a locatable license text |
Rules take priority over ordinary Memory. They are a separate context type with dedicated compilation and search interfaces, even though they live under the user's memories/rules/. Importing an agreement or standard as a Resource stores the material; its mandatory constraints still need explicit compilation.
Preferences, suggestions, facts, examples, and one-off tasks should not become Rules. Compilation must not turn “should” into “must” or weaken “must” and “must not.”
Use cases
| Scenario | Rule sources | How the Agent uses them |
|---|---|---|
| Legal agreement review | Obligations, prohibitions, and exceptions in user-provided agreements | Retrieve constraints using the review object and known facts, then check the text or planned actions |
| Coding standards checks | Team development standards and review requirements | Retrieve rules using the repository, changes, and execution stage, then check the proposed changes |
| Open-source license checks | User-provided license requirements | Read repository declarations and license files, verify triggering conditions, and record evidence |
For example, “When a repository declares itself open source, it must provide an explicit, complete, and locatable project license text” can produce:
| Field | Example |
|---|---|
content | When a repository declares itself open source, it must provide an explicit, complete, and locatable project license text. |
applies_when | The repository declares itself open source. |
exception | Empty string: the source specifies no exception. |
| Scenario | Project license review |
Topic similarity does not establish applicability. Agents must verify conditions using readable evidence. A rule still applies when its requirement is already satisfied.
How rules are organized
Each Rule holds one complete constraint that can be updated or withdrawn independently. It includes content, applicability conditions in applies_when, an exception, sources and exact evidence, a stable atomic_id, a revision, and a status. Empty applies_when means the rule applies everywhere except its exception.
A Scenario describes situations in which rules may apply, such as “Project license review,” and groups rules for retrieval. It is not a source document title: one document can produce multiple Scenarios, and several sources can share a Scenario.
viking://user/<user_id>/memories/rules/
└── repository-license/
├── abstract.md # Scenario description
└── project-license.md # Complete Rule recordCompilation flow
Rule text, files, directories, or URLs
→ Read existing resources, or parse and ingest new sources
→ Recall existing active / paused rules
→ Compiler extracts constraints and proposes mutations
→ Validate structure, targets, exact evidence, and retained requirements
→ Write Rules / Scenarios and refresh indexes asynchronouslyThe Compiler preserves obligation strength, conditions, exceptions, thresholds, and units, separating rules that can be maintained independently. An evolving rule updates its existing record; an explicit full replacement creates a new identity and archives the old record. Fully covered input needs no duplicate write. Material ambiguity or rejected input is recorded with reasons and creates no Rule.
The compilation interface first returns a background task. Inspect the actual mutations after completion. The index task associated with the writes may still be processing; confirm it completes before use as well. See Rule validation (Beta) for the steps.
Search and execution flow
Agent submits the task goal, object, planned actions, and known facts
→ Semantically recall potentially relevant Scenarios
→ Jev filters Scenarios judged unrelated with high confidence
→ Read their active rules and judge conditions and exceptions
→ Return structured rules and complete constraint text
→ Agent checks every rule and constrains its actions or answerSearch returns rules scoring at least 0.65 by default, with no fixed Top-K in the public interface. For non-empty conditions, an exception vetoes a rule only if its score reaches the threshold and strictly exceeds the applicability score. With empty conditions, an exception reaching the threshold is sufficient to veto.
If Jev is unconfigured, unavailable, or returns invalid results, affected candidates pass through. Failed Rule judgment returns judge="pass", probability=1.0, and a warning; this score means pass-through, not an estimated probability. Agents must still check conditions and exceptions.
rendered supplies an application protocol and complete rule blocks for the Agent. Search determines whether rules apply; the Agent uses task evidence to decide whether they are satisfied, violated, or undetermined. Empty results do not prove the library contains no relevant constraints. delivery.complete only means matched rules were delivered in full, not that the entire library was recalled.
Lifecycle
| Status | Compilation candidate | Search candidate | Meaning |
|---|---|---|---|
active | Yes | Yes | Enabled |
paused | Yes | No | Suspended and retained without expiry cleanup |
archived | No | No | Logically deleted; eligible for cleanup after retention |
Explicit requests to pause or disable use PAUSE; reactivation of paused rules uses RESTORE. Deletion, discard, or moving to the recycle bin uses ARCHIVE. UPDATE preserves the current status. The compilation interface cannot restore archived rules.
Archived records store archived_at; repeated archival does not reset it. Periodic cleanup is enabled by default with 30-day retention. Physical removal occurs during a scan after retention expires; see server Rules configuration.
Related documentation
- Rule validation (Beta): batch compilation, recall, and Agent checks
- Rules API (Beta): parameters, responses, and failures
- VikingBot Installation and Configuration: the rule search tool
- Context Types: resources, memory, and skills