Skip to main content
Glama
neethanwu

joa

by neethanwu
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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.

Related MCP server: Agent State MCP Server

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.

Gemini CLI (~/.gemini/settings.json):

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

Codex (~/.codex/config.toml):

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

Amp (~/.config/amp/settings.json):

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

OpenCode (~/.config/opencode/opencode.json):

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

GitHub Copilot (VS Code mcp.json or .vscode/mcp.json):

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

Pi (~/.pi/mcp.json):

{
  "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

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/neethanwu/joa'

If you have feedback or need assistance with the MCP directory API, please join our Discord server