Edicts

Ground truth for AI agents.

Edicts is a small TypeScript library for storing cheap, verified facts that your agent should treat as non-negotiable. Instead of stuffing long documents into every prompt or building a full retrieval stack for a handful of critical facts, you keep a compact set of assertions in YAML or JSON, render them into prompt context, and give agents optional tool access for runtime reads and updates.

Docs: https://edicts.ai
License: MIT

The problem

Agents are surprisingly good at sounding certain about things they should never improvise: launch dates, product limitations, compliance constraints, internal naming, migration status, embargoes, and "definitely not" statements. Those facts are usually tiny, high-value, and expensive to get wrong. Edicts gives you a lightweight ground-truth layer for exactly that class of information.

30-second quick start

Install the package:

npm install edicts

Create an edicts file:

npx edicts init
# Creates ./edicts.yaml with a starter template

Or write one manually:

version: 1
edicts:
  - text: "Product v2.0 launches April 15, NOT before."
    category: product
    confidence: verified
    ttl: event
    expiresAt: "2026-04-16"

List it with the CLI:

npx edicts list

Inject it into your system prompt:

import { EdictStore } from 'edicts';

const store = new EdictStore({ path: './edicts.yaml' });
await store.load();

const edicts = await store.all();
const rules = edicts.map(e => `- [${e.category}] ${e.text}`).join('\n');

const systemPrompt = `You are a helpful assistant.

## Standing Rules
${rules}

Treat these as ground truth. Never contradict them.`;

That is the whole idea: small verified facts, cheap enough to include all the time.

Why Edicts?

• Built for high-value facts, not conversational memory. Edicts is for "this is true" and "this is not true," not giant transcript recall.
• Tiny context footprint. A few critical edicts cost tens of tokens, not thousands.
• Time-aware by default. Ephemeral and event-based facts expire automatically.
• Framework-agnostic. Use it with any LLM stack that can prepend text or expose tools.
• Simple storage. YAML or JSON on disk, atomic writes, optimistic concurrency, minimal dependencies.

Key features

• YAML and JSON storage
• Automatic expiry pruning on load/render
• Sequential IDs (e_001, e_002) or stable user-provided keys
• Key-based supersession for facts that change over time
• Token budget enforcement with rollback on overflow
• Category allowlists and category soft limits
• Built-in plain, markdown, and JSON renderers
• Optional custom tokenizer and custom renderer hooks
• Full CLI for all store operations
• First-party OpenClaw plugin for automatic prompt injection

Installation

npm install edicts

For CLI usage, install globally:

npm install -g edicts

Requirements:

• Node.js >= 20
• TypeScript recommended, but not required

Core API

import { EdictStore } from 'edicts';

const store = new EdictStore({
  path: './edicts.yaml',
  tokenBudget: 4000,
  categories: ['product', 'compliance', 'operations'],
});

await store.load();

await store.add({
  text: 'The public launch date is April 15, NOT earlier.',
  category: 'product',
  confidence: 'verified',
  ttl: 'event',
  expiresAt: '2026-04-16T00:00:00.000Z',
});

const edicts = await store.all();
const stats = await store.stats();

The primary interface is the EdictStore class. See the full API reference.

CLI

The CLI covers all store operations:

edicts init                          # Bootstrap edicts.yaml
edicts add --text "..." --category product  # Add an edict
edicts list                          # List active edicts
edicts get <id>                      # Get a single edict
edicts remove <id>                   # Remove an edict
edicts update <id> --text "..."      # Update an edict
edicts search <query>                # Search by text
edicts stats                         # Store statistics
edicts review                        # Health check (stale, expiring)
edicts export --output backup.yaml   # Export store
edicts import backup.yaml            # Import from file

Full CLI reference.

OpenClaw integration

If you use OpenClaw, install the plugin for automatic prompt injection:

openclaw plugins install openclaw-plugin-edicts
openclaw gateway restart

Every agent session will automatically receive your edicts as ground truth — no code changes needed. The plugin also registers tools so agents can read, create, and manage edicts at runtime.

See the OpenClaw integration guide.

Documentation

Full docs at https://edicts.ai:

• Installation
• Quick Start
• Best Practices
• Memory Hierarchy
• Configuration
• YAML Schema
• API Reference
• CLI Reference
• Generic Integration
• OpenClaw Integration

Contributing

PRs are welcome. Please read CONTRIBUTING.md before sending changes.

License

MIT