RAGNotebook: A GraphRAG Note Manager You Run Yourself

The problem RAGNotebook picks, and who feels it

The README frames the target problem in one line: notes that are written and never revisited, and knowledge that scatters into isolated islands. That is a real failure mode for personal knowledge bases. A folder of Markdown files has no retrieval layer, and a plain chat-over-documents tool has no memory of what you wrote last month. RAGNotebook tries to close both gaps at once by putting notes and uploaded documents into the same Neo4j graph and exposing a single conversational interface over them. The stated audience is individuals who want AI-assisted note management, plus job seekers who need a portfolio project that touches RAG, agents and graph databases. The repository also keeps a base-rag branch described as a pure RAG conversation service, positioned for developers who want to learn RAG or integrate it quickly without the graph layer. That split matters: the master branch is a product, the base-rag branch is a teaching artifact, and the README is explicit that the base branch is preserved permanently rather than deprecated.

How the retrieval actually works: Neo4j as both graph and vector store

The architecture puts Neo4j in an unusual double role. It stores the knowledge graph extracted by an LLM from notes and uploaded documents, and it also stores chunk vectors and full-text indexes. Semantic search runs a hybrid of vector and full-text retrieval with RRF fusion, so a query can match both by embedding similarity and by literal token overlap. On top of that, retrieval expands along graph edges to pull in evidence connected to the initial hits. The agent layer is built with LangChain's create_agent plus tool definitions, which means the model chooses which retrieval tools to call rather than following a fixed pipeline. Chat history and note records live in MySQL through SQLAlchemy's async ORM, Redis handles caching, and the API is FastAPI. The frontend is React 19 with TypeScript, Vite, Tailwind, Radix UI, Tiptap for Markdown editing and Zustand for state. Two design choices stand out. First, tags and categories are generated asynchronously by an LLM after a note is saved, so classification is a background job rather than a blocking step. Second, every retrieval is scoped to the authenticated user, which the README describes as user-level knowledge base isolation enforced through JWT.

Getting it running: docker compose, or uv plus npm

The fastest path is Docker. Clone the repository, then on Windows run start.bat from the root, which the README says generates backend/.env if missing, builds and starts five containers, waits for the backend and opens the browser. On Linux and macOS the manual sequence is cp backend/.env.example backend/.env, edit that file to set at least OPENAI_BASE_URL, OPENAI_API_KEY and OPENAI_MODEL_NAME, then docker compose up -d --build. The frontend lands on http://localhost:3000 with a default admin account of admin / admin1234 that the README states is created automatically at backend startup. API documentation is served at http://localhost:8000/docs. Database passwords can be overridden in the root .env through MYSQL_ROOT_PASSWORD and NEO4J_PASSWORD. Day-to-day commands are docker compose down to stop while keeping data, docker compose logs -f backend for logs, and docker compose restart backend after changing model keys in backend/.env. A full reset is docker compose down -v, which the README flags as destructive. For local development the backend uses uv sync and uvicorn main:app --reload on port 8000, the frontend uses npm install and npm run dev on port 3000, and MySQL, Redis and optionally Ollama run as separate services. The .env.example covers an OpenAI-compatible chat model, optional separate embedding credentials, an optional cloud reranker from SiliconFlow or a compatible provider, MySQL, Redis, Neo4j, JWT settings, and a disabled-by-default web search block using Tavily.

Where the design costs you: five services and a hard dependency on model keys

The deployment surface is the first constraint. A working instance needs MySQL, Redis, Neo4j, the FastAPI backend and the React frontend, and the README recommends at least 4GB of memory with roughly ten minutes for the first build because backend dependencies are large. That is a lot of operational weight for a personal note tool, and it is the main reason someone might stop reading here. The second constraint is that AI features are inert without credentials. The README states plainly that the service starts and can be browsed without an LLM key, but question answering and the other AI functions do not work. There is no bundled local model path in the quick start beyond pointing OPENAI_BASE_URL at an Ollama /v1 endpoint yourself. Third, reranking is a cloud call by default, and the README notes it degrades to the original order on failure, which means retrieval quality silently changes when the reranker is unreachable. Fourth, the graph extraction step depends on an LLM to identify entities and relations, so graph quality tracks model quality, and the README does not document a correction or review workflow for bad extractions. Finally, the README is written primarily in Chinese, which raises the reading cost for teams without Chinese speakers even though the frontend ships an i18n toggle for English.

The base-rag branch is the honest comparison point

The most useful alternative is inside the same repository. The base-rag branch is described as a pure RAG conversation service with a document upload, vector retrieval and question answering flow, explicitly non-GraphRAG, and it is pitched at developers who want to integrate RAG quickly or study it. The difference in approach is concrete: base-rag is a pipeline, while master is an agent with tools that can decide to expand along graph edges, call web search when enabled, and mix note and document sources. If your goal is to understand chunking, embedding and retrieval without also learning Neo4j graph modeling and agent tool routing, base-rag removes an entire layer. Outside the repository, the natural comparison is a general-purpose RAG framework such as LlamaIndex or Haystack, which give you components to assemble into your own service rather than a finished application with a React frontend and a fixed note-centric data model. RAGNotebook is the wrong tool if you need to embed retrieval into an existing product, because adopting it means adopting its MySQL schema, its Neo4j graph conventions and its API shape. The base-rag branch is the better match for that use case, and it exists precisely because the maintainers recognized the two audiences.

Maintenance, versioning and the MIT licence

The repository is active rather than archived, with v2.3.2 released on 2026-09-09 and v2.3.0 and v2.3.1 landing within the preceding ten days. That cadence suggests the master branch is being maintained, and the README calls it the long-term supported version. The cost of upgrading is not documented in the material provided. There is no migration guide, no changelog beyond release tags, and no statement about Neo4j schema compatibility between versions, so anyone running this in production should read release notes before pulling a new tag and should treat the MySQL and Neo4j volumes as data that may need migration. The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is a permissive arrangement, but it says nothing about the model providers you connect to: your OpenAI-compatible endpoint, embedding service, reranker and Tavily key each carry their own terms and costs, and those are outside the repository's licence. This is not legal advice; check the terms of each provider you enable.

Who should run this, and what to check first

RAGNotebook fits a specific shape of user: someone who wants a self-hosted notes workspace where the retrieval layer understands relationships between notes, is comfortable running Docker Compose with five containers, and already has an OpenAI-compatible model endpoint. It also fits developers building a portfolio piece around GraphRAG, since the repository exposes the full stack from Tiptap editor to Neo4j graph traversal. It does not fit teams that want a retrieval library to call from their own service, and it does not fit anyone unwilling to operate MySQL, Redis and Neo4j. The first thing to verify is which branch you actually want: master for the note manager, base-rag for the plain RAG service. The second is the security default. The README states the admin account admin / admin1234 is created automatically at backend startup, and it does not describe a forced password change, so on any host reachable beyond localhost that account needs to be changed or the instance kept behind a private network. The third is the feature matrix in backend/.env.example: reranking, separate embedding credentials, vision and web search are all optional blocks, and leaving them unset changes what the system can do rather than breaking it. Decide which of those you need before you size the deployment.

Editorial conclusion

Adopt RAGNotebook if you want a self-hosted notes workspace where retrieval is graph-aware and you are willing to run five Docker containers and supply OpenAI-compatible keys. Do not adopt it if you only need a RAG library to call from your own code, or if you cannot operate MySQL, Redis and Neo4j. Before committing, verify the master branch against the base-rag branch, confirm the default admin account is changed after first login, and check the backend/.env.example keys for the reranker and web search features you plan to enable.

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. RMA-MUN/RAGNotebook on GitHub