Joa

CI npm License: MIT

Persistent activity journal for AI agents. Log decisions, file changes, errors, and observations — then query them for context across sessions.

What is joa?

AI agents lose context between sessions. joa gives them a journal — a structured log of what happened and why, queryable by any agent on any platform. Start a session with catchup to see what happened last time. Log meaningful events as you work. Future sessions inherit the full picture.

Works as a CLI tool and as an MCP server for agent platforms like Claude Code, Cursor, Gemini CLI, Codex, Amp, and more.

Install

npm install -g @neethan/joa

Requires Node.js >= 18.

Quick Start

# Log an entry
joa log "Chose PostgreSQL over MongoDB for user data" -c decision -t project:api

# See recent activity
joa catchup

# Search the journal
joa search "PostgreSQL"

# Check journal health
joa status

MCP Server Setup

joa runs as an MCP server so agents can log and query entries directly.

Claude Code (~/.claude.json or .mcp.json):

{
  "mcpServers": {
    "joa": {
      "command": "joa",
      "args": ["mcp", "--agent", "claude-code"]
    }
  }
}

Cursor (~/.cursor/mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "joa": {
      "command": "joa",
      "args": ["mcp", "--agent", "cursor"]
    }
  }
}

Or run joa setup for interactive configuration.

{
  "mcpServers": {
    "joa": {
      "command": "joa",
      "args": ["mcp", "--agent", "gemini-cli"]
    }
  }
}

[mcp_servers.joa]
command = "joa"
args = ["mcp", "--agent", "codex"]

{
  "amp.mcpServers": {
    "joa": {
      "command": "joa",
      "args": ["mcp", "--agent", "amp"]
    }
  }
}

{
  "mcp": {
    "joa": {
      "type": "local",
      "command": ["joa", "mcp", "--agent", "opencode"]
    }
  }
}

{
  "servers": {
    "joa": {
      "type": "stdio",
      "command": "joa",
      "args": ["mcp", "--agent", "github-copilot"]
    }
  }
}

{
  "mcpServers": {
    "joa": {
      "command": "joa",
      "args": ["mcp", "--agent", "pi"]
    }
  }
}

CLI Commands

Logging:

joa log <summary>       Log an entry
  -c, --category <cat>  Category (decision, change, observation, error, ...)
  -t, --tag <tag>       Tag (repeatable, e.g. project:api)
  --thread <id|new>     Thread ID or "new" to start one
  --detail <json>       Structured detail as JSON

Querying:

joa query               Query with filters
joa catchup             Recent entries (last 7 days)
joa threads             Active threads summary
joa timeline            Chronological entries
joa decisions           Decision entries
joa search <term>       Full-text search

Maintenance:

joa status              Journal health and stats
joa rebuild             Rebuild SQLite index from JSONL
joa export              Export entries as JSONL to stdout
joa import <file>       Import entries from JSONL (or - for stdin)
joa setup               Configure MCP for agent platforms
joa config get|set      View or update configuration

Run joa <command> --help for detailed usage.

How It Works

joa writes entries to JSONL files (one per day, append-only) as the source of truth, then indexes them in SQLite with FTS5 for fast full-text search and filtered queries.

~/.joa/
  journals/
    2026-02-27.jsonl    # Append-only daily logs
    2026-02-26.jsonl
  journal.db            # SQLite FTS5 index (derived, rebuildable)
  config.yaml           # Optional configuration

If the SQLite index is ever lost or corrupted, joa rebuild reconstructs it from the JSONL files.

Runs on both Node.js (published CLI) and Bun (development).

Contributing

See CONTRIBUTING.md.

License

MIT