docs: README.org and setup notes in docs/setup.org

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-19 12:22:46 +08:00
parent 17fbeffac1
commit 6b4d54bfac
2 changed files with 274 additions and 0 deletions
@@ -0,0 +1,123 @@
+#+title: RAGs — Private Learning Tool
+#+author: df
+#+date: 2026-04-19
+
+* Overview
+
+Two local RAG systems for a private learning tool with Anki export.
+
+| Project  | Purpose                                          |
+|----------+--------------------------------------------------|
+| LightRAG | Graph-based RAG — ingest docs, query concepts    |
+| Graphiti | Temporal knowledge graph — track what you learned and when |
+
+Both run fully local via Ollama. No cloud, no API keys.
+
+* Prerequisites
+
+** Ollama
+
+Install Ollama and pull the required models:
+
+#+begin_src sh
+ollama pull qwen2.5:7b
+ollama pull nomic-embed-text
+#+end_src
+
+Ollama must be running before starting either service.
+
+** Nix
+
+Flakes must be enabled. Add to your NixOS config or =~/.config/nix/nix.conf=:
+
+#+begin_src
+experimental-features = nix-command flakes
+#+end_src
+
+* Usage
+
+** LightRAG
+
+Ingest documents and query them as a knowledge graph.
+
+#+begin_src sh
+nix develop .#lightrag
+lightrag-server
+#+end_src
+
+Server runs at =http://localhost:9621=.
+
+Configure in =.env.lightrag=. Default storage is =./lightrag/rag_storage/=.
+
+** Graphiti
+
+Temporal memory graph — tracks concepts and when you learned them.
+
+Start Neo4j first (in a separate terminal):
+
+#+begin_src sh
+nix run .#neo4j-start
+#+end_src
+
+Then enter the shell:
+
+#+begin_src sh
+nix develop .#graphiti
+#+end_src
+
+Configure in =.env.graphiti=.
+
+** Neo4j Management
+
+#+begin_src sh
+nix run .#neo4j-start   # start daemon
+nix run .#neo4j-stop    # stop daemon
+#+end_src
+
+Data persists in =./data/neo4j/=. Web UI at =http://localhost:7474=.
+
+* Configuration
+
+** .env.lightrag
+
+| Variable             | Default              | Notes                    |
+|----------------------+----------------------+--------------------------|
+| =LLM_BINDING=        | =ollama=             |                          |
+| =LLM_MODEL=          | =qwen2.5:7b=         | Change to any Ollama model |
+| =EMBEDDING_MODEL=    | =nomic-embed-text=   |                          |
+| =EMBEDDING_DIM=      | =768=                | Must match model         |
+| =RAG_DIR=            | =./rag_storage=      | Where graph data lives   |
+| =PORT=               | =9621=               |                          |
+
+** .env.graphiti
+
+| Variable          | Default                      | Notes                         |
+|-------------------+------------------------------+-------------------------------|
+| =NEO4J_URI=       | =bolt://localhost:7687=      |                               |
+| =OPENAI_BASE_URL= | =http://localhost:11434/v1=  | Ollama OpenAI-compatible API  |
+| =OPENAI_API_KEY=  | =ollama=                     | Dummy value, required by SDK  |
+| =MODEL_NAME=      | =qwen2.5:7b=                 |                               |
+| =EMBEDDING_MODEL= | =nomic-embed-text=           |                               |
+| =EMBEDDING_DIM=   | =768=                        | Must match model              |
+
+* Structure
+
+#+begin_src
+rags/
+├── flake.nix          — Nix devShells and neo4j apps
+├── flake.lock
+├── .env.lightrag      — LightRAG runtime config
+├── .env.graphiti      — Graphiti runtime config
+├── lightrag/          — submodule: hkuds/lightrag
+├── graphiti/          — submodule: getzep/graphiti
+├── data/
+│   └── neo4j/         — Neo4j data (gitignored)
+└── docs/
+    └── setup.org      — How this was set up
+#+end_src
+
+* Submodules
+
+#+begin_src sh
+git submodule update --init --recursive
+#+end_src