Break the question down with Last Order, the coordinator, and refine the research plan; send
each branch of the inquiry to Sisters, specialists who report, liaise and consult; gather
their reports, read them and write; defend the conclusion before the reviewers; and turn whatever
it cannot cover into new research. Graph algorithms manage the graph of research branches, and
the final report arrives in your project folder as a research article, every citation traceable.
Core design
Quick start
uv tool install "misaka[providers] @ git+https://github.com/Luciole-Studio/Misaka-Agent.git"
mkdir ~/Documents/my-research
cd ~/Documents/my-research
misaka setup # sign in, choose a model, create your first two Sisters
misaka # start MISAKA and type /research
MISAKA runs on macOS, Linux and Windows (x86_64 or arm64); macOS is recommended. It requires
uv, git, ripgrep,
fd and poppler, and access to a model provider: an API key, or a
ChatGPT or GitHub Copilot subscription. Claude accounts can also sign in, with that usage billed
by Anthropic per token as extra usage. Install from this repository: the misaka package on PyPI
is an unrelated project.
Each GitHub release also has a prebuilt archive for those architectures. The archive includes
uv, git, ripgrep (rg), fd and poppler (pdftotext); running misaka puts them on PATH for
that process. ocrmypdf, DjVuLibre and LibreOffice stay optional and are not in the archive.
curl -fsSL https://raw.githubusercontent.com/Luciole-Studio/Misaka-Agent/main/scripts/install.sh | sh
Windows (PowerShell):
irm https://raw.githubusercontent.com/Luciole-Studio/Misaka-Agent/main/scripts/install.ps1 | iex
brew install luciole-studio/tap/misaka and winget install Luciole-Studio.Misaka use the same
archives once the tap and the winget package are published. release/README.md
describes the archive layout and those publish steps.
Run MISAKA in a working folder under Documents (such as ~/Documents/my-research above),
never in the root directory.
Getting started covers installation step by step and walks you through
a first research question.
Research: /research
The plan's ready! Misaka Misaka starts the moment you say so, says Misaka Misaka, holding it out with both hands.
/research is the core of MISAKA. A run takes one question and explores the different ways it
could be answered. Your question is the first node: Last Order agrees the plan with you, the
Sisters research it, and Last Order writes the conclusion; a red team then reviews that conclusion
and brings out the possibilities it set aside. Errors and gaps are corrected within the node,
while genuine alternatives resting on different premises open as new nodes, each with its own
Last Order, Sisters and red team. The run thus unfolds level by level into a research graph and
concludes in a research article.
Starting a run
In Last Order's window, type /research. A picker confirms nine parameters in turn, then takes
your research question.
| Parameter | Meaning |
|---|
| Research depth | how many levels of alternatives may open beneath the question |
| Node parallelism | how many nodes run at the same time |
| Card parallelism | how many cards each node runs at the same time |
| Follow-up rounds | how many further rounds of cards may follow the first |
| Revisions | how many times a conclusion may be revised in each review loop (the red team's, then the divergence review's) |
| Node limit | how many nodes the run may hold, the root included |
| Plan approval | whether plans wait for your consent |
| Compaction threshold | the share of the context at which conversation is compressed, for this run only |
| Output limit | the longest reply a model may write, for this run only |
Parameters and question may also be given on one line, as in
/research --depth 2 --max-nodes 12 QUESTION. Parameters left unspecified take their defaults:
depth 3, four nodes and four cards at a time, two follow-up rounds, two revisions and a limit of
30 nodes. From the shell, misaka research accepts the same parameters. A running run's
parameters are changed with /research limits --sister-parallel 2 (and the other options).
Inside a node
Every node, your question included, passes through the same seven stages:
- Plan. The plan is a research design. It establishes what the question actually asks and
what else it could mean, identifies untested premises, sets out the evidence, methods and
sources required together with their limits, and justifies each Sister's assignment. Each
task receives its own card; a coverage table maps every sub-question, actor and dimension to
the cards serving it, so that a gap appears as an empty cell; and the red team is appointed
here. Where the question admits mutually exclusive ways of answering it, the plan may record a
decision with at least two options and their premises.
- Cards. The Sisters, and allies such as Claude Code, work their cards in parallel in
separate sessions, declaring each finding: the claim, its type (fact, inference,
interpretation or value judgement), the file and page it rests on, and the quotation. Once the
cards return, Last Order may send out further rounds within the follow-up limit.
- Conclusion. Last Order studies the deliverables in full and writes the conclusion: shared
and competing findings, key evidence and counterevidence, and the limits of the methods; the
premises the conclusion rests on and what each gains and gives up, what the materials could
not reach and whose voices are absent; and how it answers the node it came from and its rival
options. A conclusion may be a position that accepts stated costs, or the dissolution of the
question. Factual errors found in an earlier node are recorded as errata, shown beside the
original conclusion in every node below it and in the final report.
- Red-team review. The red-team Sister studies the conclusion, the plans, the evidence, the
graph and Last Order's reasoning. She checks the facts, raises gaps, tests whether the
conclusion answers its parent and its rivals, and identifies what the conclusion leaves unsaid
yet relies on.
- Response to review. Last Order gives each material objection exactly one response: revise,
rebut, concede a cost, refer it to the node that owns it, park it, or take it to a decision.
Before answering an objection about a card's material she can ask the Sister who wrote it and
hear her out. Where something is revised, the conclusion is issued in a new version and
returned to the same red team, until nothing material remains or the revisions are exhausted.
- Divergence review. Once the red team's loop is over, the same Sister conducts a divergence
review in a fresh session. She separates possibilities not taken, which rest on different
premises, from gaps that any answer must fill, and brings out the presuppositions behind each
of the conclusion's choices and what each gains and gives up. Last Order fills or answers every
gap within the node; each version that fills one is reviewed again, until no gap is left or
the revisions are exhausted.
- Decision. Each possibility not taken is recorded as an option to open, as already covered,
or as declined with a reason. A presupposition on which the answer depends may itself become a
fork: the node opened for it examines whether it holds, and how the answer changes if it does
not.
How the graph grows
The run proceeds level by level: every node at one depth finishes before the next depth begins.
Between levels, Last Order surveys the whole graph and reconciles it:
- Waiting options open as new nodes; options that ask the same question are merged into one
node, researched once.
- Lines that reach the same place by different routes may be joined and carried forward by a new
node. At the join they confront each other: what can be integrated is integrated, and where
they cannot be reconciled the disagreement is drawn sharply.
- Relations between nodes (convergence, divergence, resonance, appropriation and displacement)
are recorded for the final report.
A paths list records every possibility raised in the run and what became of it, so that each is
opened only once. A new node forks from the session of the node it came from and inherits the
history of its question.
Taking part and following a run
- Plan approval. Every plan, the reconciliations between levels included, can wait for your
consent, given in ordinary conversation. Plans may instead proceed automatically, but a plan
that changes the question itself always waits for you. You may also skip a node, cancel a
follow-up round or stop the run.
- Conversation at any point. Each node has its own tab in the panel, where you can speak with
that node's Last Order at any time.
- Commands and recovery.
/research status shows progress, /research stop ends the run with
a partial report, and /research resume resumes a stopped or failed run. A failed card is
retried up to three times; when a node fails, the rest of its level continues.
The final report
When every node has closed, Last Order writes a survey of each node, a draft report, an
independent red-team review of the draft and the final version. The report is a research article
for readers in the humanities and social sciences, written in the language of the question, with
a title, abstract and keywords, an introduction, argued chapters and a conclusion. Notes and a
bibliography carry its traceability; the appendices record every line of inquiry, the costs the
answer accepts together with errata and paths not taken, the materials used, and the handling of
the review. The theses, arguments and connections between lines are drawn from the research
materials: what can be integrated is integrated, and positions whose premises cannot be
reconciled are kept distinct.
The research guide covers every stage in full.
Context and materials for humanities research
The materials of humanities and social science research are often voluminous and multilingual,
and their provenance must be verifiable; together these exceed what a single model's context
window can hold. MISAKA addresses the following problems by design.
| Problem | Approach |
|---|
| Long works exceed the capacity of the context window | PageIndex builds a hierarchical chapter index of long documents, which are then read on demand by section or page range |
| Context compression over a long inquiry distorts earlier material | LCM summarises earlier conversation hierarchically, each summary traceable to the original text; all sessions in a project share one retrieval index |
| Skill and tool instructions consume the coordinator's context | Skills and tools are assigned to Sisters by specialty, and cards run in separate sessions; Last Order's context is reserved for the materials submitted to her |
| Citations are hard to verify, and sources may be fabricated | Quotations are located to the page and character offset; conclusions cite only sources actually read, and source lists and original files are archived with them |
| Scanned documents, DjVu and multilingual materials | OCR in Chinese, English and Japanese, DjVu and legacy Office formats; plain text is structured by headings such as CHAPTER or LIVRE |
| Model output gravitates toward prevailing views | Disciplinary coverage maps and literature scans mark research gaps, and the divergence review proposes directions not taken |
PageIndex: hierarchical indexing and reading on demand
- Each project keeps its own document index. Documents of 20 pages or more receive a
hierarchical table of contents giving the page range of each section.
- An agent first consults the outline (
doc_outline) and then reads by section node or page
range (doc_read), so that only the required text enters the context.
- For PDF and DjVu a page is a page of the file, counted from 1, which is not always the number
printed on it (the printed number is shown beside it where the PDF labels its pages or the
page heads print it); other formats are divided at paragraph boundaries into pages of about 3,000
characters, to which page citations refer.
doc_find performs literal search; doc_verify returns the page, character offset and
checksum of a quotation.- Scanned pages are found one by one and read by OCR, so a book that mixes typeset and scanned
pages loses neither.
doc_read names the figures its text does not carry: images and drawings on a PDF page, a
scanned page that is likely a map or a plate, a slide whose meaning is in a picture, a picture
a Word document or an EPUB embeds. doc_page_image shows the page, the slide or the one
figure. For a model without vision, every image is read to it in words by one vision model
(vision.model).- Texts produced during the research are indexed on completion. The final report retrieves each
node's conclusion as a document, without loading everything into the context at once.
LCM: traceable hierarchical compression
- When a session reaches a set share of the context window (35% by default), earlier
conversation is compressed into summaries, which are in turn merged level by level.
- The original conversation is preserved in full. Every summary can be expanded to the text it
rests on, and the original can be searched directly, so compression entails no irreversible
loss of information.
- All sessions in a project share one retrieval index; any agent can search the conversations of
the others.
- Optional features: semantic retrieval with a local embedding model, proactive recall of
relevant history, external storage of very long tool outputs, and daily, weekly and monthly
roll-ups.
- Each research run may set its own compaction threshold and output limit without affecting the
global configuration.
See Documents and the web and the
configuration reference.
Outputs
Every source is filed where you can check it, Misaka reports.
All output is written to your project folder:
my-research/
├── final/<run>-final.md the final report, with the costs it accepts and the paths not taken
├── final/<run>-sources/ every file the report cites, linked in place
└── nodes/<node>/ one directory per piece of research
├── plan.md Last Order's plan and her reasons for choosing each Sister
├── cards/<card>/ each Sister's work and the red team's critique
├── synthesis.md the conclusion (synthesis-2.md and onward once revised)
└── SOURCES.md every file the conclusion cites, and the claims each one supports
MISAKA commits only at your request. If the project is a git repository, /commit lists the files
for your confirmation before committing.
Common commands
| Purpose | Command |
|---|
| Start MISAKA | misaka |
| Begin a research run | /research, followed by your question |
| Check, halt or resume a run | /research status, /research stop, /research resume |
| Say something to a running node | /research tell [--to NODE_ID] MESSAGE |
| Change a running run's limits | /research limits --sister-parallel 2 |
| See what a run spent | misaka usage --run RUN_ID |
| Talk to a single Sister | /sister 10032 |
| Create a Sister | misaka create 10036 --desc "Econometrics and causal inference" |
| Index your documents | misaka doc scan sources/ |
| Choose a model, sign in | /model, /login |
| List every command | / in chat, misaka --help in the terminal |
| Show the panel's key bindings | ctrl+b, then ? (see the panel guide) |
| Update | misaka update --apply |
The command reference lists every command.
Documentation
docs/README.md indexes every page and defines the terms MISAKA uses.
Data and cost
All data MISAKA keeps stays on your machine: settings, credentials and history in ~/.misaka/,
research output in your project folder. Prompts are sent only to the model providers you
configure. Web searches go to the search services you configure, or, when none is configured or
one fails, to the free public tiers of Exa, Parallel, Firecrawl and Keenable
(misaka web set keyless_fallback false disables this). Literature scans send a question's search
terms to OpenAlex. MISAKA sends no telemetry.
A research run operates at scale: by default up to four branches run at once, each with up to four
Sisters working in parallel as memory allows, so a deep run makes many model calls. A smaller
depth reduces cost, and research.token_cap in ~/.misaka/settings.json sets a hard token
budget for each run.
About the name
MISAKA takes its names from Kazuma Kamachi's A Certain Magical Index and A Certain
Scientific Railgun, in which the Sisters, clones of the Railgun Misaka Mikoto, share their
memories through the Misaka Network.
| In the story | In MISAKA |
|---|
| Misaka Mikoto, the original every Sister comes from | MISAKA.md, the shared identity every agent loads before her own |
| The Sisters, known by serial number: Misaka 10032, 10033, … | your specialists, each with a number, a specialty and her own SOUL.md |
| Last Order, Misaka 20001, who commands the network | the coordinator you talk to |
| The Misaka Network, through which what one Sister learns the others can recall | the project's conversations, searchable by every agent in it |
The "says Misaka" lines in this README are ornamental; each agent speaks as her SOUL.md
specifies, and a single line there gives her the Sisters' manner of speech.
MISAKA is an independent project. It is not affiliated with or endorsed by the author or the
publishers of the series.
Foundations
MISAKA's agent kernel is a Python port of pi, and its
panel is a port of herdr, with
ghostty's terminal library behind every pane. It builds
on hermes-lcm for long conversations and
PageIndex for document structure, and ports web tools
and skills from Hermes Agent and Office support
from FrontierAgent.
THIRD_PARTY_NOTICES.md records the origin of each part.
MISAKA builds on pi for its simple kernel and its mature, actively maintained community, which lets
MISAKA follow upstream directly. MISAKA's graph governs the content and possibilities of research:
a node is a completed piece of research, and an edge is a line of inquiry that forked off carrying
its reasoning.
Licence
MISAKA is released under the Apache License 2.0. Third-party components keep their own
licences, recorded in THIRD_PARTY_NOTICES.md.
If you redistribute MISAKA or build on it, keep the attribution in NOTICE: Apache-2.0
requires it to accompany your distribution.
