---
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.
---

# IMPORTANT: Codex Sandbox - `nessie` Must Escape It

Codex runs shell commands in a sandbox by default (`workspace-write`, network
disabled, no writes outside the working directory). The `nessie` CLI talks to
the Nessie macOS app over a localhost socket and reads/writes files outside the
workspace, so **every `nessie` invocation must run with escalated permissions**
or it may fail with sandbox or network errors that are not real Nessie failures.

When you call the shell tool to run any `nessie ...` command:

1. Set `with_escalated_permissions: true` on the call.
2. Provide a short justification, e.g. `"nessie CLI requires localhost network + access to ~/Library/Application Support/Nessie"`.
3. If a command fails with a sandbox / permission denied / network unreachable error, retry the same command with escalated permissions before reporting a Nessie failure.

# Nessie Skill

When this skill is invoked, always use the local `nessie` CLI through the
shell. Do not use Nessie MCP tools exposed by other connector surfaces; those
belong to the MCP connector surface, not the CLI skill surface.

The only Codex-specific rule is the sandbox rule above: every `nessie` command,
including read-only commands like `nessie status`, `nessie search`, and
`nessie context get`, must use escalated permissions.

---

# 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 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, 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.

For knowledge questions, search contexts first, then primary sources. Contexts
are compiled, synthesized knowledge. Transcripts and notes are raw material.
Checking the summary before re-reading the source material is usually faster
and more accurate.

Two-step search pattern:

1. Search contexts first for existing synthesized knowledge. If a context
   matches, read it in full. This often gives the complete picture without
   needing to search transcripts.
2. Search primary sources only if no context exists, the context is stale, or
   primary-source verification or deeper detail is needed. Search across all
   primary source types - including Obsidian notes - not just transcripts.
   For daily or operational artifacts (task logs, daily notes, journals),
   Obsidian is often the primary source and should be included in the initial
   search rather than treated as a fallback.

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 broad discovery where you are unsure what source worlds exist, list
available sources first. Then search all available document types, prioritizing
context results before primary-source results.

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. They are the best starting point for
  understanding any topic the user has previously researched or discussed.
  Always check contexts first for orientation. They may be stale, so verify
  freshness by checking the context date against recent activity.
- 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.
- Profile sections contain structured biographical facts about the user. Check
  the profile for identity, connections, project info, and other recurring
  personal context.

For discovery: contexts first, then transcripts.
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.

## 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, then read them.
- Current-state queries ("what am I working on") should prefer recent content
  without excluding older foundational context.
- 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
   two-step search pattern: contexts first, then transcripts if needed. 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.
2. User references prior work: search contexts first, then transcripts if
   needed. Include synced notes when the prior work likely lives in files,
   memos, vaults, or source documents. Read full content, not just snippets.
3. User asks "what do I know about X": search contexts first for the compiled
   picture, then transcripts for verification 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.

- Search exact names or terms in contexts first for compiled knowledge.
- Search exact names or terms in transcripts and notes when primary-source
  verification is needed or no context exists.
- 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 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.

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
```

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`) or a raw node kind such as `claude_code_chat`, `codex_chat`, or
`obsidian_note`. Use `--since` and `--until` for recency windows; both accept
ISO-8601 timestamps or `yyyy-mm-dd` dates.

`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. For questions like "what did Tiger do yesterday?", start with
`team list` or `integration list --status team_remote`, identify Tiger's
shared integration root, then use `node search` or `node list --since/--until`
under that root.

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>" --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 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
- 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 --parent-id <integration-root-id>
nessie source list --parent-id <node-id> --source-type obsidian
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.

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 --parent`. If shared
roots are sparse, also search all contexts/transcripts/profile because teammate
mentions may live in the user's own conversations.

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.
