reflectl

Your AI-native personal operating system.

Capture what you learn. Reflect on what you think. Research what you don't know. Read deeply. Make decisions. Track goals across life chapters. Crystallize knowledge you trust. All orchestrated by a team of 11 AI agents over a local-first Zettelkasten — your data on your machine, scored by a deterministic trust engine, improving itself every session.

Runs first-class on Claude Code and includes a Codex compatibility layer through AGENTS.md plus runtime adapter contracts. Claude Code currently has the richest native slash-command and subagent surface; Codex uses the same workflow specs through adapters. $ZK/ is the local data layer. Reflect.app and Readwise are optional capture surfaces; the authoritative knowledge lives on disk.

What It Does

Reflect — Daily check-ins grounded in what you actually wrote. Surfaces forgotten connections, challenges assumptions, tracks your goals across life chapters.

Read — Deep-reads articles, saved notes, and transcripts through multiple lenses (critical, structural, practical, dialectical). Multiple readers analyze in parallel, then you discuss what they found.

Plan — Goal reviews, decision journals, and energy audits. Tracks what's progressing, what's neglected, and what's emerging. Uses 22 thinking frameworks with cross-validation.

Act — Compact redundant notes, deep-dive into a topic with 4 agents working in parallel, triage your notes for cleanup, or curate your Readwise inbox.

Learn — Get reading recommendations or introspect to rebuild your self-model.

Wiki — Crystallize validated thinking into $ZK/wiki/ entries with structured claims, external anchors, and bi-temporal markers. A TrustRank pass (scripts/trust.py) scores each claim via Personalized PageRank with external anchors as trust seeds. /lint enforces corpus-level structure and harness health. Wiki entries stay local by default; the user can manually share a specific entry to Reflect for mobile reading (orchestrator dispatches Curator for create_note).

Session reflections are written to $ZK/reflections/ as the durable session output. Daily notes are the user's capture stream; the system only writes during an orchestrator-authorized /sync that merges Reflect's copy into the local file without discarding any local content. Compiled knowledge lives locally in $ZK/wiki/; the user can manually share a specific entry to Reflect for mobile reading.

Getting Started

Prerequisites

• One AI runtime CLI:
  • Claude Code for native slash commands and agent teams
  • Codex CLI for the portable AGENTS.md harness and external review
• uv — Python package manager

Optional — enhances the system but not required:

• Reflect.app with the MCP server — enables mobile capture via daily notes and a /sync pull-and-merge of those daily notes into $ZK/daily-notes/. The system is local-first; everything works without Reflect, you just lose mobile capture and the manual wiki-share surface.
• Gemini CLI — npm i -g @google/gemini-cli — second external reviewer perspective

Core scripts (trust.py, lint.py, staleness.py, session_log.py) are stdlib-only. Semantic search and document conversion deps are managed via pyproject.toml.

Install

git clone https://github.com/mhxie/reflectl.git ~/reflectl
cd ~/reflectl
uv sync                # install dependencies from pyproject.toml

Set $ZK to point to your Zettelkasten vault (the directory containing daily-notes/, wiki/, reflections/, etc.):

echo 'export ZK="$HOME/path/to/zk"' >> ~/.zshrc
source ~/.zshrc

If using Reflect, create .mcp.json in the project root for Claude Code:

{
  "mcpServers": {
    "reflect": {
      "type": "http",
      "url": "http://127.0.0.1:7676/mcp"
    }
  }
}

For Codex, register the same MCP server via the Codex CLI:

codex mcp add reflect --url http://127.0.0.1:7676/mcp
codex mcp list                                            # verify

Codex prompts for approval on every MCP tool call (no documented auto-approve in codex-cli 0.125.0); see AGENTS.md → MCP Setup for the full notes.

First Run

Claude Code:

claude                # open Claude Code in the project
/introspect           # build your self-model from your notes (reads $ZK/daily-notes/)
/reflect              # start your first session

Codex:

python3 scripts/reflectl.py run reflect            # fresh Codex TUI on /reflect (default)
python3 scripts/reflectl.py run lint --exec        # one-shot, no TUI
python3 scripts/reflectl.py run reflect "context here"
python3 scripts/reflectl.py run promote --resume   # continue most recent session (only on resume_friendly commands)
python3 scripts/reflectl.py run promote --fork     # branch from most recent without mutating it

The run subcommand spawns codex with the generated prompt pre-loaded and the repo as the working directory; this is the Codex parity for Claude Code's slash commands. Codex reads AGENTS.md, picks up the repo-scoped reflectl skill under .agents/skills/, then adapts .claude/commands/*.md through protocols/runtime-adapters.md. Use run --print to inspect the prompt without launching Codex, or prompt/source for paste-and-discover flows.

Reflection-type commands (/reflect, /weekly, /review, /decision, etc.) default to fresh sessions because reusing a prior session pollutes the new reflection. Continuation-friendly commands (/promote, /restore) are marked resume_friendly = true in harness/commands.toml; pass --resume to chain them off a recent session, or --fork to branch without mutating the original. When --resume/--fork is used on a non-resume_friendly command, a warning is printed to stderr and the command still proceeds — the flag is advisory, not a hard stop, since the caller knows their context best.

Sessions

Type /reflect to get a menu of everything you can do:

Mode	What happens
Daily Reflection	Reflects on today's notes, asks questions at increasing depth, surfaces a forgotten connection
Weekly Review	Energy + attention audit across the week
Explore	Finds hidden connections and open threads across your notes
Goal Review	Checks progress on goals — progressing, neglected, or shifted
Decision Journal	Structured decision-making with framework cross-validation
Energy Audit	Four-dimension assessment (physical, mental, emotional, social)
Read & Discuss	Multi-lens reading of an article or note, then interactive discussion
Deep Dive	Full briefing on a topic — your notes + web research + resources + framework
Compact Notes	Find and merge redundant notes
Curate Inbox	Goal-aware triage of your Readwise inbox — score, route, and tag
Note Triage	Scan for compaction candidates across your notes
Process Meeting	Turn a work meeting transcript into structured notes with action items

You can also go direct: /review, /weekly, /decision, /explore, /energy-audit, /curate, /introspect, /sync, /lint, /promote, /paper-review.

Knowledge layer commands:

Command	What it does
/promote	Create an L4 wiki entry from L2 source notes: Researcher finds claims + anchors, Curator drafts schema-compliant entry.
/sync	Pull daily notes from Reflect into $ZK/daily-notes/ and line-union merge with any local edits. One-way, Reflect → local only. Sharing a wiki entry to Reflect is a separate manual per-note operation.
/lint	Corpus-level structural check over $ZK/wiki/ (parse errors, duplicate titles, slug drift, orphan entries, graph topology). Also checks harness health: CLAUDE.md size and formatting.
/restore	Emergency wiki recovery from Reflect's append-only archive when the user supplies a note ID. Very rarely triggered.

The Team

Eleven agents work together during sessions. You don't need to manage them — the orchestrator dispatches automatically. But you can talk to any of them directly:

• "find notes about X" — sends Researcher to search your notes
• "read [[Article]] with critical lens" — sends Reader to analyze
• "challenge my assumption about X" — sends Challenger to probe
• "compact my notes on Y" — sends Curator to merge
• "recommend reading on Z" — sends Librarian to curate
• "what's happening in the world on X" — sends Scout to search the web

How It Works

Capture sources                 Local data layer ($ZK/)              Display
(Reflect, Readwise,             L4  $ZK/wiki/       ─manual share→  Reflect
 voice, mobile)                 (trust-scored)                    (mobile read)
                                L3  $ZK/papers/
(Reflect daily notes ─/sync──>  L2  $ZK/daily-notes/, reflections/,
 merged line-union)                 research/, preprints/,
                                    agent-findings/, drafts/, ...
                                L1  $ZK/cache/, $ZK/readwise/

                                        ^
                                        |
                                        v
                           AI runtime (Claude Code or Codex)
                                        |
                    +-----------+-------+-------+-----------+
                    v           v               v           v
              Agent Team    Sessions      Frameworks   Trust engine
              (11 agents)  (12 types)   (22 + xval)  (trust.py,
                    |           |               |       lint.py)
                    v           v               v
              Protocols    $ZK/reflections/   Cross-validation
              (21 rules)   (session outputs) & Pattern Library

Five-tier knowledge model. Everything under $ZK/ is classified by depth of crystallization — raw capture (L1), working notes (L2), externally-certified papers (L3), locally-certified wiki entries (L4). Directory = tier; no tags required. Agents read from disk via semantic search and grep, not via MCP. Reflect is demoted to a capture + display surface.

TrustRank over the wiki. Wiki entries under $ZK/wiki/ follow a structured schema: ## Claims with [C1], [C2]... headings, each backed by fenced anchors blocks containing @anchor (external evidence), @cite (internal edge to another wiki entry), and @pass (reviewer verification) markers with bi-temporal valid_at/invalid_at fields. scripts/trust.py runs Personalized PageRank with external anchors as seeds; trust mass enters the graph only at external sources and propagates through internal cites. No external anchor, no trust. scripts/lint.py enforces structural integrity across the corpus.

Session reflection. The orchestrator dispatches agents, gathers findings, runs a quality gate, and writes session output to $ZK/reflections/. Daily notes are the user's capture stream; the only system writes are the /sync merge (line-union with Reflect's copy, never discards local content) and the orchestrator's today-fetch when the local file is missing or empty. All personal data under $ZK/ is gitignored; only the system configuration (protocols, agents, commands, scripts) is committed.

Harness engineering. CLAUDE.md is kept minimal (~7KB target) because it is inherited by every Claude subagent; each line costs N tokens times N agents per session. AGENTS.md and .agents/skills/reflectl/SKILL.md give Codex the root contract and workflow trigger, while harness/models.toml, harness/capabilities.toml, harness/commands.toml, harness/agents.toml, and protocols/runtime-adapters.md keep provider and runtime assumptions explicit. scripts/reflectl.py gives Codex command and role discovery plus prompt generation. Critical rules live at the top (primacy effect), detailed specifications are loaded on demand from protocols and agent definitions. The Evolver agent has a "subtract before adding" principle and a root-instruction budget gate. /lint Phase 0 checks harness health alongside the wiki structural pass.

Key design choices:

• Local-first: the knowledge layer lives on disk, not in a remote app. MCP is used only as narrow escape hatches: /sync pulls daily notes from Reflect into local, and the user can manually share a specific wiki entry to Reflect via the Curator.
• Reflect as append-only archival: Reflect's MCP has create_note and append_to_daily_note but no update or delete. That's a drawback for editing, but a feature for recovery: any wiki entry the user has manually shared leaves a tamper-evident copy in Reflect's cloud. The rarely-triggered /restore command operationalizes this property.
• Deterministic trust scoring: TrustRank is a stdlib-only Python pass, not an LLM heuristic. The same input always produces the same score.
• Era-aware: tracks life chapters with themes and directions (Mastery, Impact, Freedom, Connection, Creation)
• Bilingual: handles English and Chinese notes, matches your language
• Self-improving: the Evolver agent evolves the system with harness engineering best practices, reviewed by external AI models (Codex, Gemini) via scripts/review.sh
• Privacy by default: personal data never leaves your machine

License

MIT