Sessions & Safety — Noah Documentation

Sessions

A session is a single conversation with Noah. When you open Noah and start typing, you're inside a session. Everything that happens during that conversation — messages, tool calls, system changes, playbook runs — is tracked and stored as part of that session.

Sessions are the fundamental unit of work in Noah. They provide context, history, and accountability for every interaction.

What sessions track

Messages — Your messages and Noah's responses, in order
Tool calls — Every diagnostic or action tool Noah invoked
Changes made — System modifications, recorded in the change journal
Playbook runs — Which playbooks were activated and their results

Session metadata

Each session stores the following metadata:

Field	Description
`title`	A short label for the session, auto-generated from the first message or manually renamed
`created_at`	When the session started
`ended_at`	When the session was closed (null if still active)
`message_count`	Total number of messages in the conversation
`resolved`	Whether the issue was marked as resolved

Managing sessions

Rename — Give a session a more descriptive title after the fact
Mark as resolved — Flag a session as complete when the issue is fixed
Export — Save a session as a formatted Markdown file

Session lifecycle

Every session follows a simple lifecycle:

Create — A new session starts when you begin a conversation. Noah assigns it a unique ID and timestamps it.
Active — You exchange messages with Noah. Tool calls happen, changes are recorded, playbooks may be activated. The session stays active as long as the conversation continues.
End — The session closes when you start a new conversation, close the app, or explicitly end it. The ended_at timestamp is recorded.

Context management

Long sessions can accumulate a lot of context. To keep Noah responsive and within the AI model's context window, Noah uses compressed summaries:

When a session grows long, Noah generates a compressed summary of the conversation so far
The summary captures key facts, decisions, and findings — without the full back-and-forth
This keeps Noah fast and accurate, even in extended troubleshooting sessions

ℹ️

Context compression is automatic. You don't need to manage it — Noah handles it behind the scenes. If you notice Noah forgetting earlier context in a very long session, it may be because the compressed summary didn't capture that detail. Starting a new session is always an option.

Session restore

You can reopen any past session from the session history. When you do, Noah loads:

Recent messages — The latest messages from the original conversation
Compressed summary — A summary of earlier context, so Noah remembers what happened without loading every message

This means you can pick up where you left off. If a fix didn't stick or you need to revisit a problem, open the old session and Noah already has the context.

💡

Session restore is especially useful for multi-day troubleshooting. Close the app, come back tomorrow, and reopen the session — Noah remembers the diagnosis, the changes it made, and what was left to do.

Safety tiers

Every tool Noah can use has a safety classification. This determines whether Noah can run it automatically or needs your permission first. There are three tiers:

Read-only

Gathering information. No system changes.
Checking WiFi status, reading files, listing processes, querying DNS. These tools only observe — they never modify your system. Noah runs them automatically without asking.

Safe action

Low-risk writes that don't affect system state.
Saving a knowledge note, writing a preference file, recording a device fact. These are changes within Noah's own data, not your operating system. Noah runs them automatically.

Needs approval

System-modifying actions that require your explicit consent.
Changing DNS settings, killing processes, running shell scripts, modifying system configuration. Noah shows an approval dialog with the action details and its reasoning before proceeding.

The approval dialog

When Noah wants to perform an action that needs approval, it pauses and shows you:

What it wants to do — The specific tool and its parameters (e.g., "Run shell command: sudo networksetup -setdnsservers Wi-Fi 8.8.8.8")
Why it wants to do it — Noah's reasoning for why this action is the right next step
Approve or Deny — You decide. If you deny, Noah will try an alternative approach or ask for guidance.

⚠️

Approval timeout. If you don't respond to an approval request within 5 minutes, it is automatically denied. This prevents Noah from hanging indefinitely while waiting for input on an unattended machine.

Why this matters

The safety tier system means Noah can be fast for read-only diagnostics (no waiting for approval to check your network) while still giving you full control over anything that could change your system. You never have to worry about Noah making unexpected changes.

Change journal

Every system change Noah makes is recorded in a change journal. Think of it as an audit log for everything Noah does to your machine.

What gets recorded

Each journal entry includes:

Field	Description
`tool_name`	Which tool performed the action (e.g., `run_shell`, `set_dns`)
`description`	Human-readable summary of what changed
`undo_instruction`	How to reverse the change (tool name and parameters)
`session_id`	Which conversation triggered this change
`timestamp`	When the change was made

Session-scoped changes

Changes are linked to the session that created them. When you review a past session, you can see exactly what Noah modified during that conversation. This makes it easy to:

Audit what happened during a troubleshooting session
Identify which change caused a new problem
Undo specific changes from a specific session

💡

The change journal is stored locally in Noah's database. It persists across app restarts, so you can always go back and review what Noah did — even weeks later.

Undo system

When Noah records a change, it also records how to reverse it. This gives you a safety net: if a fix makes things worse, you can undo it.

How undo works

Recording — When Noah performs an action, it stores an undo_tool and undo_input alongside the change journal entry. These describe the reverse operation.
Reviewing — Open a past session and browse its changes. Each change shows what was done and whether an undo is available.
Undoing — Select a change and trigger the undo. Noah executes the reverse operation and marks the change as reversed in the journal.

Limitations

Not every change is perfectly reversible:

Fully reversible — DNS changes, preference edits, configuration toggles. The undo restores the exact previous state.
Best-effort — Process kills, cache clears, some script executions. The undo does its best but can't always restore state that was never saved.
Not reversible — Some destructive operations don't have a meaningful undo. In these cases, the journal records the change for audit purposes but no undo tool is attached.

ℹ️

Undo marks the change as reversed with a logical flag — it doesn't delete the journal entry. Your full history is always preserved for audit purposes.

Secret storage

Sometimes Noah needs credentials to complete a task — a WiFi password, an API key, or a service account token. Noah handles these securely through its secret storage system.

How it works

Secure input — When Noah needs a secret, it shows a dedicated input field (like a password field) that masks your input
Memory-only storage — Secrets are held in memory for the duration of the session. They are never written to disk.
Never sent to the LLM — Secrets are used directly by tools (like write_secret) that need credentials. The secret value is never included in the AI conversation context.
Never logged — Secret values don't appear in session logs, change journals, or debug output
Session-scoped — When the session ends, all secrets are cleared from memory

⚠️

Secrets don't persist across sessions. If you start a new session that needs the same credentials, you'll need to enter them again. This is by design — it prevents secrets from accumulating on disk.

Data storage

Noah stores all of its data locally on your device in a SQLite database called journal.db, located in Noah's application data directory.

Data directory locations

Platform	Path
macOS	`~/Library/Application Support/app.onnoah.desktop/`
Windows	`%APPDATA%\app.onnoah.desktop\`
Linux	`~/.local/share/app.onnoah.desktop/`

What's stored

The database contains:

Sessions — Conversation metadata (title, timestamps, resolved flag)
Messages — Full conversation history for every session
Changes — The change journal with undo instructions
Scan results — Health check outputs and scores
Health scores — Historical health score data
Auto-heal runs — Records of automated playbook executions
Settings — App preferences and configuration

Reliability

Noah includes protections against database corruption:

Backup on corruption — If Noah detects a corrupted database, it backs up the existing file to journal.db.bak and creates a fresh database. Your old data is preserved in the backup file.
Auto-migration — When you update Noah and the database schema changes, migrations run automatically. No manual steps required.

Export

Noah supports exporting session data for record-keeping, compliance, or sharing with colleagues.

Session export

Sessions can be exported as formatted Markdown files. The export includes:

Conversation transcript — All messages between you and Noah, in order
Changes made — A summary of every system modification, pulled from the change journal
Playbook runs — Which playbooks were activated, their progress, and outcomes

Health report export

Health check results can be exported as plain text. This is useful for:

Compliance audits that require documented device health
Sharing system status with IT teams
Keeping records of your device's health over time

Privacy

Noah is designed with a local-first architecture. Your data stays on your device unless you explicitly choose otherwise.

What stays local

All processing happens on your device — diagnostics, tool execution, and data storage
The database (journal.db) never leaves your machine
Knowledge files (playbooks, device notes, past issues) are stored locally
Secrets are held in memory only and never enter the LLM context

What leaves your device

LLM calls — Your conversation messages are sent to the AI provider (Anthropic by default, or your configured proxy) for generating responses. This is required for the AI to work.
Fleet sync (opt-in) — If you link your device to a Noah Fleet dashboard, session summaries and health reports are synced to the fleet server. This is entirely opt-in and requires explicit linking.

What Noah never does

No telemetry is sent without your explicit consent
No secret values are included in LLM requests
No data is sold or shared with third parties
No background data collection beyond health checks you've enabled

ℹ️

Fleet sync is not surveillance. When linked to a fleet, Noah sends session summaries (not full transcripts) and health scores (not raw system data). Your admin sees that a problem was fixed, not every command that was run. You can unlink at any time.