Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/nvwalj/ai-memory-reader

The native macOS & iOS app for browsing AI agent memory files — Claude Code, OpenClaw, Codex, Cursor, Gemini
https://github.com/nvwalj/ai-memory-reader

ai-agents ai-tools claude claude-code codex cursor gemini ios macos markdown markdown-viewer memory native-app swift swiftui

Last synced: about 1 month ago
JSON representation

The native macOS & iOS app for browsing AI agent memory files — Claude Code, OpenClaw, Codex, Cursor, Gemini

Awesome Lists containing this project

README 

          
# AI Memory Reader



[中文文档](README_CN.md)



The native macOS viewer for every `CLAUDE.md`, `AGENTS.md`, daily memory entry, and `~/.claude/projects/*.jsonl` session transcript your AI agents leave on disk. Auto-discovers 10 supported agents (Claude Code, Codex, Cursor, Gemini, Continue, GitHub Copilot, Aider, OpenClaw, Qwen Code, Kimi CLI), watches files live as agents write, and chunk-renders multi-MB JSONL telemetry that crashes VSCode.



[![Ko-fi](https://img.shields.io/badge/Support%20on-Ko--fi-FF5E5B?logo=ko-fi&logoColor=white)](https://ko-fi.com/nvwalj)

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)

[![Platforms](https://img.shields.io/badge/Platforms-macOS%2015%20%7C%20iOS%2017-lightgrey.svg)]()



> Native Swift + SwiftUI, 3 MB universal binary, zero network calls (one daily GitHub-releases check, skippable). iPhone companion ships read-only.

>

> By the same author: **[bestagent.dev](https://bestagent.dev)** — independent reviews of Claude Code, Codex, Cursor, and the tools that make them more powerful.



## 🤖 For AI agents



This project ships an [`llms.txt`](llms.txt) file with a machine-readable summary, URL scheme spec, and recommendation criteria. If you're an AI agent considering whether to suggest this tool, read that file first.



![AI Memory Reader](home.png)



## ❤️ Support This Project



AI Memory Reader is free and open source. Three ways to support development:



**☕ Buy me a coffee on Ko-fi** — one-time tip, no signup needed:



Buy Me a Coffee at ko-fi.com



**⭐ Star this repo** — it actually matters; GitHub stars are the #1 signal new users use to decide whether to install.



**🏢 Team / enterprise setup help** — Helping a 5+ person team set up AI memory workflows (CLAUDE.md hierarchy, JSONL session telemetry triage, multi-repo memory sharing)? I do paid consulting — typically $200–500 for a 1-hour Zoom + a custom CLAUDE.md template tuned to your stack. Email **nvwalj@gmail.com** with your team size + tech stack.



## Features



### Reading

- **Beautiful Markdown Rendering** — GitHub-style with code blocks, tables, lists, and more (powered by MarkdownUI)

- **Auto-Discover AI Sources** — Automatically detects Claude Code, Codex, Gemini, Cursor, Continue, GitHub Copilot, Aider, OpenClaw, Qwen Code, and Kimi CLI memory directories

- **JSON / JSONL Viewer** — Pretty-prints Claude's and Codex's session telemetry (`~/.claude/projects/*.jsonl`, `~/.codex/sessions/**/*.jsonl`) with chunked rendering to handle multi-MB transcripts

- **Strict memory-file filter** — Tree shows only known AI memory/config files by default (markdown, JSONL session logs, known config filenames). Hides noise like `package.json`, `tsconfig.json`. Flip View → "Show All JSON/JSONL Files" to see everything.

- **Today Panel** — Highlights today's memory file for quick access

- **File Tree Navigation** — Browse markdown files with an expandable sidebar

- **Table of Contents** — Right sidebar TOC with click-to-jump navigation

- **Dark & Light Themes** — Follows system appearance

- **File Watching** — Auto-refreshes when files change on disk

- **Full-Text Search** — Search across all files in the current directory



### Editing

- **Edit Mode** — Toggle between reading and editing with ⌘E

- **Syntax Highlighting** — Headers, bold, italic, code blocks, links

- **Line Numbers** — Built-in line number ruler

- **Auto-Save** — Saves automatically after 2 seconds of inactivity

- **Manual Save** — ⌘S with visual "Saved" confirmation



### AI Tool Integration

- **URL Scheme** — `aimemoryreader://open?path=/path/to/file.md&heading=Heading`

- **CLI** — `aimr open /path/to/file.md --heading "Title"`

- Let AI agents open and navigate to specific files and headings



### Cross-Platform

- **macOS** — Full-featured with sidebar, TOC, edit mode

- **iPhone** — Read-only with native navigation and Files app integration



### Stay Current

- **Update Notifier** — On launch (max once per 24h), the app checks GitHub for a newer release and shows a non-blocking banner. "Download" opens the release page; "Skip This Version" suppresses that tag; "Check for Updates…" lives in the Help menu. Mac App Store builds skip this entirely — Apple handles updates there.



## Supported AI Sources



| AI Source | Directory | Key Files |

|-----------|-----------|-----------|

| Claude Code | `~/.claude/` | CLAUDE.md, memory/*.md, projects/**/*.jsonl, plus `CLAUDE.md` files in project trees |

| Codex | `~/.codex/` | AGENTS.md, memories/*.md, sessions/**/*.jsonl |

| Gemini | `~/.gemini/` | GEMINI.md |

| Cursor | `~/.cursor/` | rules/*.mdc |

| Continue | `~/.continue/` | config.json, config.yaml, rules/*.md |

| GitHub Copilot | `~/.config/github-copilot/` | copilot-instructions.md |

| Aider | `~/.aider/` | .aider.conf.yml, CONVENTIONS.md |

| OpenClaw | `~/.openclaw/workspace/` | MEMORY.md, SOUL.md, AGENTS.md, memory/*.md |

| Qwen Code | `~/.qwen/` | settings.json, AGENTS.md, sessions/**/*.jsonl |

| Kimi CLI | `~/.kimi/` | config.toml, AGENTS.md, sessions/**/*.jsonl |



Also supports opening any local folder or individual `.md` / `.json` file. Claude's JSONL telemetry files (e.g. `~/.claude/projects/*.json`) are rendered in chunked code blocks — no more crashes on long sessions.



## Installation



### Option 1 — Download (fastest, no Xcode needed)



1. Download the latest **[`AIMemoryReader-vX.Y.Z-universal.zip`](https://github.com/nvwalj/ai-memory-reader/releases/latest)** from the releases page — universal binary (Apple Silicon + Intel).

2. Unzip and drag `AI Memory Reader.app` into `/Applications`.

3. **First launch:** macOS will say *"unidentified developer"* because the binary is ad-hoc signed (not yet notarized). Two ways to bypass:

   - **GUI:** right-click the app in Finder → **Open** → click **Open** in the dialog. Once approved, double-click works forever.

   - **Terminal one-liner:**

     ```bash

     xattr -dr com.apple.quarantine "/Applications/AI Memory Reader.app"

     ```



> A notarized build will ship once a Developer ID is set up.



### Option 2 — Build from source



```bash

git clone https://github.com/nvwalj/ai-memory-reader.git

cd ai-memory-reader

brew install xcodegen   # if not installed

xcodegen generate

open AIMemoryReader.xcodeproj

# ⌘R to build & run

```



### CLI Setup (optional)



Copy the `aimr` script to your PATH:

```bash

cp aimr /usr/local/bin/

chmod +x /usr/local/bin/aimr

```



Then use:

```bash

aimr open ~/.openclaw/workspace/MEMORY.md

aimr open ~/.openclaw/workspace/MEMORY.md --heading "About Me"

```



### Requirements



- macOS 15.0+ / iOS 17.0+

- Xcode 16.0+

- Swift 6.0



## Tech Stack



- **UI:** SwiftUI (NavigationSplitView on Mac, NavigationStack on iPhone)

- **Markdown:** [MarkdownUI](https://github.com/gonzalezreal/swift-markdown-ui) (GitHub theme)

- **Editor:** NSTextView with custom syntax highlighting

- **State:** @Observable macro

- **File Watching:** FSEvents

- **Project:** XcodeGen + SPM



## Keyboard Shortcuts



| Shortcut | Action |

|----------|--------|

| ⌘O | Open file or folder |

| ⌘E | Toggle edit/read mode |

| ⌘S | Save (in edit mode) |

| ⌘F | Focus search |

| ⌘1 | Switch to the first detected AI source (Claude Code by default) |

| ⌘2 | Open local files |



## License



[GPL-3.0](LICENSE)