# How Knosy works
No magic here. This page walks through what Knosy actually does at the moments that matter: when a session starts, when it learns a memory, and when your team shares context. Each section ends with the fine print for readers who want the exact mechanics.
## The integration [#the-integration]
Connecting a host adds one clearly marked Knosy entry to that host's configuration, after a timestamped backup. That entry runs at the host's official session events and is what tells Knosy a session started. Disconnecting removes exactly that entry and nothing else.
* Knosy listens to two documented hooks. `SessionStart` fires when a session begins, resumes, clears, or compacts, and is where context normally loads; a Claude fork counts as a new session. `UserPromptSubmit` is the fallback: it performs one initial injection only when scope selection couldn't finish before the first prompt, and it never re-injects context on later messages.
* The entry is merged structurally into the existing configuration: other hooks are never reordered or removed, the write is atomic, and the result is verified with a handshake before Knosy reports the integration as connected.
* The wait is strictly bounded, budget inside budget: the host gives Knosy's entry 130 seconds, the bridge answers within 125, and the scope gate itself resolves within 120. Nothing extends these, not even interaction.
## The local bridge [#the-local-bridge]
The hook itself is a tiny bundled program. It talks to the Knosy desktop app over a private, local-only channel and then gets out of the way. Nothing listens on the network, ever.
* On Windows the channel is a named pipe owned by your user session; on macOS, a Unix socket in a private, owner-only directory. Remote clients are rejected outright.
* Messages are versioned, length-prefixed JSON, capped at 64 KiB each. Malformed, oversized, or unknown-version frames are rejected.
* Every request is authenticated with a per-installation random key kept in the operating system's protected storage, and signed proofs bind the request to the exact process on both ends.
* Every failure fails open: if the desktop app is gone, busy, or incompatible, the hook resolves immediately and your prompt continues without the wait.
## Your first prompt, step by step [#your-first-prompt-step-by-step]
If Knosy isn't running, the entry finds nobody to tap and your prompt goes through immediately. Details in [The scope picker](/docs/concepts/scope-picker).
## Where the context comes from [#where-the-context-comes-from]
* Each scope (Private, your Team, each Space) has one instructions file that loads automatically when a session starts.
* Every other file you've added is reference material: synced and searchable, read only when the session actually needs it.
* A session keeps its scope through resume, clear, and compact, because Knosy remembers which scope each session ID uses. That mapping holds identifiers only, never content.
- The instructions file is `AGENTS.md`, one per scope. You may keep an `AGENTS.local.md` beside it: it loads right after, stays on your machine, and never syncs.
- Size guidance is measured in characters: 1,500 for Personal, 2,500 for Team, 4,000 for a Space, and 8,000 for the active combined set. At 100% you get one advisory warning naming the responsible file; nothing is ever truncated or blocked.
- Files are read atomically at session start. Knosy keeps no snapshots and never touches the host's transcript.
- During a session, the AI can reach the rest of your registered context through Knosy's own tools: search your context, read a specific file, and search memories, all bounded and scoped to what the session is authorized to see.
## How a memory is born [#how-a-memory-is-born]
* Capture takes only your prompts and the final answers. Extraction runs in small local batches: after about 90 seconds of quiet, at session end, after eight turns, or at a size cap. An explicit "remember this" is processed immediately.
* Each batch is one call to a bundled provider runtime in a sealed configuration: a single turn, a strict output schema, no tools, no file or network access, and a short timeout.
* The runtimes are the official Claude and Codex ones, bundled with Knosy and reusing the logins you already have. Provider packs download when you connect, with hash-verified, signed, atomically activated installs, and their versions are pinned to each Knosy release.
* The redacted local queue is deleted after successful extraction, or after seven days. It never syncs.
* Search runs behind the Knosy API: your authorization is checked before any memory store is queried, and every result carries its provenance, who it came from, and where.
## How your team shares context [#how-your-team-shares-context]
* The visible root is the `~/Knosy` folder. Knosy's own technical state lives in the platform's application-data directory, out of your way.
* Importing a file from elsewhere copies it into `~/Knosy`; the managed copy becomes the active one and the original is never watched.
* Files must be UTF-8 plain text. Binaries and other encodings are rejected with a clear error, never half-supported.
* The server keeps file metadata and permissions in a database and file content in object storage, holding only the current content, its revision hash, and your last-sync hash. There is no history or rollback.
## The honest edges [#the-honest-edges]
* Knosy Cloud stores the current version of shared files and memories, not their history. See [Beta](/docs/beta).
* Who can publish, review, and manage is governed by your team's [roles and permissions](/docs/permissions).
* Everything this page describes crossing to the cloud, and everything that never does, is spelled out in [Privacy](/docs/privacy).