Store knowledge once, load it the right way every time

• Knowledge Library
• Rules, References, Skills, Commands, History
• Memory
• Notes

Unified storage doesn't mean unified injection. Rules, References, Skills, Commands, Notes, Memory, and History never enter model context the same way.

flowchart TB
  Library["Knowledge Library"]
  Library --> Rules
  Library --> References
  Library --> Skills
  Library --> Commands
  Library --> Notes
  Library --> Memory
  Library --> History
  Rules --> Always["Always in effect"]
  References --> Demand["Read on demand"]
  Skills --> Match["Explicit or matched trigger"]
  Commands --> Invoke["Triggered by command"]
  Notes --> Retrieve["Relevance retrieval"]
  Memory --> Retrieve
  History --> Review["Reviewed on demand"]

• Agent & Tasks
• Context Engineering

Knowledge Library: manage everything in one place#

Knowledge Library is the management surface for kxen's unified knowledge system. It stores every knowledge type in one entry format, while keeping each type's own loading and invocation semantics.

Where you manage it#

Find it in Settings' Knowledge Base (OKF) area. The page first splits by scope — project and personal — then groups by kind.

Current kinds: rule, reference, skill, command, note, memory, history.

Scope#

Project scope lives in the Workspace's knowledge directory, and can be shared through Git. Personal scope lives in your own knowledge directory, and applies across every project.

When the same kind and slug exist in both scopes at once, the project entry overrides the personal one — the UI marks any personal entry that's currently shadowed by a project version.

What you can do#

• Enable or disable an entry.
• Move an entry between project and personal scope.
• Delete to the system trash.
• Manually write a Note.
• Preview exactly what knowledge would be injected into the next system prompt.

Enabling or disabling immediately affects the next knowledge render. Moving scope keeps the entry's kind — it never silently turns a Rule into a Note. The move-transaction claim lives in the app's private data directory, never accepting a path or recovery state a project file provides; a cross-filesystem move uses staging plus a durable commit, so an abnormal exit during that move recovers from the same claim instead of treating source and target as both committed.

Automatic consolidation boundary#

Automatic knowledge consolidation acquires a single lease per Session, and builds its snapshot from that Session's monotonic message_revision and a message-content cursor. On completion, it only checkpoints the revision/cursor for the exact snapshot it processed — any new message or history rewrite that produces a different cursor during processing still goes into the next round. Multiple writes or a history rewrite within the same millisecond are never mistaken for already-processed by timestamp alone.

If a durable attempt shows a provider request may have started but its result never landed, the background job marks it provider_result_unknown and stops retrying on its own. Knowledge Library then shows "automatic consolidation pending confirmation," including the Session, a stable reason, and whether the UNKNOWN usage has already settled durably. That state is never an empty result, and never counted as a success.

"Confirm UNKNOWN and skip this snapshot" is an explicit two-step action. After the backend re-acquires that Session's same consolidation lease, it durably settles the attempt's usage, checkpoints the skipped message cursor, and deletes the attempt, in that order. Any already-known token observation settles at its known value; a missing observation is recorded as UNKNOWN, never as zero. If settlement or checkpointing fails, the attempt is kept and an error returned — the recovery action itself never calls the provider again. Once it succeeds, the same cursor is never billed again, and the Session can enter the next round of automatic consolidation once it produces a new message cursor.

A legacy attempt created before this upgrade, lacking an exact revision/cursor, can't be safely checkpointed. Confirming its UNKNOWN only settles usage and deletes the old claim — it never substitutes the confirmation-time cursor for the old one, so any message added after the block still enters consolidation in the next round.

Deleting a Session first establishes a tombstone, then waits for any active run and consolidation lease to converge. The deletion window admits no new Note writes; an attempt that already crossed the provider boundary is only allowed to settle its usage against the existing result. Choosing "don't consolidate" still durably settles the blocked attempt's UNKNOWN usage before the recovery manifest is built, and only the cleanup phase deletes the claim afterward — it never calls the provider again, and never drops unknown usage as zero. Choosing "delete and consolidate" stops the deletion and preserves recovery state if distillation, result persistence, or revision validation fails.

Trust boundary#

An untrusted Workspace's project knowledge can still appear in the index and management UI, but its body is never injected into the model, and it never opens the project's Skill and Command execution surface.

The exact activation rule for each capability lives on its own page — Knowledge Library itself doesn't change an entry's semantics.

Memory: retrieve stable facts relevant to the current task#

Memory holds stable information distilled from past Sessions and long-running work. It's for recovering relevant facts in a new task — not for replaying a full conversation.

Where it comes from#

Memory can come from:

• The agent actively saving it through the knowledge tool.
• You explicitly choosing "delete and consolidate personal knowledge" when deleting a Session.
• Background consolidation you've explicitly enabled in personal settings.
• Long-lived entries you maintain yourself.

Automatic knowledge consolidation is off by default, only ever reads your personal configuration, and only ever writes to personal scope. Once enabled, it scans active Sessions from the last 24 hours every 30 minutes, sending each one's most recent 20 lines of text and injected context to that Session's explicitly selected model, or to its Workspace's chat role routing when none was selected. Routing, MRM limits, and the circuit always come from the Session's own Workspace — switching the foreground Workspace never changes them. Deleting a Session deletes directly by default; choosing to consolidate shows you the target provider, and a provider failure keeps the Session and shows an error instead of silently deleting it. Automatic consolidation can never write a failed output as fact, and can never silently override project Rules.

Retrieval#

Memory and Notes are retrieved together:

1. Generate a query from the involved files and their descriptions.
2. Rank by text relevance using BM25.
3. Add semantic recall once embedding is configured.
4. Weight project scope, newer entries, and conflicting versions accordingly.
5. Deduplicate by slug and keep the most relevant entries.

With no involved files, it falls back to the 3 most recently dated entries. A single injected body is capped at 500 characters, so long-term knowledge never unboundedly occupies context.

Conflict handling#

Entries that are highly similar in content but disagree on facts are treated as potential conflicts, and the older version gets down-weighted. Project entries outrank personal ones, but Memory still can never override Safety or an active project Rule.

Scope#

Project Memory lives at file:///path/to/workspace/.agents/memory/. Personal Memory lives at file:///Users/you/.agents/memory/.

Project Memory should only hold facts the team genuinely needs long-term. Before the agent writes to project scope through the knowledge tool, it must show a description and content preview and get your Approval — without an approval channel, it fails closed. Personal preferences, individual tool habits, and cross-project experience belong in personal scope.

Compared to Session#

Session is the full execution history. Memory is stable knowledge selected out of that history. Simply deleting a Session doesn't automatically generate Memory — only explicitly choosing "delete and consolidate personal knowledge" runs a distillation, so important information should be consolidated deliberately.

Notes: capture atomic, maintainable knowledge#

A Note is a short knowledge entry you can save directly. It fits facts that will keep being useful in future tasks, without deserving promotion to a hard rule.

Where you write them#

Write a Note manually from Settings' Knowledge Base (OKF) area — choose a scope, type, description, and body.

The agent can add a Note through the knowledge tool too. Personal scope is the default choice; only stable facts the team needs to share belong in project scope.

Note types#

• correction: fixing a mistaken understanding.
• convention: a stable convention.
• pitfall: a trap that's easy to repeat.
• preference: your preference.
• note: long-lived information that doesn't fit the above.

How to write one#

One Note expresses exactly one fact. Its description drives retrieval and listing; its body carries what a future task can use directly.

Don't turn an execution log, a failed output, a temporary plan, or an unconfirmed inference into a Note. When a fact changes, update the original entry rather than leaving conflicting versions around.

Scope#

A project Note lives at file:///path/to/workspace/.agents/notes/, shareable through Git. A personal Note lives at file:///Users/you/.agents/notes/, used across projects.

A project entry with the same slug overrides a personal one. Moving scope keeps its kind and content unchanged.

How it gets injected#

Notes share Memory's relevance retrieval. It's never an always-injected Rule, and never a Skill that needs explicit invocation — see the retrieval mechanics in Memory above.