Working with Nucleus

What Nucleus is

Nucleus is Audity’s persistent memory layer. It remembers facts about your clients (memories), ingests text from outside sources like meeting transcripts (captures), and produces proactive observations from background jobs (insights). The agent API exposes the read and write surface of Nucleus so you can query and update it from Claude, Cursor, n8n, or any other agent, the same way Audity’s internal AI does inside the web app.

What’s exposed to the agent

Capability	Endpoint	Notes
List memories	`GET /api/nucleus/memories?type=&projectId=`	Three types: `client`, `pattern`, `preference`
Create a memory	`POST /api/nucleus/memories`	Source defaults to `explicit` when created via API
Update a memory	`PATCH /api/nucleus/memories`	Body-passed `memoryId` + `subject` and/or `content`. Mirrors the contacts pattern.
Delete a memory	`DELETE /api/nucleus/memories/{id}` (idempotent 204) or `DELETE /api/nucleus/memories` with `{memoryId}` in body	Both soft-delete (`is_archived = true`). Prefer the path form, it’s idempotent.
List captures	`GET /api/nucleus/captures?channel=&status=&projectId=`	8 channels: `transcript`, `voice_note`, `text_note`, `email`, `calendar`, `zoom`, `crm_sync`, `file_drop`
Get a capture + items	`GET /api/nucleus/captures/{id}`	Returns `{ capture, items }` (extracted action items, decisions, key insights)
Submit a text capture	`POST /api/nucleus/capture/note`	Triggers extraction pipeline. Rate-limited to 30/hour.
Reprocess a capture	`POST /api/nucleus/captures/{id}`	Resets status to `pending` and re-runs extraction. Useful after a failure.
Delete a capture	`DELETE /api/nucleus/captures/{id}`	Soft delete. Idempotent.
List contacts	`GET /api/nucleus/contacts?search=`	Lightweight CRM. Search matches name + company, case-insensitive.
Create / update / delete contact	`POST` / `PATCH` / `DELETE /api/nucleus/contacts`	All take the contact in the JSON body, not the URL path.
Read insights	`GET /api/nucleus/insights?type=&unreadOnly=`	Generated by background jobs
Get prompt suggestions	`GET /api/nucleus/suggestions?projectId=`	3 contextual prompts

The full request and response shapes are in the API Reference.

What’s not exposed (and why)

Nucleus chat (/api/nucleus/chat). Exposing it would turn Audity into a chatbot middleman, your agent IS the chatbot. Use the underlying memory and capture endpoints directly.
Live co-pilot (/api/nucleus/live). Real-time, requires a UI.
Backfill and admin operations. Internal-only.
Slash commands. Internal Nucleus chat affordances.

Pattern: “What does Audity remember about this client?”

Search my Audity Nucleus for everything related to Acme Corp's stakeholder
concerns. Cross-reference with any patterns I've seen across other healthcare
clients.

What runs:

GET /api/nucleus/memories?type=client filtered to projectId for Acme
GET /api/nucleus/memories?type=pattern for cross-client patterns
The agent synthesizes the join

This is the killer use case: your accumulated client knowledge becomes searchable from any AI assistant, not just inside Audity. Every memory carries confidence (0–1) and sourceType (explicit, extracted, detected). Tell the agent to cite both, detected patterns under 0.8 confidence are hypotheses, not facts.

Pattern: “Capture this for me”

After a client call, paste a transcript:

Here's the transcript from my call with Initech this morning. Drop it into
Nucleus as a capture for project {projectId}. Once it's processed, summarize
the action items and decisions.

What runs:

POST /api/nucleus/capture/note with the transcript text and projectId. Returns immediately with the capture in pending status.
The capture goes into the extraction pipeline (Inngest job, runs async). Action items, decisions, key insights, and contact mentions are extracted into structured items.
After ~15–60 seconds: GET /api/nucleus/captures/{id} returns { capture, items }. The agent reads the items and summarizes.

The agent should poll, not block. If the capture is still in processing after a minute, something failed, call POST /api/nucleus/captures/{id} to trigger a reprocess.

Pattern: “What insights are sitting in my queue?”

Pull my unread Audity insights. Group by type. Tell me which look most
time-sensitive.

GET /api/nucleus/insights?unreadOnly=true returns the typed insight set. In v1, four insight types are actively generated by background jobs:

overdue_followup, leads or clients you said you’d follow up with, where the date has passed
pattern_detected, cross-client pattern Nucleus noticed in your portfolio
similar_lead, a new lead matches a profile of a past project
stale_client, a client who’s been quiet long enough to risk going cold

The OpenAPI spec also lists pre_meeting, referral_opportunity, portfolio_insight, and content_suggestion as valid types. These are reserved in the schema but not yet produced by any background job. Don’t promise them to your customers as if they’re live; they aren’t.

Pattern: “Daily Nucleus brief”

A common n8n / scheduled workflow:

Every weekday at 8am:
Get unread Audity insights
Get Audity captures from the last 24 hours
Summarize as a 5-bullet brief and post to Slack

This pairs cleanly with n8n’s MCP Client node, every Audity tool the daily brief needs (list_insights, list_captures) is exposed.

Memory hygiene

Memories accumulate. Periodically have the agent prune:

List my Audity memories of type "pattern". Find any that look duplicate or
contradictory. Don't delete anything yet, propose deletes I can approve.

What runs:

GET /api/nucleus/memories?type=pattern
The agent dedupes / contradicts client-side
The agent proposes a deletion list, wait for approval
After approval: DELETE /api/nucleus/memories/{id} for each approved ID

DELETE /api/nucleus/memories/{id} is idempotent and soft (sets is_archived = true); the row stays on disk for audit purposes. To edit a memory in place, use PATCH /api/nucleus/memories with the target ID in the body:

{ "memoryId": "<uuid>", "content": "<new content>", "subject": "<new subject>" }

At least one of subject / content must be present. PATCH returns { success: true } on success. There’s no separate “version history”, the row is updated in place, so reserve PATCH for content corrections rather than running edit logs.

Confidence and sourceType

Every memory has:

confidence (0.00–1.00), how trustworthy the memory is
sourceType
- explicit, you (or your agent) asked Nucleus to remember it
- extracted, pulled from a conversation by the extraction pipeline
- detected, AI-identified pattern

When the agent surfaces a memory, ask it to include both numbers. A high-confidence explicit memory is a fact. A low-confidence detected pattern is a hypothesis worth sanity-checking against fresh data.

Get Started

Workflows

Connect Your Agent

What Nucleus is

What’s exposed to the agent

What’s not exposed (and why)

Pattern: “What does Audity remember about this client?”

Pattern: “Capture this for me”

Pattern: “What insights are sitting in my queue?”

Pattern: “Daily Nucleus brief”

Memory hygiene

Confidence and sourceType

What’s next

​What Nucleus is

​What’s exposed to the agent

​What’s not exposed (and why)

​Pattern: “What does Audity remember about this client?”

​Pattern: “Capture this for me”

​Pattern: “What insights are sitting in my queue?”

​Pattern: “Daily Nucleus brief”

​Memory hygiene

​Confidence and sourceType

​What’s next

What Nucleus is

What’s exposed to the agent

What’s not exposed (and why)

Pattern: “What does Audity remember about this client?”

Pattern: “Capture this for me”

Pattern: “What insights are sitting in my queue?”

Pattern: “Daily Nucleus brief”

Memory hygiene

Confidence and sourceType

What’s next