AI session memory: the brief your AI reads before every session so no session starts cold.
Never start cold. Every new AI session opens already briefed on your project.
DeerDawn is AI session memory — your AI's chief of staff — for Claude Code, Claude.ai, Claude Desktop, ChatGPT, Cursor, Windsurf, VS Code, Zed, Codex, and any other MCP-compatible agent. Start a session anywhere and start_session hands the agent the brief: what you were working on, what was decided, and what's blocking — so no session starts cold.
About this repository. DeerDawn is a hosted service. This repo holds the public install guide, the
server.jsonmanifest published to the MCP registry, and a Dockerfile that launches the published npm package. The server itself ships from npm as@deerdawn/mcp-server; its source is not open. Issues and questions are welcome here.
Connect to the hosted MCP endpoint. No API key needed — you sign in with your browser the first time a DeerDawn tool is called.
Claude Code
claude mcp add -s user --transport http deerdawn https://api.deerdawn.com/api/v1/mcp
Every other tool — add a remote MCP server (sometimes called a connector) with this URL:
https://api.deerdawn.com/api/v1/mcp
| Tool | Where |
|---|---|
| Claude.ai | Settings → Connectors → Add custom connector |
| ChatGPT.com | Settings → Connectors → Add MCP server (choose OAuth) |
| Cursor | Settings → MCP → Add server, or add a "url" entry in .cursor/mcp.json |
| VS Code / Copilot | Command palette → MCP: Add Server → HTTP → paste the URL |
| Windsurf, Gemini, others | Add a custom remote / HTTP MCP server with the URL |
Leave any OAuth client fields blank. Click Connect (or restart the tool) and sign in when the DeerDawn tab opens. If your tool connects without prompting for sign-in, the first DeerDawn tool call returns the sign-in URL — open it, sign in once, and retry the call; setup completes automatically.
Then say: "Start a DeerDawn session."
The hosted server exposes 18 core session-memory tools. For repo-file writes, automatic capture hooks, and the full 35-tool set, use the local install below.
Run the server on your machine via npx -y @deerdawn/mcp-server@latest when you want deeper integration:
.deerdawn-context.md / .cursorrules into your repo so context loads with no tool call.Sign-in works the same way — browser OAuth by default, no API key required. On first run without credentials, the server starts a device-flow sign-in: the URL is printed to stderr, saved to ~/.deerdawn/pending-auth.json, and returned in-band by the get_auth_status tool (use that in GUI hosts where stderr isn't visible). After you approve in the browser, credentials are saved to ~/.deerdawn/credentials.json and every future session is authenticated.
Prefer non-interactive auth (CI, headless, SSH)? Create a key at app.deerdawn.com → Settings → API Keys (it starts with dd_) and set DEERDAWN_API_KEY in the config's env block — browser sign-in is then skipped entirely.
Run the setup command — it registers the server, signs you in, and configures hooks in one step:
npx -y @deerdawn/mcp-server@latest setup
Or register manually (user scope so it works across all projects):
claude mcp add -s user deerdawn -e DEERDAWN_API_URL=https://api.deerdawn.com -e DEERDAWN_SURFACE_ID=claude_code -- npx -y @deerdawn/mcp-server@latest
Restart Claude Code after registering. If you haven't signed in yet, call get_auth_status — it returns the browser URL to complete sign-in.
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"deerdawn": {
"command": "npx",
"args": ["-y", "@deerdawn/mcp-server@latest"],
"env": {
"DEERDAWN_API_URL": "https://api.deerdawn.com"
}
}
}
}
~/.cursor/mcp.json (same path on macOS, Linux, and Windows):
{
"mcpServers": {
"deerdawn": {
"command": "npx",
"args": ["-y", "@deerdawn/mcp-server@latest"],
"env": {
"DEERDAWN_API_URL": "https://api.deerdawn.com"
}
}
}
}
macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %APPDATA%\Codeium\windsurf\mcp_config.json
{
"mcpServers": {
"deerdawn": {
"command": "npx",
"args": ["-y", "@deerdawn/mcp-server@latest"],
"env": {
"DEERDAWN_API_URL": "https://api.deerdawn.com"
}
}
}
}
Add to .vscode/settings.json or user settings.json:
{
"mcp": {
"servers": {
"deerdawn": {
"command": "npx",
"args": ["-y", "@deerdawn/mcp-server@latest"],
"env": {
"DEERDAWN_API_URL": "https://api.deerdawn.com"
}
}
}
}
}
For Continue (~/.continue/config.json):
{
"mcpServers": [
{
"name": "deerdawn",
"command": "npx",
"args": ["-y", "@deerdawn/mcp-server@latest"],
"env": {
"DEERDAWN_API_URL": "https://api.deerdawn.com"
}
}
]
}
Add to ~/.config/zed/settings.json:
{
"context_servers": {
"deerdawn": {
"command": {
"path": "npx",
"args": ["-y", "@deerdawn/mcp-server@latest"],
"env": {
"DEERDAWN_API_URL": "https://api.deerdawn.com"
}
}
}
}
}
Add to ~/.codex/config.toml:
[mcp_servers.deerdawn]
command = "npx"
args = ["-y", "@deerdawn/mcp-server@latest"]
startup_timeout_sec = 120
[mcp_servers.deerdawn.env]
DEERDAWN_API_URL = "https://api.deerdawn.com"
To skip browser sign-in in any of these configs, add "DEERDAWN_API_KEY": "dd_your_key_here" to the env block (Codex TOML: DEERDAWN_API_KEY = "dd_your_key_here" under [mcp_servers.deerdawn.env]).
Some MCP hosts expose tools with a server prefix (for example deerdawn-get_auth_status) instead of bare names (get_auth_status).
If a tool name is not found, retry with the deerdawn- prefixed variant.
All optional. With no env vars at all, the server starts and walks you through browser sign-in.
| Variable | Required | Default | Description |
|---|---|---|---|
DEERDAWN_API_URL | No | https://api.deerdawn.com | API base URL. Only change for self-hosted or staging. |
DEERDAWN_SURFACE_ID | No | auto-detected | Which tool this server runs in (claude_code, cursor, codex). Detected from the MCP client when unset; set it explicitly to pin session attribution. |
DEERDAWN_API_KEY | No | — | API key (dd_...) for non-interactive auth (CI/headless). Default is browser OAuth sign-in. Get one at app.deerdawn.com → Settings → API Keys. |
The local server exposes 35 tools (the hosted remote exposes 18 core ones). These are the ones to reach for in every session.
start_sessionCall this at the start of every session. Returns the active project context for the current directory plus a compact map of all other projects — one API call, ~100–180 tokens total. Do not call list_context_map + get_context separately; this replaces both.
update_contextPush a context update. Call this whenever: a decision is made, the current task changes, a blocker is found, or meaningful progress happens. Don't wait until the end of the session — updates are cheap and keep the brief every new session reads current.
project_id: "proj-abc123"
summary: "Switched auth from JWT to session tokens — JWT had XSS risk via localStorage. Now using Redis-backed sessions."
get_contextGet project context by section. Defaults to [task, status] (~30 tokens). Pass sections=["all"] for everything.
project_id: "proj-abc123"
sections: ["task", "decisions", "blocking"]
import_local_contextImport context from CLAUDE.md, AGENTS.md, or .cursorrules in the current directory. Call without confirmed: true first — it shows a free preview of what would be imported. Then call again with confirmed: true to commit.
complete_setupOne-call setup fallback for brittle hosts: checks auth status, applies local setup for a surface, and runs import_local_context preview + confirmation if local files are found.
Example:
complete_setup
{
"surface": "cursor"
}
cleanup_contextClean up task state at handoff or finish time. Use this to mark the active task complete and clear open-task command history so the next agent sees clean state.
When the task is clearly done and there are no unresolved questions, call this automatically with complete_task=true (no extra confirmation loop).
cleanup_context
{
"complete_task": true
}
search_contextSearch across all projects. Examples: "decisions about authentication", "projects using PostgreSQL", "what's blocking the billing work".
list_projectsList all projects with IDs and last-updated timestamps. Use this when you explicitly need a project index. For normal startup, prefer start_session.
create_projectCreate a new project when starting something that has no existing project entry.
get_workspace_overviewUse mode=startup at the start of a session for a compact orientation brief. Use mode=overview when the user asks "what am I working on?" or wants a broader picture.
get_workspace_entitiesDrill into typed workspace knowledge: decisions, tools, environments, capabilities. Filter by types, query, status, or project_id.
get_project_mapReturn durable file-level project memory: hot paths, entrypoints, named surfaces, and debugging notes. Use this before repo-wide search when the path may already be known.
find_known_pathsSearch DeerDawn’s durable path memory for queries like "auth modal" or "signup route" before using repo search.
get_next_best_contextGet ranked suggestions for what context to fetch next, given the current tool and working directory.
upsert_workspace_entitiesCreate or update durable workspace knowledge — tools, environments, architectural decisions, or capabilities that apply across multiple projects.
record_hot_pathsWrite discovered file or folder paths back into DeerDawn so future sessions can orient without re-discovering them.
record_debug_findingStore concise durable debugging findings, optionally tied to specific paths.
A fresh AI session knows nothing about your project — it would start cold. DeerDawn hands it the brief instead.
You work in Claude Code, Cursor, or ChatGPT
→ DeerDawn captures the session (via MCP, browser extension, or desktop app)
→ Extraction pipeline distills what changed (task, decisions, blockers, stack) into the brief
→ The brief is stored per-project in your workspace and kept current
→ Next session would start cold — instead start_session hands it the brief in one call
→ Every new session opens already briefed, never from a blank slate
The brief is stored per-project. Critical decisions are flagged and always surface first, regardless of token budget. If sections are trimmed, you'll see exactly what was dropped and how to retrieve it.
After saving your config and restarting the agent, call start_session first:
start_session
If it returns your active project context, DeerDawn is already connected — you're done, skip the rest. (If you connected through the hosted remote / claude.ai connector rather than the local server, this is the normal path: apply_setup and import_local_context won't exist on that build and aren't needed — context loads automatically.)
If start_session reports you're not authenticated, complete sign-in and seed context:
get_auth_status
import_local_context
import_local_context {"confirmed":true}
start_session
cleanup_context {"complete_task":true}
If your host prefixes tool names, use deerdawn-get_auth_status and deerdawn-import_local_context instead.
If your host is flaky during setup, run complete_setup {"surface":"claude_code"} as a one-call fallback — it checks auth, applies surface setup automatically, and imports local context in a single call. apply_setup is called internally and does not need to be run manually.
You should get back your active project context (or a prompt to import local context if it's a new workspace). If you get an error instead:
get_auth_status and finish browser sign-in via the returned URL (if you set DEERDAWN_API_KEY instead, confirm it starts with dd_)~/Library/Logs/Claude/mcp*.log (Claude Desktop) or equivalentDeerDawn tools don't appear in your agent The server itself starts with zero env vars — a missing API key never prevents startup. If no DeerDawn tools show up:
~/Library/Logs/Claude/mcp*.logAuthentication error / not signed in
Call get_auth_status — it returns a browser sign-in URL. Open it, approve, then retry the tool call; setup completes automatically. If you set DEERDAWN_API_KEY, it must start with dd_.
Sign-in reports a rate limit (HTTP 429) This happens after several quick restarts during setup. Wait a minute before retrying — re-running setup immediately will keep hitting the limit.
start_session returns no projects
Call import_local_context (without confirmed: true first) to seed context from a CLAUDE.md or AGENTS.md in your current directory.
Slow responses
The extraction pipeline runs on first import. Subsequent start_session calls are fast (cached context lookup, no LLM call unless something changed).
npm install
npm run build # compile TypeScript
npm run dev # watch mode
npm test # run tests
npm run lint
MIT
Source-derived launch command. Check the maintainer’s required arguments and credentials before running:
npx -y @deerdawn/mcp-serverMerge this template into ~/Library/Application Support/Claude/claude_desktop_config.json. Keep existing servers. Add any arguments, credentials, and permissions required by the maintainer; this template has not been install-tested.
{
"mcpServers": {
"com-deerdawn-deerdawn": {
"command": "npx",
"args": [
"-y",
"@deerdawn/mcp-server"
]
}
}
}Restart Claude Desktop completely for changes to take effect. Confirm the server appears connected in the client’s tool list, then try a read-only example from its documentation.
Claude Desktop setup reference@deerdawn/mcp-servernpmcom.deerdawn/deerdawn works with any MCP-compatible client. Copy the config snippet from the Configuration section above and add it to the file shown for your client, then restart the application.
~/Library/Application Support/Claude/claude_desktop_config.jsonRestart Claude Desktop completely for changes to take effect.~/.cursor/mcp.jsonRestart Cursor for changes to take effect..vscode/mcp.jsonReload VS Code window for changes to take effect.~/.codeium/windsurf/mcp_config.jsonRestart Windsurf for changes to take effect..mcp.jsonSave at the project root, then start Claude Code in that project and review the MCP server approval prompt. Keep real credentials out of shared files.