npm package: @nokos/agent
Description: Nokos agent — MCP server + CLI for Claude Code, Codex, and more
Latest version: 3.8.0
Deprecated: This package has been renamed to @nokos/cli. Install @nokos/cli instead.

# @nokos/agent

**Connect your AI coding tools to Nokos** — every session with Claude Code, Codex, or ChatGPT becomes a searchable, AI-organized memo.

```bash
npm install -g @nokos/agent
nokos login
nokos setup claude-code
# That's it. Your coding sessions are now auto-saved to Nokos.
```

## What is Nokos?

[Nokos](https://nokos.ai) is an AI-powered note-taking app that automatically organizes your memos — generating titles, tags, categories, summaries, and daily/weekly digests from everything you save.

`@nokos/agent` bridges your AI coding tools with Nokos, giving you:

- **Auto-saved coding sessions** — every Claude Code / Codex session is automatically summarized and saved
- **MCP tools in Claude Code** — search, read, and write your Nokos memos directly from the terminal
- **Cross-tool knowledge base** — notes from Claude Code, Codex, ChatGPT, and the web app, all in one place

## Quick Start

### 1. Install & Login

```bash
npm install -g @nokos/agent
nokos login
```

This opens your browser for authentication. Your credentials are stored securely in `~/.nokos/credentials.json` (mode 0600).

### 2. Set Up Claude Code

```bash
nokos setup claude-code
```

This configures two things:

| Feature | What it does |
|---|---|
| **MCP Server** | Claude Code can search/read/write your Nokos memos |
| **SessionEnd Hook** | Coding sessions are automatically saved as memos |

### 3. Verify

```bash
nokos status
```

```
Account: you@example.com (Pro)
API:     ✓ Connected
Token:   ✓ Valid (expires in 29d)

Tools:
  Claude Code:  MCP ✓  Hook ✓
```

## MCP Tools

Once configured, Claude Code has access to 3 Nokos tools:

### `search_nokos`

Search your memos and AI session logs with keywords or natural language.

```
> Search Nokos for "React authentication"

Found 3 items:
1. [Memo] React Auth with Firebase (abc123)
   Setting up Firebase Auth with React Router...
   Tags: react, firebase | Updated: 3/9(日) 18:42

2. [Session] Debugging auth flow (def456)
   Fixed CORS issue with Firebase token verification...
```

Supports natural language on Plus/Pro plans (e.g., "important memos from last week about TypeScript").

### `get_nokos`

Fetch full content of a memo or session in Markdown format.

```
> Get nokos abc123

# React Auth with Firebase
Type: Memo
Tags: react, firebase
Created: 2026-03-01 | Updated: 2026-03-09
---
Setting up Firebase Auth with React Router...
```

### `save_session`

Save the current AI conversation as a session log for future reference.

```
> Save this conversation to Nokos

Session saved: "Debugging PostgreSQL Connection Pooling" (ghi789)
```

*`save_session` requires Plus or Pro plan.*

## Auto-Saved Coding Sessions

With the SessionEnd hook, every Claude Code session is automatically:

1. **Compressed & uploaded** (gzip, up to 2MB)
2. **Summarized by AI** — key decisions, files changed, what was accomplished
3. **Tagged & categorized** — searchable alongside your other memos
4. **Viewable on web** — with full session details at nokos.ai

No manual action needed. Just code as usual.

## Commands

| Command | Description |
|---|---|
| `nokos login` | Authenticate via browser (Device Authorization Flow) |
| `nokos logout` | Remove stored credentials |
| `nokos setup [tool]` | Configure AI tool integration (`claude-code`, `codex`) |
| `nokos status` | Show account, connection, and tool status |
| `nokos push <file>` | Manually push a JSONL session file |
| `nokos mcp` | Start MCP server (called by AI tools automatically) |

## How It Works

```
┌─────────────┐     MCP (stdio)     ┌──────────────┐     HTTPS     ┌────────────┐
│ Claude Code  │ ◄─────────────────► │ @nokos/agent │ ◄───────────► │ Nokos API  │
│ Codex / etc. │    search, read,    │  (local CLI)  │   auth,      │ (Cloud Run)│
│              │    write memos      │              │   sync       │            │
└──────┬───────┘                     └──────────────┘              └─────┬──────┘
       │ SessionEnd hook                                                 │
       │ (auto-save session)                                            │
       └────────────────────────────────────────────────────────────────┘
```

- **Auth**: Device Authorization Flow — JWT tokens with auto-refresh
- **MCP Transport**: stdio (local subprocess, no network for tool communication)
- **Session Upload**: gzip-compressed JSONL via HTTPS

## Plans & Limits

| Feature | Free | Plus | Pro |
|---|---|---|---|
| Search (memos + sessions) | 50/month | 500/month | 5,000/month |
| Read (memos + sessions) | 50/month | 500/month | 5,000/month |
| Save sessions | — | 500/month | 5,000/month |
| Auto-save coding sessions | — | — | 300/month |
| Natural language search | — | 500/month | 5,000/month |

## Requirements

- Node.js 20+
- [Nokos account](https://nokos.ai) (free to sign up)

## Links

- [Nokos Web App](https://nokos.ai)
- [GitHub](https://github.com/tmkkd/nokos)
- [npm](https://www.npmjs.com/package/@nokos/agent)

## License

MIT