Flarex

Local ticket memory for agentic coding CLIs.

Flarex is a local-first ticket memory system for Claude Code and Codex. It stores ticket context inside the current repository, exposes that context through an MCP server, and ships a shared skill bundle so agents can resume work by ticket with compact memory instead of replaying entire conversations.

Why Flarex exists

Agentic coding work is often ticket-shaped, but session memory is usually client-specific and temporary. Flarex makes ticket memory repo-local and portable, so a developer can:

• initialize memory once in a repo
• open CON2-202
• persist important progress locally
• resume the same ticket later from Claude Code or Codex

Features

• local-first storage under .knowledge/
• append-only NDJSON ticket transcripts
• deterministic JSON summaries
• local STDIO MCP server
• shared SKILL.md workflow for Claude Code and Codex
• repo-scoped install flow with generated MCP config snippets
• safe defaults with no network access for core behavior

Install

Requirements

• Node.js 20+
• npm

Path conventions used below

Replace these placeholders with your own paths:

export FLAREX_REPO=/absolute/path/to/flarex
export TARGET_REPO=/absolute/path/to/your/project

Build Flarex locally

cd "$FLAREX_REPO"
npm install
npm run build

Initialize Flarex in your repo

cd "$TARGET_REPO"
node "$FLAREX_REPO/dist/cli.js" init
node "$FLAREX_REPO/dist/cli.js" install --local

Quick client setup

If you want one command that initializes the repo, installs the local skills, and configures MCP for any available clients on your machine, run:

bash "$FLAREX_REPO/scripts/setup-clients.sh" "$TARGET_REPO"

What it does:

• runs flarex init in the target repo
• runs flarex install --local
• if claude is available, adds the flarex MCP server to Claude Code
• if claude is available, installs Claude hooks for automatic Markdown memory capture
• if codex is available, adds the flarex MCP server to Codex
• prints the next commands to run in Claude Code and Codex

Use in Claude Code

After running bash "$FLAREX_REPO/scripts/setup-clients.sh" "$TARGET_REPO", open Claude Code in the repo and run:

/fx CON2-202
Continue the task.

If CON2-202 does not exist yet, the agent should create it through Flarex MCP, then load memory first and continue the work.

Example repo-local layout:

.claude/
  skills/
    fx/
      SKILL.md

Use in Codex

After running bash "$FLAREX_REPO/scripts/setup-clients.sh" "$TARGET_REPO", open Codex in the repo and run:

$fx CON2-202
Continue the task.

Or open /skills and select fx.

Example repo-local layout:

.agents/
  skills/
    fx/
      SKILL.md

Usage

flarex init
flarex install --local
flarex status
flarex list
flarex context CON2-202
flarex open CON2-202
flarex doctor

Operate Flarex day to day

The normal ticket workflow in a repo is:

1. Initialize Flarex once:

node "$FLAREX_REPO/dist/cli.js" init

2. Install the local skills once:

node "$FLAREX_REPO/dist/cli.js" install --local

3. Start your client in that same repo.

4. In Claude Code run:

/fx CON2-202
Continue the task.

5. In Codex run:

$fx CON2-202
Continue the task.

6. Keep working normally. Flarex will use:

• .knowledge/tickets/CON2-202.memory.md as the rich handoff memory
• .knowledge/tickets/CON2-202.summary.json as compact structured memory
• .knowledge/tickets/CON2-202.ndjson as the append-only transcript

7. Check stored context any time with:

node "$FLAREX_REPO/dist/cli.js" status
node "$FLAREX_REPO/dist/cli.js" context CON2-202

If you want to create or switch tickets from the CLI instead of the agent, you can still run:

node "$FLAREX_REPO/dist/cli.js" open CON2-202

Claude Code skill invocation

• /fx

Codex skill invocation

• $fx
• /skills

.knowledge/ structure

.knowledge/
  active-ticket.json
  config.json
  tickets/
    CON2-202.ndjson
    CON2-202.summary.json
    CON2-202.memory.md

• active-ticket.json tracks the currently active ticket in this repo.
• *.ndjson stores append-only transcript entries.
• *.summary.json stores compact deterministic summaries for token-efficient resumption.
• *.memory.md stores richer Markdown memory for plan requests, assistant updates, and completed code-change summaries.

MCP server

Claude Code and Codex start the Flarex MCP server through their MCP configuration. Flarex exposes these MCP tools:

• knowledge_init
• knowledge_open_ticket
• knowledge_set_active_ticket
• knowledge_get_context
• knowledge_append_turn
• knowledge_update_summary
• knowledge_list_tickets
• knowledge_read_ticket
• knowledge_read_memory

Flarex also exposes these resources:

• knowledge://active-ticket
• knowledge://tickets
• knowledge://ticket/{ticketId}
• knowledge://ticket/{ticketId}/summary
• knowledge://ticket/{ticketId}/memory

And these prompts:

• resume-ticket
• start-ticket-session

Security and privacy

• Flarex stores data locally in the current repository.
• Flarex does not upload ticket data or use the network for core workflows.
• .knowledge/ is added to .gitignore by default.
• likely secrets are redacted before transcript append by default
• logs and summaries remain human-inspectable files

Project structure

flarex/
  README.md
  LICENSE
  package.json
  tsconfig.json
  src/
    cli.ts
    mcp/
      prompts.ts
      resources.ts
      server.ts
      tools.ts
    core/
      config.ts
      paths.ts
      store.ts
      summary.ts
      ticket.ts
      validate.ts
    install/
      claude.ts
      codex.ts
      install.ts
    util/
      fs.ts
      log.ts
      time.ts
  skills/
    fx/
      SKILL.md
  examples/
    claude-mcp-config.json
    codex-mcp-config.toml
  test/
    core/
    install/
    mcp/

Sample Claude setup instructions

1. Run bash "$FLAREX_REPO/scripts/setup-clients.sh" "$TARGET_REPO".
2. Ensure .claude/skills/fx/SKILL.md exists.
3. Start Claude Code in the repo.
4. Run:

/fx CON2-202
Continue the task.

Sample Codex setup instructions

1. Run bash "$FLAREX_REPO/scripts/setup-clients.sh" "$TARGET_REPO".
2. Ensure .agents/skills/fx/SKILL.md exists.
3. Start Codex in the repo.
4. Run:

$fx CON2-202
Continue the task.

Roadmap

• Jira sync
• GitHub issue mapping
• better summarization
• multi-repo indexing

Known limitations

• v1 uses per-process write serialization and atomic JSON writes, not cross-process file locking
• summary updates are deterministic only; there is no model-assisted summarization yet
• installer writes repo-local skills and config snippets, but does not fully manage every client config surface automatically
• full transcript replay is available, but compact context is the default and preferred path
• automatic Markdown memory capture is optional and currently targets Claude Code hooks; Codex does not yet have an equivalent Flarex hook flow

Release checklist

• npm install
• npm run build
• npm test
• verify flarex init in a fresh repo
• verify flarex open CON2-202
• verify MCP connection works in Claude Code and Codex
• verify .claude/skills/fx install
• verify .agents/skills/fx install
• verify example MCP configs
• review README for public open-source clarity