{"id":48779720,"url":"https://github.com/lisaross/tana-local-kb","last_synced_at":"2026-04-13T13:34:23.467Z","repository":{"id":314914917,"uuid":"1057306058","full_name":"lisaross/tana-local-kb","owner":"lisaross","description":"Transform your Tana database into a locally-hosted, AI-queryable knowledge system that preserves relationships while enabling semantic search.","archived":false,"fork":false,"pushed_at":"2025-09-15T14:58:49.000Z","size":12,"stargazers_count":0,"open_issues_count":13,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-15T16:35:54.066Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/lisaross.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":"2025-09-15T14:49:17.000Z","updated_at":"2025-09-15T14:58:52.000Z","dependencies_parsed_at":"2025-09-15T16:35:57.609Z","dependency_job_id":"3d9c3abe-096c-411e-95d2-38793a13fc4b","html_url":"https://github.com/lisaross/tana-local-kb","commit_stats":null,"previous_names":["lisaross/tana-local-kb"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/lisaross/tana-local-kb","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisaross%2Ftana-local-kb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisaross%2Ftana-local-kb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisaross%2Ftana-local-kb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisaross%2Ftana-local-kb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lisaross","download_url":"https://codeload.github.com/lisaross/tana-local-kb/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lisaross%2Ftana-local-kb/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31755148,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-13T13:27:56.013Z","status":"ssl_error","status_checked_at":"2026-04-13T13:21:23.512Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":[],"created_at":"2026-04-13T13:34:09.336Z","updated_at":"2026-04-13T13:34:23.437Z","avatar_url":"https://github.com/lisaross.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Tana Local Knowledge Base 🧠\n\nTransform your Tana database into a powerful, locally-hosted AI knowledge system. Chat with your notes, find connections you never knew existed, and explore your thoughts with semantic search—all running entirely on your machine.\n\n![Status: Parser Complete](https://img.shields.io/badge/Status-Parser%20Complete-green)\n![License: MIT](https://img.shields.io/badge/License-MIT-blue)\n![Built with Bun](https://img.shields.io/badge/Built%20with-Bun-orange)\n\n## ✨ What is this?\n\nIf you love Tana's powerful note-taking but want to:\n- **Ask questions** in natural language about your knowledge base\n- **Find connections** between ideas using AI semantic search  \n- **Keep everything local** - no cloud, no privacy concerns\n- **Maintain relationships** - all your Tana structure preserved\n\nThen this is for you!\n\n## 🚀 Quick Demo\n\n```bash\n# 1. Clone and setup (takes ~5 minutes)\ngit clone https://github.com/lisaross/tana-local-kb.git\ncd tana-local-kb\nbun install\n\n# 2. Test parser with your Tana export\nbun run test-parser ~/Downloads/your-tana-export.json\n\n# 3. Start everything\nbun run dev:all\n\n# 4. Open http://localhost:5173 (UI coming in Phase 2) 💬\n```\n\n## 🎯 Core Features\n\n### ✅ **Streaming JSON Parser** (Phase 1 Complete!)\n- **Memory Efficient**: Parse 1M+ Tana nodes using \u003c100MB RAM\n- **System Node Filtering**: Automatically removes Tana system/template nodes\n- **Progress Tracking**: Real-time progress callbacks for large imports\n- **Error Recovery**: Continues parsing even with malformed JSON\n- **Performance**: 2,000+ nodes/second throughput\n- **CLI Testing**: `bun run test-parser your-export.json`\n\n### 🚧 **Coming in Phase 2**\n- **💬 Chat Interface**: Ask questions about your knowledge base\n- **🔍 Hybrid Search**: Semantic + keyword + graph relationship search\n- **⚡ Command Palette**: `Cmd+K` for instant note discovery\n- **🔗 Relationship Navigation**: Click through your knowledge graph\n\n## 🛠 Tech Stack\n\nWe chose the fastest, most modern tools:\n\n- **🔥 Bun**: 4x faster than Node.js for everything\n- **⚛️ React + TypeScript**: Solid, type-safe frontend\n- **🚀 Hono + tRPC**: Lightning-fast APIs with end-to-end type safety\n- **🤖 Ollama**: Local AI models (Llama 3.2 3B)\n- **📊 ChromaDB**: Vector database for semantic search\n- **💎 SQLite**: Bun's native database for relationships\n\n## 📋 Prerequisites\n\n- **Bun** runtime ([install here](https://bun.sh))\n- **Ollama** for AI ([install here](https://ollama.ai))\n- **Docker** for ChromaDB (or Python with uv)\n- Your Tana JSON export\n\n## 🏃‍♂️ Getting Started\n\n### 1. Install Dependencies\n\n```bash\n# Install Bun (if you haven't already)\ncurl -fsSL https://bun.sh/install | bash\n\n# Clone the repo\ngit clone https://github.com/lisaross/tana-local-kb.git\ncd tana-local-kb\n\n# Install JavaScript dependencies\nbun install\n\n# Setup Python environment for ChromaDB\ncurl -LsSf https://astral.sh/uv/install.sh | sh\nuv venv\nsource .venv/bin/activate  # or .venv\\Scripts\\activate on Windows\nuv pip install chromadb fastapi uvicorn\n```\n\n### 2. Start AI Services\n\n```bash\n# Start Ollama and download models\nollama pull llama3.2:3b\nollama pull nomic-embed-text\n\n# Start ChromaDB (choose one)\ndocker run -p 8000:8000 chromadb/chroma\n# OR: uv run chroma run --path ./data/chroma\n```\n\n### 3. Test Parser with Your Data\n\nExport your Tana workspace as JSON, then test the parser:\n\n```bash\n# Test parser with your Tana export\nbun run test-parser ~/Downloads/your-tana-export.json\n\n# Test with specific performance preset\nbun run test-parser ~/Downloads/your-export.json MEMORY_EFFICIENT\n\n# Run parser test suite\nbun run test:parser:quick    # Quick tests (~30 seconds)\nbun run test:parser         # Full test suite (~30 minutes)\n```\n\nNote: Full import system with database integration coming in Phase 2!\n\n### 4. Start the Application\n\n```bash\n# Start everything at once\nbun run dev:all\n\n# Or start services individually:\n# bun run server    # Backend API\n# bun run dev       # Frontend\n# bun run chroma    # ChromaDB service\n```\n\n### 5. Explore the Parser! 🎉\n\nThe streaming parser is ready to test with your Tana exports! Visit `http://localhost:5173` to see the basic server health check. Full UI coming in Phase 2.\n\n## 💡 Current Usage (Phase 1)\n\n- **Test Parser**: `bun run test-parser your-export.json` to validate your Tana data\n- **Performance Presets**: Try FAST, BALANCED, THOROUGH, or MEMORY_EFFICIENT modes\n- **Test Suite**: Run `bun run test:parser:quick` to validate the parser\n- **Memory Monitoring**: Parser tracks memory usage and provides detailed statistics\n\n### Coming in Phase 2:\n- **Search Everything**: Use `Cmd+K` to quickly find any note\n- **Ask Questions**: Try \"What are my main projects?\" or \"Show me notes about AI\"\n- **Follow Links**: Click through relationships just like in Tana\n- **Browse Tables**: Use the data table to filter and sort your notes\n\n## 🔧 Development\n\nFor developers wanting to contribute or customize:\n\n```bash\n# Run tests\nbun test                    # General tests\nbun run test:parser         # Parser test suite (30 min)\nbun run test:parser:quick   # Quick parser tests (30 sec)\n\n# Type checking\nbun run type-check\n\n# Linting and formatting\nbun run lint\nbun run format\n\n# Parser testing and validation\nbun run test-parser /path/to/export.json        # Test parser on real data\nbun run test-parser /path/to/export.json FAST   # With performance preset\n\n# Database operations (coming in Phase 2)\nbun run db:inspect    # View database schema\nbun run migrate       # Run migrations\n```\n\nSee [WARP.md](./WARP.md) for detailed technical documentation.\n\n## 🎯 Roadmap\n\n### ✅ Phase 1 Complete (Week 1)\n- [x] Repository setup and project foundation\n- [x] **Streaming JSON Parser** - Memory-efficient parser for large Tana exports\n  - [x] Handles 1M+ nodes in \u003c100MB RAM\n  - [x] System node filtering (removes SYS_ nodes)\n  - [x] Progress tracking and error recovery\n  - [x] 93%+ test coverage with comprehensive test suite\n  - [x] CLI tool (`bun run test-parser`)\n  - [x] Multiple performance presets\n\n### 🔄 Phase 2 (Week 2) - Next Up\n- [ ] **tRPC API setup** - Type-safe APIs using the parser\n- [ ] **Database integration** - SQLite schema for parsed nodes\n- [ ] **Import system** - Full import using streaming parser\n- [ ] **ChromaDB integration** - Vector embeddings for semantic search\n- [ ] Basic search functionality and node viewer\n- [ ] Simple chat interface with Ollama\n\n### 🚀 Phase 3 (Week 3)\n- [ ] Hybrid search (semantic + keyword + graph)\n- [ ] Command palette (`Cmd+K`)\n- [ ] Data table browser with TanStack Table\n- [ ] Enhanced chat with source citations\n- [ ] Graph visualization\n- [ ] Performance optimizations\n- [ ] Export functionality\n- [ ] Settings UI\n\n## 🤝 Contributing\n\nWe'd love your help! Here's how to get started:\n\n1. **Fork** the repository\n2. **Create** a feature branch: `git checkout -b amazing-feature`\n3. **Make** your changes and add tests\n4. **Run** the test suite: `bun run test:all`\n5. **Submit** a pull request\n\n## 🐛 Troubleshooting\n\n### ChromaDB won't start?\n```bash\n# Check if it's running\ncurl http://localhost:8000/api/v1/heartbeat\n\n# Restart if needed\ndocker restart chroma-container\n```\n\n### Ollama models not loading?\n```bash\n# List available models\nollama list\n\n# Pull required models\nollama pull llama3.2:3b nomic-embed-text\n```\n\n### Parser failing?\n```bash\n# Validate your Tana export first\nbun run validate-json --file your-export.json\n\n# Test parser with debug info\nbun run test-parser your-export.json\n\n# Run parser test suite to check for issues\nbun run test:parser:quick\n```\n\nNeed more help? Check out the [detailed troubleshooting guide](./WARP.md#debugging) in WARP.md.\n\n## 📄 License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\n## 🙏 Acknowledgments\n\n- [Tana](https://tana.inc/) for creating an amazing note-taking system\n- [Ollama](https://ollama.ai/) for making local AI accessible\n- [Bun](https://bun.sh/) for blazing-fast JavaScript runtime\n\n---\n\n**Built with ❤️ by [Lisa Ross](https://github.com/lisaross)**\n\n*Transform your knowledge. Chat with your thoughts. Keep it local.*","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisaross%2Ftana-local-kb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flisaross%2Ftana-local-kb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flisaross%2Ftana-local-kb/lists"}