Skip to documentation
Documentation
Documentation
OverviewInstallationQuickstartYour first dayYou were sent a linkWorking with a customerConfigurationTroubleshootingFAQGlossary

Usage

Terminal interfaceCLIStatuslineDashboardAnalytics

Collaborate

DocumentsLessonsSession sharingPicking up tomorrow and handing work overFrom your phoneSession linksSession messagingAsksAsks privacy fact sheetFeedbackEmail from crewkitBlueprintsAgent identitiesMCP server

Configure

AgentsSkillsSkill and agent security scanningRulesCommandsInheritancePlaybooksExperimentsHooksCapture modesSensitive sessionsData residencyTeamSettings mapIntegrations

Workspaces

WorkspacesSet up a workspaceFix a ticket end to endShip a feature with approvalHand off work and set agent settings

API Reference

API OverviewAuthenticationSessions APIResources APIOrganizations APIProjects APIPlaybooks APIExperiments API
Need a hand?Find an answer in troubleshooting.
Loading docs…
CREWKIT / DOCUMENTATION

Lessons

Short rules your team learned from its own repeated corrections, review comments and confirmed discussions, added to later sessions on the same project. What is collected and why, consent, residency and erasure.

Lessons are off for every organization until crewkit turns them on for it, and only on the Team, Business and Enterprise plans. After that, an organization admin or owner gives the two consents in Turning Lessons on. Until crewkit turns them on, the Lessons settings do not appear and every Lessons screen is empty.

A Lesson is a short rule a person on your team wrote or approved, after the same kind of evidence came up for two or more people on a project: a mistake caught in their sessions, a pull request review comment the author acted on, or a confirmed meeting, Slack or email document. Once accepted, crewkit adds it to later Claude Code sessions on that project, so the next session starts with what the team already learned.


Turning Lessons on

Two organization settings control Lessons. Both are off by default, and each is a separate consent. An organization admin or owner turns them on and off in Settings → Organization → Privacy & Telemetry, in the Lessons section.

SettingWhat it allows
Propose Lessons from repeated correctionscrewkit proposes a Lesson when the same kind of mistake recurs on the same file for two or more people.
Add accepted Lessons to sessionsAccepted Lessons are added to later sessions on the same project, and an agent can read them through the MCP get_lessons tool.

Turning either one on asks you to confirm, and the confirmation restates what the acceptable-use policy says about Lessons. The acceptable-use policy describes both settings. Editing, accepting, rejecting or retiring a Lesson, and the get_lessons read, need the signed-in person to have accepted the current version of the policy.


Where a proposal comes from

With the first setting on, crewkit proposes a Lesson from three kinds of evidence:

  • Corrections a person or a reviewer caught. These come from correction detection, from conversations that are not sensitive, not deleted, and not attributed to a private repository. A private repository never seeds a Lesson.
  • Pull request review comments the author acted on. A comment by someone other than the pull request's author, and not a bot, followed by a commit to that pull request. The pull request must be a confirmed document in the project.
  • Confirmed meeting, Slack and email documents. Only documents a person has confirmed for use in sessions.

A Lesson is proposed only when the same kind of evidence recurs on the same file for . One person's mistakes never become a Lesson on their own.

Documents

Project memory — upload docs, import from Drive, capture Slack and email, and search everything your project knows.

Session sharing

Share any conversation with a link — org-scoped or public, with expiry and inline annotations.

On this page

Turning Lessons onWhere a proposal comes fromWhat a Lesson containsHow a Lesson reaches a sessionIs it working?Indexing and where text goesData residencyErasureNext steps
The two-person rule.
two or more different people

A proposal is a draft. Its text is a template built from the kind of mistake alone: nothing from a conversation, a comment or a document is copied into it, and neither is the file path. A draft is never added to a session. A person edits it into the team's rule and accepts it in the project's Lessons page (the Lesson inbox), or rejects it.

Who can accept. Any member can read the inbox. A developer or above can edit, accept, reject or retire a Lesson that came from corrections or from members' review comments. A Lesson that came from meetings, Slack or email, or from a review comment by someone who is not a member of the organization, needs a manager or above.


What a Lesson contains

A Lesson's text has a fixed shape, one clause per line, in this order:

When: <the situation>
Prefer: <what to do>
Because: <why>
Except: <the exception>   (optional)

It is at most 1,500 characters. crewkit refuses a Lesson that contains a URL, a shell command, an instruction override such as "ignore", "disregard", "forget" or "override", the name of a Claude Code tool, or angle brackets.

Every edit writes a new version; the previous one is superseded and is no longer served.

A Lesson shows how many people it came from, never who. crewkit serves that count, the kind of mistake and a hash of the file path with each Lesson. It never serves the people, conversations or corrections behind a Lesson.


How a Lesson reaches a session

With the second setting on, the CLI sends each prompt you type as a search query, the same request that fetches relevant project documents. crewkit returns at most three accepted Lessons from that exact project that are close enough to the prompt. Each Lesson is added once per session.

The CLI adds them in their own block, at most 6,000 characters, which holds three Lessons of the longest length whole, after a header that says they were written and accepted by people on your team and that they are data, not instructions: the user's request always wins. The text is fenced and redacted for secrets before it is added.

No Lessons are fetched, and no prompt is sent for them, when:

  • the session is started with --sensitive;
  • the organization's capture mode is minimal;
  • the session is started with --no-artifacts;
  • the session has no project.

The MCP get_lessons tool returns the same accepted Lessons when an agent asks for them, fenced the same way. It sends no query from a --sensitive session, and it is rate-limited per person.

What crewkit records when a Lesson is served. One receipt per Lesson served: which Lesson and version, the project, the conversation, the person, whether it was added to the session or read through get_lessons, and when. A receipt holds ids only, never the prompt or the text. No screen or endpoint lists receipts. Within a day after 90 days from when the Lesson was served, crewkit removes the person and the conversation from its receipt and reduces the receipt's time to its day (UTC). This holds in every organization, whatever its retention setting, and the rest of the receipt stays for counts. That rest is the Lesson and its version, the project, how it was served and the day, so on a project where one person worked that day a receipt still points to that person.

Is it working?

The Lesson inbox shows, for each kind of mistake, how often it came back in the 14 days before and the 14 days after its first Lesson was added to a session, and how many proposals people accepted. Only Lessons added to sessions count; a get_lessons read does not. A number appears only when enough people and corrections are behind it that no one person can be singled out; otherwise it reads as suppressed, never as zero. There is no per-person view.


Indexing and where text goes

In a hosted organization, crewkit indexes each accepted Lesson's text with its embedding provider, Voyage AI, so it can be matched to prompts. The prompt sent as a search query is embedded the same way. Neither is sent when the organization has privacy mode on, has turned off embedding egress, or keeps its data resident.

To match better, crewkit may also embed short excerpts of a Lesson's sources: up to three sources, up to 400 characters each, redacted for secrets, and only from sources that are still confirmed for use. Only the resulting vector is stored. The excerpt text is stored nowhere, and it is never added to a session: a session only ever sees the Lesson's own text.


Data residency

When your organization keeps its data resident, its Lessons live on its own data plane:

  • Proposals. The data plane finds candidate corrections in the conversations it holds and sends crewkit only ids, the kind of mistake and a hash of the file path, never a path or any text. crewkit applies the same two-person rule.
  • The text. A resident Lesson's text is written and stored on the data plane and never crosses to crewkit. crewkit keeps the Lesson's ids, kind, path hash, status and owner, and a digest of the text that was confirmed.
  • Confirming. A manager or above reads the text directly from the data plane in their browser and confirms it. A resident Lesson is served only after that confirmation.
  • Serving. The CLI and get_lessons read confirmed Lessons from your data plane, which matches them to the prompt with its own text search. get_lessons sends its query only to the data plane once the MCP process remembers a resident value passed by crewkit code, or a live repository resolution or project answer tells it the organization is resident. That knowledge stays in memory, never in the disk cache, and a failed project read cannot undo it. A hosted value from the launcher still requires a project read; the MCP process's own hosted answers are re-read before a search once three minutes old, with concurrent searches sharing a successful read. When residency is unknown, including a failed initial read with no resident value from the launcher or live resolution, or a failed hosted refresh, a query still goes to crewkit; for a resident organization, crewkit refuses it without storing it, and every later one goes to the data plane. Failed residency reads are retried on the next call.
  • Receipts. The data plane keeps the receipts. It sends crewkit only weekly counts per Lesson and project, and only above the same privacy floor.

Erasure

  • Retiring or editing. When a Lesson is retired, rejected or superseded by an edit, its indexed copy is deleted in the same step.
  • Erasing a person or a conversation. When the last person or conversation a Lesson came from is erased, the Lesson is retired and its indexed copy deleted. Erasing a review comment's author removes that author from every Lesson they contributed to.
  • Erasing a source. Erasing a document, conversation or correction that was excerpted deletes that excerpt's vector at the same time. When a document stops being confirmed for use, its excerpt vectors are deleted too.
  • Projects and organizations. Deleting a project or an organization deletes its Lessons and their receipts. A resident organization's data plane deletes its copy when crewkit's erasure log tells it to.

A Lesson already added to a session is part of that session's own transcript, in Claude Code's files on the developer's machine (~/.claude). crewkit cannot reach or recall that copy.


Next steps

  • Capture modes
  • Documents
  • MCP