{"id":51067213,"url":"https://github.com/thefilesareinthecomputer/llm-wiki-agent","last_synced_at":"2026-06-23T07:32:24.422Z","repository":{"id":352783735,"uuid":"1216596802","full_name":"thefilesareinthecomputer/llm-wiki-agent","owner":"thefilesareinthecomputer","description":"LLM Wiki AI agent with optional local inference, knowledge graph, and wiki-style KB tools. Runs in Docker. Can run fully offline with Ollama.","archived":false,"fork":false,"pushed_at":"2026-04-21T06:25:31.000Z","size":16847,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"develop","last_synced_at":"2026-04-21T06:32:03.900Z","etag":null,"topics":["ai","ai-agents","docker","fastapi","knowledge-base","knowledge-graph","lancedb","langextract","llm-wiki","obsidian","ollama","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/thefilesareinthecomputer.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T04:01:16.000Z","updated_at":"2026-04-21T06:25:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/thefilesareinthecomputer/llm-wiki-agent","commit_stats":null,"previous_names":["thefilesareinthecomputer/llm-wiki-agent"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/thefilesareinthecomputer/llm-wiki-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thefilesareinthecomputer%2Fllm-wiki-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thefilesareinthecomputer%2Fllm-wiki-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thefilesareinthecomputer%2Fllm-wiki-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thefilesareinthecomputer%2Fllm-wiki-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/thefilesareinthecomputer","download_url":"https://codeload.github.com/thefilesareinthecomputer/llm-wiki-agent/tar.gz/refs/heads/develop","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/thefilesareinthecomputer%2Fllm-wiki-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34680620,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-23T02:00:07.161Z","response_time":65,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","docker","fastapi","knowledge-base","knowledge-graph","lancedb","langextract","llm-wiki","obsidian","ollama","python"],"created_at":"2026-06-23T07:32:21.793Z","updated_at":"2026-06-23T07:32:24.411Z","avatar_url":"https://github.com/thefilesareinthecomputer.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LLM Wiki Agent\n\nImplementation of the [LLM Wiki Pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) — medallion-tiered storage, hybrid inference, knowledge graph. Runs in Docker. Obsidian-compatible markdown as source of truth.\n\n[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE) [![Python 3.12](https://img.shields.io/badge/python-3.12-3776AB.svg)](https://www.python.org/) [![FastAPI](https://img.shields.io/badge/FastAPI-009688.svg)](https://fastapi.tiangolo.com/) [![Docker](https://img.shields.io/badge/Docker-2496ED.svg)](https://www.docker.com/) [![Ollama](https://img.shields.io/badge/Ollama-000000.svg)](https://ollama.ai/)\n\n\u003cimg src=\"static-assets/images/demo.gif\" alt=\"LLM Wiki Agent UI\" width=\"780\" /\u003e\n\nSwitch models at runtime from the UI dropdown. Any Ollama model works.\n\n## Why\n\nMost agents pick a side: local for privacy, cloud for speed. This doesn't. Ollama locally for sensitive work. Cloud models for heavier reasoning. Same KB either way. You decide per session.\n\n1. **LLM Wiki Pattern as a working system.** Single-concept pages, `[[wiki-links]]`, graph traversal as navigation — [Karpathy's pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f), built out.\n2. **Medallion tiers.** `canon/` (gold, read-only) \u003e `knowledge/wiki/` (silver, agent-writable) \u003e `knowledge/raw/` (bronze, source). Search ranks accordingly. Agent reads sources, never overwrites them.\n3. **Honest tool execution.** Results labeled `COMPLETE`, `TRUNCATED`, or `NOT_EXECUTED`. Skipped and duplicate calls never marked complete. UI shows the difference.\n\n## Inference Modes\n\n| Use Case | Chat | Embeddings | Network |\n|----------|------|------------|---------|\n| Fully local | Ollama (local) | Ollama (local) | None |\n| Hybrid | Ollama (local or cloud) | Gemini (cloud) | Embeddings only |\n| Fully cloud | Ollama Cloud | Gemini (cloud) | Required |\n\n## Quick Start\n\n```bash\ngit clone https://github.com/thefilesareinthecomputer/llm-wiki-agent.git\ncd llm-wiki-agent\n\necho \"GOOGLE_GEMINI_API_KEY=AIza...\" \u003e .env\necho \"EMBEDDING_PROVIDER=gemini\" \u003e\u003e .env\n\ndocker compose up --build -d\n\n# http://localhost:8080\n```\n\nDocker Desktop + [Ollama](https://ollama.ai) with a model pulled + Gemini API key.\n\n`src/` and `tests/` are copied at build time, not bind-mounted. After edits: `docker compose down \u0026\u0026 docker compose up --build -d`, then test in container.\n\n## What it does\n\n| | |\n|---|---|\n| **15 KB tools** | list, read tree/section, search, save; graph neighbors/traverse/search/stats, describe node, folder tree; search/read conversations; lint, compile — native Ollama JSON-schema tool calling |\n| **Knowledge graph** | 6 edge types (SIMILAR, INTER_FILE, CROSS_DOMAIN, PARENT_CHILD, REFERENCES, RELATES_TO). Edge provenance (`link_text`, `link_kind`, `evidence`) in every graph tool response |\n| **Medallion architecture** | `canon/` \u003e `knowledge/wiki/` \u003e `knowledge/raw/`. Agent writes only to wiki. Search ranks canon above wiki above raw |\n| **LLM Wiki Pattern** | Single-concept pages, `[[wiki-links]]`, `compile_knowledge(source)` plans pages from raw, `lint_knowledge()` flags omnibus files/orphans/broken links |\n| **Honest tool framing** | `COMPLETE` / `TRUNCATED` / `NOT_EXECUTED` — skipped and duplicate calls never labeled complete |\n| **Adaptive budgets** | 15 section loads max per turn, 8K tokens min remaining, per-class caps, ~50% context cap on tool traffic |\n| **Streaming tool loop** | Ollama native `tool_calls`, `asyncio.to_thread` execution, dedup of identical `(name, args)`, SSE lifecycle events |\n| **Obsidian-compatible** | Frontmatter, `[[wiki-links]]`, heading trees with token costs — works as a vault |\n\n\u003cdetails\u003e\n\u003csummary\u003eFull feature list\u003c/summary\u003e\n\n- Local inference via Ollama — no cloud API required for chat\n- Gemini embeddings (gemini-embedding-001, 768-dim, cloud) or Ollama (nomic-embed-text, local)\n- Model switching at runtime\n- Conversation sessions — create, switch, delete; persists across reloads\n- Heading trees with token costs — agent sees structure before loading\n- Section-based chunking — H1-H5 hierarchy, recursive splitting, doc-level LLM overviews\n- LLM summary preservation — reindex/save/watcher never overwrite stored LLM summaries\n- Watcher path-suppression — save triggers one inline reindex, not four\n- SSE streaming — thinking tokens, per-iteration lifecycle events\n- KB file watcher — auto reindex on markdown changes\n- Structured JSONL debug logging\n- Glassmorphism UI — dark theme, collapsible tool/thinking bubbles, live elapsed timers\n\u003c/details\u003e\n\n## Tech Stack\n\n| Layer | Technology |\n|-------|------------|\n| Container | Docker (`python:3.12-slim`, non-root) |\n| Runtime | Python 3.12 |\n| Web Server | FastAPI + Uvicorn |\n| Inference | Ollama (`host.docker.internal:11434`) |\n| Embeddings | Gemini `gemini-embedding-001` (cloud) or Ollama `nomic-embed-text` (local) |\n| Vector Search | LanceDB (768-dim) |\n| Knowledge Graph | In-memory, JSON persistence |\n| Token Counting | tiktoken (cl100k_base) |\n| Knowledge Base | Markdown, Obsidian-compatible, section-based chunking |\n| UI | Vanilla JS + CSS |\n\n## Project Structure\n\n```\nllm-wiki-agent/\n├── src/\n│   ├── main.py              # Entry point\n│   ├── debug_log.py         # Structured JSONL logging\n│   ├── models/\n│   │   └── gateway.py       # Ollama client, streaming, model switch\n│   ├── web/\n│   │   └── app.py           # FastAPI, tool loop, SSE, conversations, KB\n│   ├── memory/\n│   │   └── store.py         # JSON session persistence\n│   ├── knowledge/\n│   │   ├── index.py         # LanceDB, embeddings, summaries, graph\n│   │   ├── chunker.py       # H1-H5 heading trees, chunk splitting\n│   │   ├── graph.py         # Knowledge graph, folder tree, traversal\n│   │   ├── wiki_links.py    # [[wiki-link]] parsing\n│   │   └── prose_bridges.py # Prose reference extraction\n│   └── agent/\n│       ├── tools.py          # 15 KB tools, budgets, Obsidian writes\n│       ├── tokenizer.py      # Token counting, slice, truncate\n│       ├── kb_paths.py       # Canonical filename helpers\n│       └── watcher.py       # KB file watcher\n├── ui/\n│   ├── index.html\n│   ├── app.js               # SSE, markdown, sessions, tool events\n│   ├── kb-graph-hud.js      # Graph HUD overlay\n│   └── style.css            # Dark glassmorphism theme\n├── tests/                    # ~723 unit + integration; e2e/evals separate\n├── knowledge/                # Writable KB\n├── canon/                    # Read-only KB\n├── Dockerfile\n├── docker-compose.yml\n├── requirements.txt\n└── ARCHITECTURE.md\n```\n\n## Testing\n\n```bash\ndocker exec llm-wiki-agent timeout 600 python -m pytest tests/ --ignore=tests/e2e --ignore=tests/evals -q\n```\n\n724 passed, 0 skipped. E2E needs live Ollama: `docker exec llm-wiki-agent python -m pytest tests/e2e -v`.\n\n## Configuration\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `EMBEDDING_PROVIDER` | `gemini` | `gemini` (cloud) or `ollama` (local) |\n| `GOOGLE_GEMINI_API_KEY` | (required) | Starts with `AIza...` |\n| `OLLAMA_BASE_URL` | `http://host.docker.internal:11434` | Ollama endpoint |\n| `OLLAMA_MODEL` | `llama3.1:8b` | Default chat model |\n| `SUMMARY_MODEL` | `llama3.1:8b` | LLM summary model |\n| `LANCEDB_DIR` | `/app/lancedb` | LanceDB data dir |\n\n**Volume mounts:** `./knowledge` → `/app/knowledge`, `./canon` → `/app/canon`, `./lance-data` → `/app/lancedb`\n\n**Switching embedding providers:** set `EMBEDDING_PROVIDER=ollama` in `.env`, wipe `lance-data/*` (spaces are incompatible), rebuild.\n\n## Architecture\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) — module map, data flow, embedding pipeline, graph construction, tool loop, design decisions.\n\n## License\n\n[MIT](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthefilesareinthecomputer%2Fllm-wiki-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fthefilesareinthecomputer%2Fllm-wiki-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fthefilesareinthecomputer%2Fllm-wiki-agent/lists"}