---
name: nessie
description: Access the user's personal context layer from an AI agent session. Use when the user references prior work, asks what they know about a topic, needs answers grounded in past AI conversations, or wants Nessie to generate a structured context. Agents can search transcripts, read contexts, answer questions, and create or update contexts.
---

# Nessie Skill

When this skill is invoked, always use the local `nessie` CLI through the
shell. Do not use Nessie MCP tools such as `mcp__claude_ai_Nessie__*`; those
belong to the MCP connector surface, not the CLI skill surface.

---

# Nessie Agent Behavior

This is the shared behavior guide for agent surfaces that read from or write to
Nessie. Interface-specific docs should explain how to operate a surface, but
the product semantics below should stay consistent across CLI skills, MCP
connectors, and future agent integrations.

## Mental Model

Nessie is the user's personal context layer. It gives agents access to saved
contexts, profile sections, raw AI conversation transcripts, and synced source
graphs such as Obsidian vaults and Granola meeting notes so they can answer
questions, reconstruct prior decisions, and preserve durable knowledge for
future sessions.

When the user says "use Nessie" or asks what Nessie can do, lead with the
agent-access mental model:

> I can use Nessie to browse the sources you have connected, search your past
> AI conversations and notes, read your saved contexts, and bring that context
> into this agent session. You can ask a question, ask for a brief or memo, or
> ask me to generate a structured context when you want something reusable.

The user does not need to switch into the Nessie app before getting value.
Treat their natural-language request as the interface: search what Nessie
knows, read the relevant sources, and answer directly. Context generation is
one powerful capability, not the only way to use Nessie.

Nessie builds context by analyzing the user's AI conversation history across
supported AI providers, including chat apps, coding agents, and research tools.
It can also expose connected source graphs, such as Obsidian vaults with
folders and notes, or Granola meeting notes organized into folders, when those
sources are synced.

## Default User Experience

When a user asks what Nessie can do, explain that Nessie gives agents access
to the context they have already built. Give generic examples of normal
back-and-forth use:

- "What do I know about this topic?"
- "What did I decide about this project?"
- "Summarize my past conversations about this topic."
- "Show me what sources Nessie has available."
- "Search my Obsidian notes about this project."
- "What have I already tried for this bug?"
- "Use what I know from Nessie and help me draft this reply."

It is fine to show a command or tool table when it helps the user understand
the tooling. Do not frame context generation as the only or default thing the
user should ask for. Many requests are answered through research,
source-reading, and back-and-forth synthesis in the agent session; context
generation is for deeper or reusable outputs.

## Search Strategy

Use source browsing before search when the user asks what is available, wants
to inspect a vault or folder, or is unsure which source world contains the
answer. Source listing is the "ls" affordance: it shows connected source
groups, root nodes, and folder-like children without requiring a query.

For navigational queries - when the user asks for a specific artifact by name
(task log, daily journal, a specific file) - prefer source browsing over
search. Navigate directly to the relevant folder and read the latest entry.
These artifacts often live in synced note sources, not in contexts or
transcripts, so searching contexts alone will miss them.

Choose the source order from the user's intent, not from a global ranking:

- Discovery, navigation, and "what sources exist" requests should start by
  listing source roots and traversing hierarchies.
- Specific files, notes, journals, task logs, and memos should start in the
  relevant source hierarchy. For Obsidian, browse vaults and folders first when
  the user gives a path-like or artifact-like clue.
- Knowledge questions about something the user has researched should use
  contexts for synthesized orientation, then read primary sources when freshness,
  provenance, or deeper detail matters.
- Latest/current-development questions should be grounded in recent source
  activity, especially recent transcripts. Use stale contexts only as
  orientation, then search or browse recent transcripts and notes broadly enough
  to synthesize what changed.
- Verification and exact grounding should read primary sources. Use transcripts
  for what happened in AI conversations, and notes for user-authored or
  user-maintained material.
- Resume and takeover requests should be transcript-first, with beginning and
  recent-tail reads before synthesis.

Context search is an orientation tool, not the universal first step. A matching
context often gives the compiled picture quickly, but it may be stale or omit
details that live only in primary sources. Obsidian notes and conversation
transcripts are not fallback sources when the user's request clearly points to
them.

For topics with multiple relevant contexts, one context is often not enough.
Read the obviously relevant context results, compare their recency metadata,
and check recent transcripts before making a strong claim. A stale context is
orientation, not the final answer.

For questions like "latest developments on X", "what changed recently", "where
are we now", or "what is the current state", do not stop at existing contexts.
Start with recent source discovery and recent transcript search for the relevant
project, product, people, repository, issue, or distinctive terms. Read several
recent matching conversations or notes, including relevant tail windows for long
transcripts, and synthesize across them. Existing contexts can explain the
background, but recent primary sources establish the latest state.

For broad discovery where you are unsure what source worlds exist, list
available sources first. Then search the relevant source types for the user's
intent rather than defaulting to contexts.

Run multiple searches with related terms when the first query is too narrow:
names, companies, product names, distinctive wording, and likely synonyms.

After searching, always read full content with the appropriate context,
transcript, note, folder, or profile reader. Search results are starting
points, not answers.

When a search result or transcript chunk cuts off mid-sentence or mid-thought,
paginate forward with the source document reader. Do not run another search,
guess at the missing content, or report "I don't know" when you have the
document ID and chunk index to continue reading from. A cutoff is a signal to
keep reading, not to stop.

## Source Authority Hierarchy

Source types serve different purposes:

- Contexts are compiled knowledge: synthesized, structured summaries of what
  the user knows about a topic. Use them for orientation and reusable summaries
  when the user asks a knowledge question. They may be stale, so verify
  freshness by checking the context date against recent activity and primary
  sources when the answer depends on current or exact details.
- Conversation transcripts are ground truth for the user's actual AI
  conversations: words, decisions, and thinking as they happened. Use
  transcripts to verify context claims, fill in details, or when no context
  exists.
- Obsidian notes are user-authored or user-maintained source material. Use
  them when the user refers to notes, vaults, files, memos, source docs, or
  asks for project knowledge that likely lives outside AI transcripts. Preserve
  their path and hierarchy when citing or selecting them.
- Granola notes are AI-generated summaries of the user's recorded meetings,
  organized into folders. Use them when the user refers to a meeting, call,
  interview, or who-said-what, or asks for decisions and action items from a
  conversation that happened on a call rather than in an AI chat. Browse granola
  folders to find a meeting; reading a note returns its AI meeting summary, and
  the raw transcript turns are indexed for search (they surface under transcript
  or all-type search), not as browsable child nodes.
- Profile sections contain structured biographical facts about the user. Check
  the profile for identity, connections, project info, and other recurring
  personal context.

For discovery: browse source roots and hierarchies first.
For synthesized orientation: read relevant contexts.
For verification: primary sources are authoritative over contexts. Prefer
transcripts for claims about what happened in conversations, and notes for
claims about user-authored source material.
For creation: ground new contexts in primary-source evidence, not only in other
contexts.

## Authenticated User and Personal Sources

For first-person questions such as "what did I do", "what am I working on",
"what did I decide", "who am I", "my recent work", or "what do you know about
me", treat the authenticated user's own profile and personal source roots as
the primary scope.

Start with profile or check-in data for orientation when the surface exposes
it. Profile data may be sparse or incomplete; do not stop there. If the profile
does not answer the question, list the user's source roots and inspect their
personal transcript or note roots. Browse or search within those personal roots
before falling back to broad global search.

Do not use team-shared roots as the default scope for first-person questions.
Use team and team-shared roots when the user asks about a teammate by name,
asks about shared team work, or explicitly asks to compare their work with
someone else's.

When a surface exposes an owner or source-owner selector, leave it omitted or
set it to `current_user` / `me` for first-person questions. Pass an explicit
teammate identifier, teammate email, or `team` only when the user asks for that
person's sources or shared team scope.

Use `sourceOwner` as the sole authority for source ownership, owner scoping,
and profile inclusion. It identifies whose source/transcript was queried; it is
not semantic proof that the source owner personally did every business task
mentioned inside the content. Read the content before attributing work. Treat
integration/provider/account fields as provenance and debugging context only;
never infer who owns a source from an integration display name, device label,
provider account email, or account name. A current user's ChatGPT, Claude,
Codex, or other provider account may use a different email or machine label
while still being owned by the current Nessie user.

## Temporal Interpretation

For relative date phrases such as "today", "yesterday", "this week", "last
week", or "so far", resolve the time window in the user's local timezone before
filtering Nessie sources. The local CLI can parse date-only filters using the
Mac's current timezone. Hosted MCP surfaces should pass date-only filters with
`since` and `until` as `yyyy-mm-dd` values plus an explicit IANA timezone so
the MCP server can resolve the local window programmatically.

If the surface exposes a user timezone, use it. If no reliable user timezone is
available and the date boundary matters, ask the user or state the timezone
assumption before applying a strict date filter. Prefer recent-source browsing
or a wider window over silently using UTC for first-person "today" questions.

## Query Interpretation

Before searching, infer the likely purpose and scope:

- Identity and relationship queries ("who are my collaborators", "what tools do
  I use") need broad searches with related names and terms. These answers
  accumulate over time.
- Topics with several plausible sources need multiple relevant contexts, recency
  comparison, and recent transcript checks before answering. Do not infer from
  the first matching context or external information alone.
- Queries with temporal signals ("recent", "lately", "this week") should prefer
  recent conversations and notes, then read them. Existing contexts are
  background only until checked against recent primary sources.
- Current-state queries ("what am I working on") should prefer recent content
  without excluding older foundational context.
- Latest-development queries ("latest developments on Nessie", "what changed
  recently on X", "where are we now") need a broad synthesis over recent
  transcript/source activity. Search multiple related terms, read several recent
  sources, and compare against any existing context before answering.
- Open-ended exploration ("what have I learned about X") should start with a
  broad search and expand with more specific searches if results are thin.
- Generation with audience ("brief for my team", "summary for my team") should
  infer purpose, audience, and tone before researching.
- Agent takeover or resume requests ("take over this session", "resume this
  Claude/Codex conversation", "continue from this transcript", "here is a
  session ID") need transcript-first reading. The relevant work is often near
  the end of a long conversation, so do not stop after reading the beginning.
- When uncertain, run a few searches with exact names, related terms, and
  broader conceptual phrases. Synthesize across the results.

## Agent Takeover / Resume

Use this workflow when the user asks an agent to take over, resume, continue,
or recover context from a prior AI session, especially when they provide a
session, transcript, node, or conversation ID.

1. Identify the target conversation or source node. If the user gave an ID,
   read that node directly. If they gave a title, project, tool, teammate,
   date, or workspace, search and browse until you find the matching recent
   conversation.
2. Read both the beginning and the end before synthesizing. The beginning
   usually explains the goal and constraints; the end usually contains the
   current state, latest decisions, open blockers, and uncommitted next steps.
3. Bias toward the tail for handoff state. For long transcripts, read the last
   available page or chunk window first after a light beginning skim, then page
   backward until the latest work is coherent. Do not assume offset 0 is the
   most important part of an old session.
4. Search within or around the transcript for distinctive terms from the recent
   tail, such as file paths, branch names, issue IDs, errors, people, or
   project names. Read adjacent chunks when results land in the middle.
5. Produce a compact takeover brief before acting: goal, current state, files
   or artifacts touched, decisions made, blockers, and exact next actions. Then
   continue the user's requested work from that brief.

If the session is too long to read fully, say that you read the beginning, the
recent tail, and the relevant middle sections you found by search. Be explicit
about any remaining uncertainty rather than presenting a partial read as a full
resume.

## Core Loop: Read -> Respond -> Optional Write Back

On every Nessie invocation, follow this loop:

1. Read first. Before responding, search Nessie for relevant context. Use the
   source order implied by the user's intent: browse source hierarchies for
   discovery, read contexts for synthesized orientation, and read primary
   sources for verification or exact grounding. Read matching documents in full.
   The response is better when grounded in what Nessie already knows.
2. Respond with Nessie context. Use what you found to inform the answer. Surface
   relationships, prior discussions, and cross-references the user may have
   forgotten.
3. Optionally write back if new information emerged. After the exchange, if the
   conversation produced durable new knowledge, handle the write-back for the
   user or offer it proactively:
   - Update the relevant context when a targeted addition is enough.
   - Create a new context if no existing one covers the topic.
   - Update the user's profile if biographical facts changed.
   Do not make this sound like maintenance the user has to remember. Frame it
   as: "I can save this back to Nessie so future sessions can pick it up."

## When to Use

1. Start of session: read the profile to understand the user. If profile data
   is sparse, inspect the user's personal source roots and recent transcripts
   before concluding Nessie lacks information about them.
2. User references prior work: use contexts for orientation when the request is
   a knowledge question, but start with source browsing or primary-source search
   when the prior work likely lives in files, memos, vaults, source documents,
   or a specific conversation. Read full content, not just snippets.
3. User asks "what do I know about X": search contexts for the compiled
   picture, then read transcripts or notes for verification, freshness, or
   deeper detail.
4. User asks about past conversations: search transcripts for matching
   conversations, then read the relevant transcript content.
5. User asks what sources are available or asks to browse a connected source:
   list source groups or children before searching.
6. Synthesizing answers or new knowledge: follow the manual research workflow
   at the right depth for the request. Save a context only when the user asks
   for a reusable artifact or the exchange produced durable new knowledge worth
   preserving.
7. Organizing contexts: use context and folder organization operations to help
   the user organize their context library.
8. Accessing and updating the profile: use profile operations to read what
   Nessie has built so far and update it when new information emerges about the
   user, such as a new job, new connection, changed project status, or new
   decision.

## Manual Research Workflow

This workflow mirrors the Nessie backend agent's context generation flow. When
the user asks you to research a topic and produce a structured output, follow
these steps. Every step is mandatory for substantial synthesis.

### Step 1: Interpret the Query

Infer purpose, audience, and time scope. Decompose the topic into facets:

- A person query needs their name, company or role, related people, relevant
  events, and key dates. Always start by checking profile or connection data
  when available. Use that as your starting point before searching transcripts.
- A product or project query needs the product name, related decisions,
  adjacent products or projects, and evolution over time.
- A relationship query needs both parties, the timeline, key interactions, and
  current status. Check profile connections for both parties first when
  relevant.

### Step 2: Search Broadly

Cast a wide net with multiple searches. A single search is almost never
sufficient.

- List source groups or source children when the user asks what is available,
  references a vault or folder, or you need to understand a source hierarchy.
- Search exact names or terms in contexts when compiled knowledge would help
  orient the task.
- Search exact names or terms in transcripts and notes when primary-source
  verification is needed, no context exists, or the user asks about artifacts,
  notes, files, conversations, task logs, journals, or other source material.
- Search broader conceptual topics when you are unsure what exists.
- Search related terms separately. If researching a person, also search their
  company, related people, and relevant events.
- When a topic can be described several ways, search the user's wording plus
  obvious alternate names or related terms before concluding that sources are
  unrelated or newly changed.

### Step 3: Read Deeply

Search results are breadcrumbs, not answers. Search snippets are short excerpts
from conversations that may span thousands of words. Read full sources before
synthesizing.

For each relevant search result:

- Read the full transcript or relevant paginated transcript sections.
- Read full synced notes when note results match the task.
- Read relevant existing contexts in full.
- Read at least 3-5 full sources before synthesizing when enough sources exist.
- If multiple contexts match the same entity or topic, read the relevant set;
  do not stop at the first context that confirms a plausible answer.
- Conversations often build over many exchanges. Read enough to understand the
  full picture.

If you create a context based only on search snippets without reading full
sources, the output will be thin and missing critical details. This is not
acceptable.

### Step 4: Cross-Reference and Synthesize

Follow threads across multiple conversations and contexts. Surface patterns,
timelines, contradictions, and insights that no single source contains alone.
If a transcript mentions another person, event, or decision, search for that
too.

### Step 5: Save with Editorial Judgment

Save only structured, source-grounded work. The body should be useful prose:
headers, bullets, narrative paragraphs, dates, names, and concrete details when
they matter. Every claim should trace back to something you actually read in
full.

Do not include the context title as the first H1 in the body. Nessie stores
titles separately from context body markdown.

When creating a context from Nessie research, attach the document IDs of every
transcript and context read during research. Without provenance, the user cannot
trace claims back to original conversations.

Output quality rules:

- Thoroughness over brevity. Capture substance, nuance, and key details. A thin
  summary is not useful. Err on the side of comprehensive; the user can ask for
  edits later.
- Specific details, not vague summaries. Include dates, quotes, amounts, and
  names when they matter.
- Every claim must trace to a specific source. While drafting, mentally tag each
  claim with the source document ID it came from. If you cannot identify which
  source supports a claim, do not include it.
- Relevance filtering. A search match does not automatically earn inclusion.
  Ask whether it serves the purpose of the context.
- Match tone to audience. Use professional tone for external stakeholders,
  casual tone for personal notes, and precise tone for technical briefs.

### Multi-Person Attribution

When a transcript discusses multiple people, verify who said or did what before
attributing. Names appearing in the same document do not mean the same person
said everything. When uncertain, ask the user to confirm.

### Epistemic Rules

Only state something as a biographical fact about a real person if the user
explicitly established it as true.

When synthesizing content from conversations, distinguish between:

1. User statements of fact: things the user explicitly said are true about
   themselves or someone they know. State these as facts in the context.
2. User questions and hypotheticals: explorations, not assertions. The user
   asking about something does not mean it is true. Never convert a question
   into a stated fact.
3. External information the user analyzed: research, articles, or data the user
   looked up. This is reference material, not biographical fact.

Use "discussed", "explored", "asked about", or "researched" for anything that
is not an explicitly established biographical fact.

## Generated vs Manual Research

Generated context research is available only on surfaces that expose Nessie's
backend generation workflow, such as the app and CLI. Adapter-specific
instructions may narrow this guidance when a surface does not expose that
workflow.

Use generated context research when:

- The user wants a comprehensive brief, memo, summary, or prep doc grounded
  purely in their conversation history.
- The task needs synthesis across their overall history or profile, and manual
  search is likely to overfit to granular transcript citations.
- You need higher-accuracy synthesis from Nessie's backend research agent.
- The user pushes back on manual output quality after multiple rounds.

Use the manual research workflow when:

- You need to combine Nessie data with external information or code context.
- You want to control exactly which sources are consulted.
- You are answering a question directly in the agent session and need to search,
  read, and synthesize from Nessie sources before responding.
- You are creating a context that synthesizes across Nessie data and other
  sources such as files, web, or codebase context.

Both workflows have the same source authority rules. Manual research gives you
control over exactly which sources to read and how to synthesize them. Use
pagination when reading long transcripts rather than loading everything at once.
Generated context research re-runs research from scratch, so treat it as a
deliberate escalation for deeper synthesis rather than the default next step
after every manual answer.

Never search once, skim snippets, and save a context. This produces thin,
unreliable output that misses critical details the user expects.

Do not keep forcing a manual answer after the user has pushed back on quality.
If the task needs deeper synthesis or the user is not satisfied after multiple
rounds, use a generated research workflow when available and incorporate that
output.

## Auto Write-Back

This is step 3 of the core loop. After any substantive exchange where new
information emerged about a topic Nessie tracks:

- Prompt naturally. If there are durable takeaways, offer to save them back to
  Nessie or just do it when the user has asked you to preserve the work. The
  user should not feel responsible for manual library maintenance.
- Existing context on the topic? Add the new information to that context.
  Targeted edits are better than full rewrites.
- No existing context? If the research was substantial, with 3+ sources read
  and meaningful synthesis, offer to create one. Keep the prompt simple:
  "Want me to save this back to Nessie for next time?"
- Profile changed? Update the relevant profile section or card.

When creating new contexts, search for existing ones on the topic first to
avoid duplicates. Use file-backed body inputs when available for creation to
avoid escaping issues with special characters. Organize into an appropriate
folder.

## Non-Destructive Operations

Context operations should be additive whenever possible:

- Do not delete contexts to "replace" them. If consolidating multiple contexts
  into one, create the new context first, verify it captures all information,
  and only delete originals after explicit user confirmation.
- Use targeted edits for corrections and additions. When correcting or updating
  part of a context, replace specific text rather than deleting and recreating
  the entire context.
- Do not overwrite without preserving. If updating a context, the original
  information should not be lost.
- Prefer creating alongside, not instead of. If the user has existing contexts
  on a topic, create your new synthesis as a separate context rather than
  deleting and replacing the originals.

---

# Nessie CLI Adapter

This is the CLI adapter section for agent surfaces that call the local
`nessie` CLI.

## Operating Model

The CLI talks to the Nessie macOS app over localhost and reads or writes the
app's local data. The app must be running before CLI commands can succeed.
Check with:

```bash
nessie status
```

CLI surfaces should document their own sandbox or permission requirements. For
Codex, every `nessie` command must run with escalated permissions because the
CLI needs localhost networking and access outside the workspace.

## Check-In

```bash
nessie check-in
nessie check-in --recent-limit 10
nessie check-in --hook
```

Use `nessie check-in` when the user starts with "Nessie check-in", says "check
in with Nessie", asks to load their Nessie context before continuing, or when a
local agent session needs a compact startup briefing. The command returns the
user's generated profile sections plus recent Nessie activity. `--recent-limit`
defaults to 10 and accepts values from 1 through 25.

Use `nessie check-in --hook` only from Claude Code or Codex `SessionStart` hook
configuration. In hook mode, the CLI emits the host hook JSON payload with
`hookSpecificOutput.additionalContext`; it does not print the raw check-in
response. The hook is fail-closed: if the Nessie app is closed, too old, or
unreachable, it emits no context rather than blocking session startup.

The local CLI check-in shape is optimized for hook rendering. Profile sections
are returned as `{ name, value, updatedAt }`, where `value` is already parsed
into a string or card array and timestamps are Mac-local display strings. The
MCP `nessie_check_in` tool returns profile source nodes instead:
`{ id, name, kind, emoji, updatedAt, displayUpdatedAt, content }`, where
`content` is the raw JSON section payload. Do not assume the two adapter
surfaces have identical response shapes.

## Profile Access and Updates

```bash
nessie profile
nessie profile get
nessie profile get --section connections
nessie profile edit-field --field <field> --value "<value>"
nessie profile edit-text --section <section> --content "<markdown>"
nessie profile edit-text --section <section> --content-file <path>
nessie profile add-card --section <section> --fields '{"key":"value"}'
nessie profile update-card --section <section> --index <n> --updates '{"key":"value"}'
nessie profile remove-card --section <section> --index <n>
```

Profile commands return or edit the user's structured profile. The profile may
still be building for new users, so describe this capability as accessing and
updating their profile rather than assuming every section is already complete.
`nessie profile` or `nessie profile get` returns the full profile. Use
`--section` to read a specific section.

For first-person questions such as "what did I do", "what am I working on",
"who am I", or "what do you know about me", start with `nessie profile` or
`nessie check-in` for orientation, then continue into the user's personal raw
sources if the profile is sparse. Run `nessie source list` with no filter first
when you need to see all available personal root IDs, including transcript roots
and note roots. Then use `nessie source list --parent-id <root-id>` to inspect a
chosen root and search or browse within it with `nessie node search --parent
<root-id>` or `nessie node list --parent <root-id>`. Sparse profile data does
not mean sparse raw data.

Scalar fields for `edit-field`: `name`, `preferredName`, `dateOfBirth`, `email`,
`phone`, `address`, `employer`, `jobTitle`.

Text sections for `edit-text`: `biography`, `communication`, `personality`.
These accept full markdown content that replaces the section.

Card sections for `add-card`, `update-card`, and `remove-card`: `education`,
`workExperience`, `connections`, `projects`, `decisions`, `expertise`,
`upcoming`.

Card fields:

- `education`: `school`, `degree`, `years`, `description`
- `workExperience`: `employer`, `title`, `years`, `description`
- `connections`: `name`, `shortDescription`, `description`
- `projects`: `name`, `status`, `description`, `techStack`
- `decisions`: `title`, `description`, `category`, `timeHorizon`, `date`
- `expertise`: `name`, `category`, `description`
- `upcoming`: `title`, `date`, `category`, `description`

Cards are identified by 0-based index within their section. Use
`nessie profile get --section <section>` to see current cards and indices
before updating or removing. For `add-card`, provide all fields. For
`update-card`, only include fields you want to change.

Profile changes made via CLI are immediately visible in the Nessie app; the
editor observes profile section changes reactively.

## Teams, Integrations, and Nodes

```bash
nessie team list
nessie integration list
nessie integration list --platform claude_code
nessie integration list --status team_remote
nessie integration list --team-id <team-id>
nessie node list --parent <node-or-integration-root-id>
nessie node list --parent <node-or-integration-root-id> --kind transcript
nessie node list --parent <node-or-integration-root-id> --since 2026-05-30 --until 2026-05-31
nessie node get <node-id>
nessie node search "<query>" --parent <node-or-integration-root-id>
nessie node search "<query>" --parent <node-or-integration-root-id> --kind claude_code_chat --since 2026-05-30
nessie node search "<query>" --owner <teammate-owner-user-id>
nessie source list --owner team
```

Use these first for team-shared work. `team list` returns teams, members, and
shared resources. `integration list` returns connected and team-shared roots
with provenance fields such as `teamId`, `teamName`, `ownerUserId`,
`ownerDisplayName`, `ownerEmail`, `status`, `deviceId`, `platform`, and
provider labels. Team members include current-user and creator markers when
the local directory has enough metadata.

`node list` is the first-class graph browser. Pass an integration root, vault,
folder, or other container with `--parent` to list direct children. Without
`--parent`, `node list` returns root-like entries rather than a broad flat
document feed. Use `--kind` with a group (`context`, `transcript`, `profile`,
`obsidian`, `granola`) or a raw node kind such as `claude_code_chat`,
`codex_chat`, `obsidian_note`, or `granola_note`. Use `--since` and `--until` for recency windows; both accept
ISO-8601 timestamps or `yyyy-mm-dd` dates. Date-only CLI filters are resolved
in the local Mac timezone before querying, matching the user's normal local-day
expectation for phrases like "today" and "yesterday". The CLI does not need an
explicit timezone flag because these requests are handled by the local Mac app
server. A date-only CLI `--until` resolves to the local day's final second, so
use an exact ISO timestamp when sub-second end-of-day precision matters.
`source list --parent-id ...` accepts the same date filters when the task is
source browsing rather than lower-level graph inspection.

Discovery and search commands default to the authenticated user's own source
owner. Keep `--owner` omitted, or pass `--owner current_user` / `--owner me`,
for first-person questions. Pass `--owner team` only for explicit shared-team
scope. Pass a teammate user ID or email, such as `--owner tiger@nessielabs.com`,
only when the user asks about that teammate's sources. For named teammates,
prefer `nessie team list` or `nessie integration list --status team_remote`,
then pass the member `userId` / resource `ownerUserId` with `--owner`. Email
selectors resolve only from existing team member email metadata. If no readable
team member has that email, the CLI returns an invalid-input error instead of
empty results.

Returned descriptors may include both `sourceOwner` and `integration` metadata.
Use `sourceOwner` as the only ownership and scoping signal. It tells you whose
source/transcript this is, not who semantically performed every task mentioned
inside the transcript. Read the content before assigning business work to a
person. Treat `integration` fields such as `accountName`, `providerName`,
`deviceId`, and team/provider labels as provenance only. Do not decide whether a
result is "mine" or "Tiger's" from an integration account email or display
name; those can differ from the authenticated Nessie owner.

`node get` reads a specific node. Readable notes, contexts, and transcripts
include a `read` payload. Container nodes such as integration roots, vaults,
and folders include their first `children` page, so an agent can drill through
with either `node get` or `node list --parent`.

`node search` is the preferred scoped search surface. It accepts the same
`--parent`, `--kind`, `--since`, `--until`, `--limit`, and `--literal` filters
and returns document descriptors with team/integration provenance where
available. Returned descriptors include `sourceOwner` so attribution does not
depend on integration display names. For questions like "what did Tiger do yesterday?", start with
`team list` or `integration list --status team_remote`, identify Tiger's
shared integration root and ownerUserId, then use
`node search --owner <tiger-owner-user-id>` or
`node list --owner <tiger-owner-user-id> --since/--until` under that root. Use
`--owner <email>` only when that email appears in team member metadata.

If `node search` returns `truncated: true`, the search scope hit an internal
safety cap before searching. Narrow the request with a smaller `--since` /
`--until` window, a more specific `--parent`, or a narrower `--kind`, then
retry. `scopeNodeCount` reports how many scoped nodes were searched.

## Agent Takeover / Resume

For requests such as "Nessie resume", "Nessie takeover", "resume this Claude
session", "continue this Codex session", or a pasted conversation/node ID, treat
resume as a workflow over search plus read.

If the user provides a UUID, start with:

```bash
nessie source get <id> --head-limit 5 --tail-limit 10
nessie node get <id> --head-limit 5 --tail-limit 10
nessie transcript get <id> --head-limit 5 --tail-limit 10
```

These return a windowed read payload with a small beginning window and the
recent tail window. Use it to write a compact takeover brief before acting.

When the user does not provide an ID, use the user-provided clue to find
candidate conversations, including imported transcripts and Nessie chats:

```bash
nessie node search "<user-provided topic, title, error, branch, or file path>" --kind transcript
```

Choose the matching candidate ID, then read it with `--head-limit 5
--tail-limit 10`.

For takeover quality, always read a small beginning window and a recent tail
window before summarizing. If the `tail` window references specific files,
branches, errors, or decisions, search those terms and read adjacent chunks with
`nessie node get` or `nessie transcript get`. The goal is to recover the current
working state, not merely summarize the oldest context in the transcript.

## Search

```bash
nessie search "<query>"
nessie search "<query>" --type context
nessie search "<query>" --type transcript
nessie search "<query>" --type profile
nessie search "<query>" --type obsidian
nessie search "<query>" --type granola
nessie search "<query>" --parent-id <source-node-id>
nessie search "<query>" --type obsidian --parent-id <vault-or-folder-id>
nessie search "<exact phrase>" --type obsidian --literal
nessie search "<query>" --limit 20
```

Search runs hybrid search across documents. Results are grouped by document and
include matching chunks when available. Prefer `node search` for new
team-shared workflows because it can apply `--since`/`--until` and returns
first-class node descriptors.

Use `--type` to apply the source-selection principles from the shared guidance:
pick `context`, `obsidian`, `granola`, `transcript`, `profile`, or no `--type`
based on the user's intent. For latest/current-state questions, combine that with
`--since` / `--until` when a time window is available and read several recent
matching sources before synthesizing.

Local CLI search does not support concurrent search requests. Never fan out
multiple `nessie search` or `nessie node search` commands in parallel. When you
need several searches, run them serially and wait for each command to finish
before starting the next one. Concurrent local searches can slow each other down
enough to time out and may be reported by the CLI as "Nessie is not running"
even when the app is open.

Use `--type` to filter results:

- `context`: user-created and generated context documents only
- `transcript`: synced AI conversation transcripts only
- `profile`: user profile sections only
- `obsidian`: synced Obsidian notes only
- `granola`: synced Granola meeting notes only
- omit `--type` for all types combined

Use `--limit` to control the maximum returned results. The default is 10 and
the maximum is 500.

Use `--parent-id` to restrict search to a source node and its descendants,
including an integration root returned by `source list` (personal or
team-shared), or a specific Obsidian vault or folder.

Use `--literal` for exact substring matching when the user asks which files
mention a specific quoted or exact wording. Literal search matches the whole
query string as a contiguous substring. Do not treat an unquoted natural
language description as one exact phrase; split it into salient exact terms or
use ordinary search for semantic discovery.

Search results include `totalChunks`, which indicates source size, and
`documentContext`, which provides attribution framing for the conversation. Use
`totalChunks` to decide whether to read the full document or paginate.

## Source Browsing

```bash
nessie source list
nessie source list --source-type all
nessie source list --source-type obsidian
nessie source list --source-type granola
nessie source list --parent-id <integration-root-id>
nessie source list --parent-id <node-id> --source-type obsidian
nessie source list --parent-id <granola-root-id> --source-type granola
nessie source list --parent-id <node-id> --since 2026-05-30 --until 2026-05-31
nessie source get <node-id>
nessie source get <node-id> --offset 0 --limit 5
nessie source get <node-id> --head-limit 5 --tail-limit 10
nessie source list --limit 100
```

Source browsing is the CLI equivalent of `ls`. Use it when the user asks what
sources Nessie can see, wants to inspect connected source worlds, or references
a hierarchy such as an Obsidian vault or folder, or a Granola folder of meeting
notes. Browsing a Granola integration root lists its top-level folders and
loose notes; browse into a folder for the meetings filed under it.

For discovery and navigation, prefer `source list`, `node list`, and
`source get` before search. Once you identify a likely root, vault, folder, or
conversation node, use `--parent-id` / `--parent` to keep subsequent reads and
searches scoped to that hierarchy.

Without `--parent-id`, `source list` returns source groups, counts, and root
nodes. Integration roots represent connected accounts/resources; team-shared
roots appear alongside personal roots and expose shared transcripts/notes
through the same child and search commands. With `--parent-id`, `source list`
returns direct children for an integration root or folder-like source node.
Results include typed descriptors with `id`, `kind`, `sourceType`, `path` or
`sourceId`, child counts, and affordances such as `list_children`,
`search_within`, and `read`.

Use `--source-type` to scope browsing:

- `all`: all source groups and roots
- `context`: saved contexts and context folders
- `transcript`: synced AI conversation sources
- `profile`: profile source sections
- `obsidian`: synced Obsidian vaults, folders, and notes

For questions about a teammate's recent work, first inspect team-shared roots
from `nessie team list` and `nessie integration list`, then search within
likely teammate or machine roots with `nessie node search --owner <teammate>`.
Use `--parent` as an additional root/folder constraint when helpful. If shared
roots are sparse, also search all contexts/transcripts/profile because teammate
mentions may live in the user's own conversations.

Do not use team-shared roots as the default for first-person questions about
"me", "my work", or "what I did". Personal source roots are the primary scope
for the authenticated user; team-shared roots are for named teammates or
explicit shared-team questions.

For Obsidian, start with `nessie source list --source-type obsidian`, copy the
integration-root `id`, then list its children with `--parent-id` to get the
vault `id`. From the vault, continue traversing folders and notes with
`--parent-id`. Use `nessie search "<query>" --type obsidian` when you have a
query and `source list` when you need orientation or hierarchy.

Use `source get` to read a source node by UUID. It can read Obsidian notes,
contexts, profile sections, and transcripts; for integration roots and
folder-like nodes it returns children. Obsidian note responses include the note
`path`/`sourceId`, content, chunk counts, and pagination metadata.

For requests like "find all Obsidian files mentioning the exact phrase X", use:

```bash
nessie search "X" --type obsidian --literal --limit 50
nessie source get <matching-note-id>
```

For requests that mention multiple concepts without quoting an exact phrase,
run separate targeted literals or a hybrid search, then read and verify the
candidate notes. Do not assume a multi-word natural-language request is also
the exact wording that appears in source files.

If the user asks to search within a vault, folder, teammate source, or
connected account, first get the source node id with `source list`, then pass
it as `--parent-id`.

## Contexts

```bash
nessie context list
nessie context get <id>
nessie context get <id> --offset <n> --limit <n>
nessie context create --title "<title>" --body "<markdown>" [--emoji "<emoji>"] [--folder <folder-id>] [--sources <uuid1> <uuid2> ...]
nessie context create --title "<title>" --body-file <path> [--emoji "<emoji>"] [--folder <folder-id>] [--sources <uuid1> <uuid2> ...]
nessie context generate "<prompt>"
nessie context edit <id> --old-string "<text to find>" --new-string "<replacement>" [--replace-all]
nessie context edit <id> --old-string-file <path> --new-string-file <path> [--replace-all]
nessie context move <id> --to <folder-id>
nessie context move <id> --unfiled
nessie context rename <id> --name "<new name>"
nessie context delete <id>
```

Contexts are the user's saved context documents. Use `list` to browse all
contexts with folder membership, and `get` to retrieve full content by UUID.

Use `create` to save a new context synthesized from the user's data. The body
should be structured markdown. Include an emoji that represents the topic. Do
not include the context title as the first H1 in the body; titles are stored
separately, so start the body with the first real section or paragraph. The
context is automatically indexed for search.

Prefer `--body-file` over `--body` when content contains special characters
such as apostrophes, asterisks, or backslashes to avoid shell escaping issues.

Always pass `--sources` with the document UUIDs of transcripts and contexts you
read while researching. This creates source badges in the Nessie app that let
the user trace claims back to their original conversations. Without `--sources`,
the context has no provenance and no source badge appears.

Use `edit` to modify a context's markdown body using exact string replacement.
Provide the exact text to find and its replacement. The match must be unique
unless `--replace-all` is set. Only context documents can be edited;
transcripts and other document types are read-only.

Prefer `--old-string-file` and `--new-string-file` over inline strings when the
content contains markdown formatting, dashes, or special characters.

Use `generate` to have Nessie's backend research agent search the user's
conversation history and synthesize a structured context automatically. This
takes 30-120 seconds. The backend agent generally produces higher-quality deep
synthesis than a manual agent workflow because it is optimized for context
research and attribution. Use it for comprehensive briefs, memos,
profile/history-level synthesis, high-accuracy synthesis, or when manual
answers are not reaching the right abstraction. Because it re-runs research
from scratch, treat it as a deliberate escalation rather than a default retry.

## Transcripts

```bash
nessie transcript list
nessie transcript list --type chatgpt
nessie transcript list --limit 100
nessie transcript get <id>
nessie transcript get <id> --offset <n> --limit <n>
nessie transcript get <id> --head-limit 5 --tail-limit 10
```

Transcripts are the user's raw synced AI conversations. Use `list` to browse
conversations with their source platform, date, and message count. Filter by
source with `--type`, such as `chatgpt`, `claude`, `gemini`, `perplexity`,
`openclaw`, `claude-code`, or `claude-cowork`. Use `get` to read conversation
content. `transcript get` can also read a Nessie-native chat ID returned by
transcript-scoped search.

Transcripts support pagination via `--offset` and `--limit`. This is important
for long conversations. When a search result shows a high `totalChunks` count,
use pagination to read sections rather than loading the entire transcript at
once:

```bash
nessie transcript get <id> --offset 0 --limit 5
nessie transcript get <id> --offset 25 --limit 5
```

Read around the chunk index returned by search results to find context. The
response includes `totalChunks`, `offset`, and `chunksReturned` for navigation.
It also includes `documentContext` when available, which describes what the user
was doing in the conversation. Use it for attribution decisions.

## Folders

```bash
nessie folder list
nessie folder get <id>
nessie folder create --name "<name>" [--emoji "<emoji>"]
nessie folder rename <id> --name "<new name>" [--emoji "<emoji>"]
nessie folder delete <id>
```

Folders organize contexts. Use `get` to see a folder's contexts and child
folders. `delete` only works on empty folders; move or delete contents first.

## CLI-Specific Cautions

Track source document IDs as you read. Pass them with `--sources` when creating
contexts from Nessie research.

Use exact string replacement for context edits. The match must be unique unless
`--replace-all` is set.

All read commands are instant local reads. Context creation is instant local
write plus async embedding. All data is local to the user's machine. Nessie does
not send documents to external services for CLI reads and writes.

Transcripts are read-only. Do not try to modify synced conversation documents.
