Knowledge and decisions

Knowledge is what the company has written down for people and agents to reuse: a policy, a fact about a customer, a decision and its reason. Each piece is an entry. Every entry says who wrote it, when, how sure they were and what it rests on, so a reader can judge it. When an agent writes an entry for others to read, it usually waits for a person to accept it first.

This page covers shared knowledge, decisions logged in threads, and the private memory agents keep after their runs. The steps use the demo company (see Quickstart). What is not possible yet is listed at the end.

Words used on this page#

Three kinds of memory#

What an entry shows#

The card on the Knowledge page shows:

How knowledge gets in#

Written by agents#

An agent writes knowledge when its plan includes a remember step. Whether the entry needs a person depends on its scope and evidence:

A team entry belongs to the team of the person the agent acts for: a Support Agent run for Maya writes for the Support team. An entry is raised to the most sensitive data class of what it cites, and an agent's entry also to the most sensitive data the run had read.

Written by the Distiller#

If your company uses context capture, the Distiller reads each team's week once every seven days and proposes team knowledge: a Decision entry for each decision taken in the team's threads, Framework, SOP and Enablement entries from the artifacts of the team's Context thread, and an insight when the same rejection reason comes up twice. Everything it proposes is quarantined at confidence 70 and owned by the team. See Context capture.

The demo company has no context sources set up, so there is no Context thread and the Distiller proposes nothing until an admin adds a source.

Written by people#

A person's own entry is accepted at once, in any scope, unless it cites captured context:

• Governance, Knowledge tab, Remember something saves an org entry at confidence 100. Any signed-in person can use it.
• Log decision in a thread (see Log a decision).

Team, private and partner entries can only be written through the API (see For developers), and team entries only for your own team: Alice in Sales writing for the Support team is refused with "team:support is not a team of alice".

Who may decide#

Accept and Reject on the Knowledge page appear only on entries you may decide. The server checks the same rule.

Agents never decide knowledge.

In the demo, Maya (Support lead), Tom (Support) and Ada (admin) may decide the Support team's entries. Alice and Fiona do not see them at all, and the server refuses them: "policy denied knowledge.accept: fiona is neither a member nor the lead of team:support". Tom is refused an entry whose evidence is a thread he is not in: "policy denied knowledge.accept: tom may not read the evidence thread:...".

When an entry goes into quarantine, an inbox item reaches whoever of these may decide it: the team's lead (team entries), the agent's escalation contact and anyone with the data owner role. In the demo, for a Support Agent entry that is Maya. Tom may decide a team entry but is not told.

Try it in the demo#

The steps below run in order and build on each other. Steps that make an agent do something specific use developer mode, because without a model key the demo runs the stub planner, which does not write or recall knowledge on its own (see Asking agents). With a real model, the agent chooses these steps itself.

Log a decision#

1. Sign in as Maya. Open Threads and choose New thread. Goal: "Refund policy for double charges". Under Participants tick Tom Becker and Support Agent. Choose Create. The thread opens, with you as owner.
2. Choose Log decision (below the message box). The Log a decision sheet opens.
3. Decision: "Refund double charges in full without asking for proof". Why: "The billing log already shows both charges". Topics: refunds, billing. Choose Log decision. The note "Decision logged" appears, the decision card appears in the conversation, and Details lists it under Decisions.

The decision is now also an accepted org entry: "Decision: Refund double charges in full without asking for proof. Rationale: The billing log already shows both charges", confidence 100, topics refunds, billing, decision, with the thread and the decision as evidence. See Decisions in threads.

See an agent recall it#

Asking the Support Agent "A customer was charged twice. Do we ask for proof before refunding?" without a model returns a table of open tickets, not the decision. To see a recall, give the plan yourself.

1. In the same thread, add ?dev=1 to the address and reload. An Explicit plan button appears next to the agent picker.

2. Pick Support Agent in the agent picker and choose Explicit plan. A second box opens under the message box.

3. Write "Check our decisions on refunds" in the message box and paste this into the second box:

   jsonCopy

   {"ops":[
     {"op":"recall","topics":["refunds"],"bind":"k"},
     {"op":"post","kind":"text","body":"Found {{k.length}}. First: {{k.0.content}}"},
     {"op":"output","value":"$k"}
   ]}
   

4. Choose Ask agent. The Support Agent posts "Found 1. First: Decision: Refund double charges in full without asking for proof. Rationale: The billing log already shows both charges". Its run card then shows each entry it read as a table, and ends with "Done".

Recall matches any topic that contains the word you ask for, so refund finds refunds. It returns only accepted, unexpired entries the person the agent acts for may see, best topic match first, then highest confidence. Quarantined, contested and rejected entries are never returned.

Have an agent propose knowledge#

Still in the thread, with developer mode on and Support Agent picked:

1. Message: "Note the Northwind double charge". Plan:

   jsonCopy

   {"ops":[
     {"op":"remember","scope":"team","content":"Northwind was double charged in September; refunded in full","topics":["refunds","northwind"],"confidence":70},
     {"op":"output","value":"noted"}
   ]}
   

   Choose Ask agent. The agent replies "noted". The entry is quarantined for the Support team (confidence below 90, no evidence).

2. Message: "Record the refund approver rule". Plan, with <thread id> replaced by the id at the end of the thread's address:

   jsonCopy

   {"ops":[
     {"op":"remember","scope":"org","content":"Refunds over 100.00 always need an admin","topics":["refunds","fact:refund-approver"],"confidence":95,"evidence":["thread:<thread id>"]},
     {"op":"output","value":"noted"}
   ]}
   

   Choose Ask agent. This entry is accepted at once with no review: confidence 95 and evidence attached.

Accept or reject quarantined knowledge#

1. As Maya, open Inbox. Under Unread you see "Knowledge awaiting review (team): " followed by the entry's id. The item does not open the entry: clicking it only marks it read, and it moves to Everything.
2. Open Knowledge from the side menu. It opens on All. At the top, Waiting for a decision shows a count and the Northwind entry: Quarantined, Team, Fact, "confidence 70", "by Support Agent for Maya Patel", "topics refunds, northwind", with Accept and Reject.
3. Read the entry and open its evidence links if it has any.
4. Choose Accept. The note "Accepted" appears. The entry leaves the waiting list and shows under Facts as Accepted. Agents can read it from now on.
5. To try Reject, have the agent propose another entry the same way and choose Reject on it. There is no confirmation. The note "Rejected" appears and the entry disappears from the page. It is kept as Rejected, but no screen lists rejected entries.

Governance, Knowledge tab offers the same decision under Quarantined. It shows Accept and Reject on every quarantined entry you can see, even one you may not decide; the server then refuses with the "policy denied" message above.

Contest an entry#

Two accepted entries are contested when they are in the same scope, share a topic that starts with fact: and say different things. Entries without a fact: topic are never compared.

1. Sign in as Ada. Open Governance and choose the Knowledge tab. Under Accepted knowledge you can see is "Refunds over 100.00 always need an admin", from the previous section.
2. Choose Remember something. Under What should the organisation remember? write "Refunds over 100.00 need the support lead, not an admin". Under Topics write refunds, fact:refund-approver. Choose Save. The note says "Saved to org memory".
3. A Contested heading appears above Accepted knowledge you can see, with both entries marked Contested, each with Keep this one and Reject.

No one gets an inbox item when a contest starts this way, and the note after saving does not mention it. Check for a Contested list after saving an entry with a fact: topic.

Settle a contest#

On Knowledge the Contested section ("Two accepted entries disagree; a person decides which stands.") shows Accept and Reject. On Governance, Knowledge tab the same buttons read Keep this one and Reject. Who may use them follows Who may decide.

1. Choose Keep this one on "Refunds over 100.00 need the support lead, not an admin". The note says "Kept"; the entry moves to Accepted knowledge you can see.
2. The other entry is still Contested: Keep this one does not reject it. Choose Reject on it.

If you accept the other one instead of rejecting it, the two clash again and both return to Contested. You (the person who accepted) get an inbox item: "Knowledge conflicts with an accepted entry; resolve the contest". Rejecting one of them then leaves the other Contested too; accept it again to settle.

Decisions in threads#

In a thread, owners and approvers see Log decision; contributors do not.

The decision appears in the thread and in its Details (see Threads). At the same moment it becomes an accepted org entry, "Decision: . Rationale: ", at confidence 100, with your topics plus decision and with the thread and the decision as evidence. No one needs to accept it.

Because it is an org entry, everyone in the company can read it, even people who cannot open the thread. In the demo, Alice sees Maya's refund decision under Facts with both evidence links shown as restricted source.

On the Knowledge page a logged decision shows in two places:

• The Decisions tab lists, under Decisions in threads, the decisions of threads you can see, newest first, each linking to its thread. Alice sees none for Maya's thread.
• The org entry itself is listed under Facts, not under Decisions, because it carries the topic decision rather than a kind. So the Decisions tab says "No accepted decisions entries." right above the Decisions in threads list.

A decision cannot be edited or withdrawn, and neither can its entry.

Agent memory#

After every finished run the agent writes one private note: "Finished '' () for Maya Patel." followed by a short account of the result, such as "1 result", with the run as evidence. It is kept for 90 days.

• Whose it is. The note belongs to the person the run acted for, not to the agent. Any agent working for Maya can recall Maya's notes: in the demo, a Knowledge-base writer run for Maya with a recall on the topic episodic returned the notes the Support Agent wrote for her. Tom does not see them.
• Where you see it. Knowledge, Agent memory tab: "What agents noted after their runs for you, kept for their own recall for 90 days. Not company knowledge and not checked by anyone." Each card shows agent memory, its expiry date, "by Support Agent" and the task as evidence. The other tabs leave the notes out.
• How it differs from knowledge. No one reviews it, it never reaches a team or the company, it expires, and the Knowledge page shows no confidence for it.

Agents of the context module (the Curator, the Distiller) write no memory.

Expiry#

An entry can carry an expiry date. Once it passes, the entry no longer shows in lists and agents no longer read it; it is then marked Expired. Today only agent memory has an expiry. There is no way to give a shared entry an expiry from the screen or the API.

The Knowledge page#

You see private entries that are yours, team entries of your teams and of teams you lead, and every org and partner entry. Admins see every team's entries.

Governance, Knowledge tab#

The Knowledge tab on Governance is the review view:

• Remember something: save an org entry (see Written by people).
• Quarantined: entries waiting for a decision, with Accept and Reject, or "Nothing in quarantine."
• Contested: shown only when there are some, with Keep this one and Reject.
• Accepted knowledge you can see: every accepted entry, including your agent memory. Cards here show "by Support Agent" without who it acted for, and evidence as raw references (thread:...) rather than titles.

Not possible yet#

• Seeing or restoring a rejected entry from the screen.
• Editing an accepted entry. Write a new one; give both the same fact: topic if the old one should be contested.
• Setting an expiry on shared knowledge.
• Writing team, private or partner knowledge from the screen (API only).
• Opening the entry from its "Knowledge awaiting review" inbox item.
• Being told when a contest starts from a person's new entry.
• Requiring review of an agent's high-confidence, evidenced shared entry.
• Editing or withdrawing a decision.

For developers#

API#

All under /api, with Authorization: Bearer <token>.

Plan operations (see docs/plans.md in the repository): remember (scope, content, topics, confidence, evidence, team), recall (topics, bind), search (finds accepted knowledge too) and decide (thread approvers only).

Events#

On the Events page, under Knowledge: knowledge_proposed, knowledge_accepted, knowledge_rejected and knowledge_contested (only when accepting an entry starts a clash). A logged decision emits decision_logged, under Threads.

CLI#

In the demo the state file is orchkernel-demo/state.db.

ok brain --state orchkernel-demo/state.db --as maya quarantine          # entries waiting
ok brain --state orchkernel-demo/state.db --as maya recall refunds,billing
ok brain --state orchkernel-demo/state.db --as maya accept <id>
ok brain --state orchkernel-demo/state.db --as maya reject-knowledge <id>