Knowledge and state

Use the smallest state primitive that matches the lifetime of the information. Conversation history, long-term memory, typed application records, execution scratch space, and configuration are different things.

Typed entities

@noir-agent/agent/entities provides reviewed entity definitions, owner-scoped CRUD, optimistic revisions, pagination, and Memory/Postgres stores.

import {
  defineEntity,
  deterministicEntityId,
  postgresEntityStore,
} from '@noir-agent/agent/entities'

const project = defineEntity({
  name: 'project',
  description: 'A project the agent may read and update.',
  schema: projectSchema,
})

Entity owners may be agent, installation, user, or conversation scoped. Authorize that exact owner before lookup. deterministicEntityId() is useful when an external natural key should map to one record. Revision checks prevent a stale tool call from overwriting a newer update.

Execution blackboard

The entity module also provides a blackboard store for cross-step scratch state inside one execution. It is not long-term memory and is not shared across runs. Use it for intermediate IDs, plans, or evidence that should not enter the prompt repeatedly.

Post-turn learning

@noir-agent/agent/learning extracts candidate facts after a completed turn and writes only validated categories into the configured memory scope. validateLearningCandidates() rejects malformed, oversized, unsupported, or unsafe facts before storage.

The extractor is host-injected. Learning never treats the model’s candidate as trusted data, and it must inherit the same actor or conversation scope used by recall. Use expiry from the originating fact when one exists.

Skills

@noir-agent/agent/skills installs immutable local skill bundles with a manifest, version, prompt files, dependencies, and secret requirements. defineSkill() creates a reviewed definition; skillRef() and parseSkillRef() address an exact version.

Skills are instructions and optional capability dependencies. They do not create provider credentials or bypass tool policy. Keep prompt files bounded and install only versions committed with the application.

Capability registry

@noir-agent/agent/registry stores reviewed capability manifests and explicit grants. capabilityManifestDigest() binds a manifest to its content. loadInstalledCapability() requires the installed digest, current review, a local factory, dependencies, and grants to match before execution.

The registry is a self-hosted primitive, not a hosted marketplace. Your application decides who may review, install, upgrade, or revoke a capability.

Choose the right primitive

Verify

Test owner isolation, pagination bounds, stale revision rejection, invalid learning candidates, skill digest mismatch, missing dependency grants, and registry rollback. Never retrieve user-facing state with an unbounded all-record scan.