---
name: nessie
description: Access the user's personal context from Nessie - their profile, saved contexts, conversation transcripts, and folders. Use when the user references prior work, asks "what do I know about X", or needs personalized responses based on their background. Can also create new contexts and search across all conversation history.
---

# Nessie - Personal Context Engine

Nessie gives you access to the user's personal context - their profile,
saved contexts, raw AI conversation transcripts, and folders. Nessie builds
context by analyzing the user's AI conversation history across ChatGPT,
Claude, Gemini, Perplexity, OpenClaw, and Claude Code.

## Prerequisites

The Nessie macOS app must be running. Check with:
  nessie status

## Commands

### Profile (instant, no cost)
  nessie profile
Returns the user's structured profile: name, biography, expertise, work history,
communication preferences, personality traits, and known connections. Use this to
personalize your responses and understand who you're working with.

### Search (instant, no cost)
  nessie search "<query>"
  nessie search "<query>" --semantic
  nessie search "<query>" --type transcripts
  nessie search "<query>" --type all
  nessie search "<query>" --limit 20
Search across documents. Uses full-text search by default. Add `--semantic`
for vector-based semantic search. Default limit is 10, max 50.

Type options:
- `--type contexts` (default): search only generated contexts
- `--type transcripts`: search only raw conversation transcripts
- `--type all`: search everything (contexts + transcripts)

### Contexts (instant, no cost)
  nessie context list
  nessie context get <id>
  nessie context create --title "<title>" --body "<markdown>" [--emoji "<emoji>"] [--folder <folder-id>]
  nessie context generate "<prompt>"
  nessie context edit <id> --old-string "<text to find>" --new-string "<replacement>" [--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 their folder membership, `get` to retrieve full content by UUID.

Use `create` to save a new context you have synthesized from the user's data.
The body should be structured markdown. Include an emoji that represents the topic.
The context will be automatically indexed for search.

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

Use `generate` to have Nessie research the user's conversation history and
synthesize a new context automatically. This takes 30-120 seconds. Nessie's
agent searches transcripts, reads relevant content, and produces a structured
context. Multiple generations can run in parallel.

### Transcripts (instant, no cost)
  nessie transcript list
  nessie transcript list --type chatgpt
  nessie transcript list --limit 100
  nessie transcript get <id>
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` (chatgpt, claude, gemini, perplexity, openclaw, claude-code,
claude-cowork). Use `get` to read the full conversation content.

### Folders (instant, no cost)
  nessie folder list
  nessie folder get <id>
  nessie folder create --name "<name>"
  nessie folder rename <id> --name "<new name>"
  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.

## Search Strategy

You have two search modes. Use the right one for the query type:

- **Full-text search** (`nessie search "<query>"`): Best for exact terms,
  proper nouns, names, specific phrases. Use when you know what words to
  look for.
- **Semantic search** (`nessie search "<query>" --semantic`): Best for
  conceptual or thematic queries. Use for "what has the user discussed
  about X?" type questions where the exact phrasing is unknown.
- **When uncertain, do BOTH**: one full-text search for specific names
  and terms, one semantic search for conceptual discovery. Synthesize both.

After searching, always read full content with `nessie transcript get <id>`
or `nessie context get <id>`. Search results are starting points, not answers.

## Source Authority Hierarchy

Source types are NOT equal in authority:

- **Conversation transcripts** (synced from ChatGPT, Claude, Gemini,
  Perplexity, OpenClaw) are the **ground truth**. These are the user's
  actual words, decisions, and thinking as they happened. Always prioritize
  transcripts as primary sources.
- **Generated contexts** are **cached views** - past representations of a
  topic synthesized at a point in time. They may be stale, may reflect
  abandoned ideas or outdated product directions, and may not capture the
  user's current thinking. Treat them as optional supplementary reference,
  never as authoritative source data.

When answering questions or creating new content, ground your response in
conversation transcripts first. Use generated contexts only to orient your
search - never as a substitute for reading the actual conversations.

## Query Interpretation

Before searching, infer the likely purpose and scope:

- **Identity and relationship queries** ("who are my investors", "what tools
  do I use") - search broadly with `--type all`, no time filter. These
  answers accumulate over time.
- **Queries with temporal signals** ("recent", "lately", "this week") -
  use `nessie transcript list` to find recent conversations, then read them.
- **Current-state queries** ("what am I working on") - prefer recent
  content but don't exclude older foundational context.
- **Open-ended exploration** ("what have I learned about X") - start with
  a broad search, expand with more specific searches if results are thin.
- **Generation with audience** ("brief for investors", "summary for my
  team") - infer purpose, audience, and tone before researching.
- **When uncertain, do TWO searches**: one full-text for specific names
  and terms, one semantic for conceptual discovery. Synthesize both.

## When to Use

1. **Start of session**: Run `nessie profile` to understand the user.
2. **User references prior work**: Run `nessie search` with relevant terms.
   If results are found, `nessie context get` or `nessie transcript get`
   the best matches - read full content, not just snippets.
3. **User asks "what do I know about X"**: Search transcripts first (ground
   truth), then contexts for supplementary orientation.
4. **User asks about past conversations**: Search transcripts directly with
   `nessie search "<query>" --type transcripts`. Read matching transcripts
   with `nessie transcript get <id>` for full conversation content.
5. **Synthesizing new knowledge**: Follow the Research and Create Workflow.
6. **Organizing contexts**: Use `context move`, `context rename`,
   `context delete`, `folder create`, `folder rename`, and `folder delete`
   to help the user organize their context library.

## Research and Create 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.**

### Step 1: Interpret the Query
Infer purpose, audience, and time scope. Decompose the topic into facets:
- A **person query** needs: their name, their company/role, related people,
  relevant events, key dates
- A **product/project query** needs: the product name, related decisions,
  competitors, evolution over time
- A **relationship query** needs: both parties, the timeline, key
  interactions, current status

### Step 2: Search Broadly
Cast a wide net with multiple searches. A single search is almost never
sufficient.

- `nessie search "<exact name or term>" --type all` for precise matching
- `nessie search "<conceptual topic>" --type all --semantic` for thematic
  discovery
- Search for related terms separately - if researching a person, also
  search their company, related people, and relevant events

### Step 3: Read Deeply (CRITICAL - DO NOT SKIP)

**Search results are breadcrumbs, not answers.** Search snippets are ~300
characters from conversations that may span thousands of words. You MUST
read full sources before synthesizing.

For each relevant search result:
- `nessie transcript get <id>` to read the full conversation
- `nessie context get <id>` for relevant existing contexts
- **Read at least 3-5 full sources before synthesizing**
- 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 transcripts, 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, 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
Use `nessie context create` to save. The body should be structured prose -
headers, bullets, narrative paragraphs. Every claim should trace back to
something you actually read in full.

**Output quality rules:**
- **Thoroughness over brevity.** Capture the 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,
  names. "They had several interactions" is not useful. "Coffee at Blue
  Bottle Jackson Square, Dec 12, 11am. Anna went solo." is useful.
- **Every claim must trace to something you actually read** in full, not
  from a search snippet.
- **Relevance filtering.** A search match does not automatically earn
  inclusion. Ask: does this serve the purpose of the context?
- **Match tone to audience.** Professional for external stakeholders,
  casual for personal notes, precise for technical briefs.

### Epistemic Rules (CRITICAL)

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 as fact in the context.
2. **User questions and hypotheticals** - "can X cause Y?", "what if Z?",
   "I wonder whether..." These are explorations, NOT assertions. The user
   asking about X does NOT mean X is true. Never convert a question into
   a stated fact.
3. **External information the user analyzed** - research, articles, data
   the user looked up. This is reference material, not biographical fact.

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

## When to Use `generate` vs the Research Workflow

**Use `nessie context generate "<prompt>"` when:**
- The topic requires deep transcript research across many conversations
- You want Nessie's native agent to do the searching and reading (it has
  optimized tools with pagination and document type filtering)
- You want to run multiple generations in parallel
- The context should be grounded purely in the user's conversation history

**Use the manual Research and Create 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 creating a context that synthesizes across Nessie data AND other
  sources (files, web, codebase)

**Never do this:**
- Search once, skim snippets, and call `nessie context create` without
  reading any full transcripts. This produces thin, unreliable output that
  is missing critical details the user expects.

## 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 `edit` for targeted updates.** When correcting or updating part of
  a context, use `nessie context edit` to 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.

## Important

- All read commands are instant local reads - use freely.
- Context creation is instant (local write + async embedding).
- All data is local to the user's machine. Nessie never sends documents
  to external services.
- Transcripts are read-only. You cannot modify synced conversations.
