Cortex Chat

Cortex Chat is an unofficial desktop-only Obsidian plugin that adds an AI chat sidebar with vault context, note references, PDF text extraction, session history, shared _cortex memory, and backups for assistant-assisted edits.

This plugin is not affiliated with Obsidian, OpenAI, or Codex.

Features

• Chat with an assistant using the active note, outgoing links, @ references, shared memory, and recent sessions.
• Review a per-response context manifest that shows which notes, references, memory files, sessions, and related-note candidates were used.
• Toggle context sources from the chat workbench before sending, including active note, links, mentions, folders, memory, recent sessions, and local related notes.
• Pin previous assistant answers as explicit context, then remove individual context sources from the workbench before sending.
• Use lightweight local related-note retrieval when enabled; the persistent index lives in _cortex/index/vault-keywords.json and is bounded by settings.
• Preview assistant insertions with a diff-style view before they touch a note, with automatic backups and approved-change logs before applying.
• Load context from Markdown notes and text-based PDFs.
• Use Planner / Copilot for read-only analysis and Execute / Unrestricted for action-oriented work.
• Store sessions, memory candidates, outbox files, and backups in _cortex/.
• Optionally use the local Codex CLI as a desktop fallback.

Requirements

• Obsidian 1.8.0 or newer.
• Obsidian desktop. Mobile is intentionally unsupported.
• Optional: Codex CLI installed and authenticated with ChatGPT if local fallback is used.
• Optional: a backend URL if you run a backend under your control.

Installation

Community plugins

After approval in the Obsidian community directory, install Cortex Chat from Obsidian:

Settings -> Community plugins -> Browse -> Cortex Chat -> Install -> Enable

The plugin creates its own local data.json on first run.

BRAT or manual testing

For beta testing, install with BRAT from this repository or copy the release files into:

.obsidian/plugins/cortex-chat/

Required release files:

main.js
manifest.json
styles.css

Security and Privacy

Cortex Chat does not include client-side telemetry, ads, or analytics.

The plugin may access:

• The active Obsidian vault, including notes and user-configured folder roots.
• Vault file paths via Obsidian enumeration APIs. This is required for @ references, folder selection, drag-and-drop context, and the optional local related-note index.
• The system clipboard only when the user explicitly clicks a copy action. Cortex Chat writes assistant responses to the clipboard; it does not read clipboard contents.
• _cortex/ inside the vault for shared memory, sessions, candidates, outbox files, and backups.
• _cortex/index/vault-keywords.json for the optional local RAG keyword index.
• ~/.cortex-chat for local runtime state that should not sync through Obsidian Sync.
• ~/.codex/config.toml only if the user explicitly enables Codex vault trust.
• Temporary OS folders for local Codex prompt and output files.
• Network URLs configured by the user for a backend.
• Codex/OpenAI services indirectly through the authenticated local Codex CLI.

Do not commit or publish:

• data.json
• _cortex/
• .obsidian/
• local runtime folders
• backend runtime files
• tokens, secrets, logs, sessions, backups, or vault content

Technical folders such as node_modules, .git, .obsidian, _cortex, dist, build, .cache, .vite, and coverage are ignored as context sources.

Use Context exclusions in settings for vault-specific private paths or patterns that should never be attached to a prompt or indexed for related-note retrieval.

Work Modes

• Planner / Copilot: read, analyze, summarize, and propose without modifying vault files unless the user clearly asks.
• Execute / Unrestricted: can produce action-oriented output. User-visible note insertions still use the approval preview by default and create backups plus _cortex/outbox/approved-changes logs before applying.

Prompt Profiles and Commands

Settings include prompt profiles for Researcher, Editor, Planner, and Safe executor. The composer also supports quick commands:

/summarize
/rewrite
/extract-actions
/build-context

Development

lib/ contains the maintainable CommonJS source modules. Obsidian loads main.js, so main.js is generated as a self-contained runtime.

If you keep the source repository inside a synced vault, _cortex-chat/ is a convenient local folder name because it sits next to _cortex/. This is only a development convention. The installed plugin folder must remain:

.obsidian/plugins/cortex-chat/

After changing files in lib/, run:

node scripts/bundle-main.js

Before publishing a release:

node scripts/bundle-main.js
node --check main.js
node scripts/prepare-release.js

Attach main.js, manifest.json, and styles.css to the GitHub release whose tag matches manifest.version.