Add local-first memory and synchronized team knowledge

docs/local-memory.md

@@ -0,0 +1,98 @@
+# Local memory and shared knowledge
+
+Bees keeps durable memory on desktops. Bees Server supplies existing membership,
+ownership and connection grants. The existing TLS peer transport carries selected
+team knowledge directly, or through the live encrypted relay. No cloud memory
+database, embeddings upload, or credential replication is introduced.
+
+## Five parts
+
+| Part | Durable source | Behavior |
+| --- | --- | --- |
+| Thread brief | `context` in the thread document | Goal, constraints, decisions, completed work, questions, next steps and artifact references survive restarts and explicit thread transfers. |
+| Curated knowledge | `knowledge` in the owning team's SQLite document | Reusable statements carry source references, evidence status, author, revision and dates. |
+| Desktop synchronization | Existing team owner plus local `bees_knowledge_outbox` | Authorized desktops submit changes and retrieve versioned snapshots through ThreadPeer. |
+| Operational state | Existing run records, extended with `assignments` | Runtime execution status is separate from the parent's acceptance of a handoff. |
+| Broader scopes | Account preferences, thread candidates and explicit team publications | Personal preferences stay local to the account. Company knowledge reaches only selected teams in the same organization. |
+
+## Learning and retrieval
+
+`bees_propose_memory` cites a message, current user request, successful tool call,
+or verified attachment in the current thread. The runtime resolves the source and
+records its digest. A successful tool result proves provenance, not the truth of a
+paraphrased claim. Such claims remain unverified thread candidates until a person
+chooses **Keep for team**.
+
+Complete, verbatim, non-question user decisions and conventions can be retained
+automatically with `share=true`, subject to the team's learning policy. They are
+labeled **User-stated**, never automatically labeled verified. The same mechanism
+works in Chat and workflow stages. A proposal can identify the team memory it
+corrects; the expected revision prevents overwriting a newer correction.
+
+Finished answers are no longer retained wholesale. Old Hindsight outcomes remain
+available locally as legacy, unverified data; they are not promoted or shared
+automatically.
+
+Hindsight is an optional local search index of curated knowledge. Its per-device
+banks remain separate. Index documents contain the stable knowledge ID and
+revision. Recall validates the document against the current local record and
+returns the canonical statement rather than trusting a stale or synthesized
+claim. Pending corrections, forgotten records and old revisions cannot surface
+through this adapter. Local text search continues while the model or index is
+unavailable. Existing explicitly configured custom Hindsight endpoints remain
+supported and continue receiving the indexed content and queries.
+
+Prompt construction budgets the recent conversation and selected knowledge.
+Older messages remain in storage; the brief helps bridge context-window limits.
+Memory is supplied as fallible data, not instructions or authorization.
+
+## Sharing and conflicts
+
+The team owner client orders changes using the existing single-writer team
+document and ownership epoch. This reuses the existing verified team snapshot
+and transfer protocol rather than introducing a second distributed authority.
+
+Each operation has a stable ID. Repeated deliveries are deduplicated. Edits use
+the expected record revision; conflicts remain in the submitting desktop's outbox
+until discarded and resubmitted against the current record. Pending edits and
+deletions immediately suppress the old statement on that desktop.
+
+Version checks avoid returning unchanged snapshots. A newly authorized desktop
+can discover team knowledge through its directory roster. Readers can receive
+knowledge; editors can contribute; only the author or team owner can change an
+existing record. The owner alone controls automatic learning policy. Current
+connection grants and ownership epochs gate incoming exchanges.
+
+Deletion retains a content-free tombstone so an offline desktop cannot reintroduce
+the old statement. Accepted knowledge and tombstones are part of the team
+checkpoint when team ownership transfers. Private candidates and the thread
+brief travel only with an explicit transfer of their thread. Personal preferences
+are neither included in checkpoints nor injected into shared thread execution.
+
+Company publication records retain a source link and an explicit audience. Source
+edits, deletions, and removal of a destination propagate to published copies.
+Publication requires access to both teams in the same organization. A published
+copy is edited at its source rather than silently diverging.
+
+When the owner desktop is offline, existing local knowledge remains usable and
+new changes queue locally. Both endpoints must eventually be online for exchange.
+Fresh server authorization is still required for shared execution and peer grants;
+this feature does not weaken existing execution fencing. Revocation stops future
+authorized exchanges; it cannot erase information already read by another person.
+Publication propagation also requires retained write access to each destination.
+
+## Modules and migration
+
+New modules are `thread-context.js`, `thread-knowledge.js`,
+`thread-memory-sync.js`, and `thread-memory-tools.js` in
+`dsh-runtime/plugin/lib/`. They extend the existing store, client, runner,
+delegation, activity tracking and local Hindsight adapter. Memory settings expose
+curated records, candidates, private preferences, publication destinations,
+conflicts, and local index configuration. Thread Context displays the durable
+brief and local proposals.
+
+All new document fields are optional. Existing notes, histories, credentials and
+provider settings remain in place. The outbox table is created idempotently in
+each account's existing SQLite database. Current document limits also bound
+knowledge storage; reaching the limit rejects a change instead of silently
+dropping knowledge or deletion tombstones. No server or Rust migration is needed.