{"id":48220148,"url":"https://github.com/isorensen/lox-brain","last_synced_at":"2026-05-13T03:01:11.804Z","repository":{"id":349158438,"uuid":"1175473944","full_name":"isorensen/lox-brain","owner":"isorensen","description":"Where knowledge lives","archived":false,"fork":false,"pushed_at":"2026-05-12T11:53:58.000Z","size":1289,"stargazers_count":2,"open_issues_count":10,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T13:34:27.999Z","etag":null,"topics":["obsidian","openbrain","secondbrain"],"latest_commit_sha":null,"homepage":"","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/isorensen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","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-03-07T19:00:55.000Z","updated_at":"2026-05-12T11:53:48.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/isorensen/lox-brain","commit_stats":null,"previous_names":["isorensen/lox-brain"],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/isorensen/lox-brain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isorensen%2Flox-brain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isorensen%2Flox-brain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isorensen%2Flox-brain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isorensen%2Flox-brain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/isorensen","download_url":"https://codeload.github.com/isorensen/lox-brain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/isorensen%2Flox-brain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32965783,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-12T23:30:32.555Z","status":"online","status_checked_at":"2026-05-13T02:00:07.132Z","response_time":115,"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":["obsidian","openbrain","secondbrain"],"created_at":"2026-04-04T19:08:50.809Z","updated_at":"2026-05-13T03:01:11.763Z","avatar_url":"https://github.com/isorensen.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n```\n ██╗      ██████╗ ██╗  ██╗\n ██║     ██╔═══██╗╚██╗██╔╝\n ██║     ██║   ██║ ╚███╔╝\n ██║     ██║   ██║ ██╔██╗\n ███████╗╚██████╔╝██╔╝ ██╗\n ╚══════╝ ╚═════╝ ╚═╝  ╚═╝\n```\n\n### Where knowledge lives.\n\n[![CI](https://github.com/isorensen/lox-brain/actions/workflows/ci.yml/badge.svg)](https://github.com/isorensen/lox-brain/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) (core packages) | [![License: Commercial](https://img.shields.io/badge/License-Commercial-blue.svg)](packages/team/LICENSE) (team package)\n[![Node.js](https://img.shields.io/badge/Node.js-22%20LTS-green.svg)](https://nodejs.org/)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)\n\n\u003c/div\u003e\n\n# Lox\n\nLox is a hybrid personal knowledge management system that connects a local [Obsidian](https://obsidian.md) vault with PostgreSQL+pgvector for semantic search, exposed via an MCP Server over WireGuard VPN. Claude Code is a first-class client -- reading, writing, and searching notes through natural language.\n\n**Core principle:** The Obsidian Vault is the source of truth. pgvector is a read index derived from it.\n\n## Architecture\n\n```\nLocal (Obsidian Desktop) \u003c--git sync--\u003e VM (GCE e2-small, us-east1)\n                                         |\n                                         +-- PostgreSQL 16 + pgvector (localhost only)\n                                         +-- Vault Watcher (chokidar, detects .md changes)\n                                         +-- Embedding Service (OpenAI text-embedding-3-small)\n                                         +-- MCP Server (TypeScript, stdio over SSH)\n                                         +-- WireGuard VPN (UDP 51820)\n\nClaude Code --VPN--\u003e MCP Server --\u003e tools\n```\n\n**Data flow:** Local edit -\u003e git push -\u003e VM git pull (cron 2min) -\u003e Watcher -\u003e OpenAI embedding -\u003e pgvector upsert. Reverse: Claude Code -\u003e MCP Server -\u003e creates .md -\u003e Watcher -\u003e embedding -\u003e pgvector -\u003e git push -\u003e local pull.\n\n## Features\n\n- **Semantic search** across your entire vault using OpenAI embeddings + pgvector\n- **Full-text search** with PostgreSQL tsvector\n- **MCP Server** with 6 tools accessible from Claude Code\n- **Vault watcher** that auto-indexes new and modified notes\n- **Text chunking** for large notes (4000 tokens, 200 overlap)\n- **Zero Trust security** -- no public IPs, VPN-only access, secrets in GCP Secret Manager\n- **Git sync** between local vault and VM (bidirectional, 2-min cron)\n- **Claude Skills** shipped out of the box (`/zettelkasten`, more coming) for day-one workflows\n- **CI/CD** via GitHub Actions (build, test, deploy over IAP tunnel)\n\n## Quick Start\n\n### Prerequisites\n\n- [Node.js](https://nodejs.org/) 22 LTS or later\n- [Git](https://git-scm.com/)\n- A GCP account (for VM infrastructure)\n- [Obsidian](https://obsidian.md) (for local vault editing)\n\n### Install\n\n```bash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/isorensen/lox-brain/main/scripts/install.sh | bash\n\n# Windows (PowerShell)\nirm https://raw.githubusercontent.com/isorensen/lox-brain/main/scripts/install.ps1 | iex\n\n# Or clone and run manually\ngit clone https://github.com/isorensen/lox-brain.git\ncd lox-brain\nbash scripts/install.sh\n```\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `write_note` | Create or update a note in the vault |\n| `read_note` | Read the full content of a note by path |\n| `delete_note` | Delete a note from the vault and index |\n| `search_semantic` | Semantic search using embeddings (cosine similarity) |\n| `search_text` | Full-text search using PostgreSQL tsvector |\n| `list_recent` | List recently modified notes |\n\nAll search tools return metadata only by default. Use `read_note` to fetch full content after finding notes. Pagination parameters: `limit`, `offset`, `include_content`, `content_preview_length`.\n\n## Claude Skills\n\nLox ships with Claude Skills that provide opinionated workflows on top of the MCP tools. Installed automatically to `~/.claude/skills/` during setup.\n\n| Skill | Description |\n|-------|-------------|\n| `/zettelkasten` | Generate atomic smart notes from project codebases (3 modes: full scan, topic-focused, review) |\n| `/obsidian-ingest` | Ingest URLs, images, PDFs, and text into the vault with semantic deduplication and categorization |\n| `/sync-calendar` | Sync Google Calendar events to meeting notes, with optional Gemini AI summary integration |\n| `/para` | Organize content using the PARA method (Projects, Areas, Resources, Archives) |\n\n## Monorepo Structure\n\n```\nlox-brain/\n  packages/\n    shared/                # Constants, types, config\n    core/                  # MCP server, vault watcher, embedding service (runs on VM)\n    installer/             # Cross-platform setup wizard (runs locally)\n  skills/\n    zettelkasten/          # /zettelkasten Claude Skill\n    obsidian-ingest/       # /obsidian-ingest Claude Skill\n    sync-calendar/         # /sync-calendar Claude Skill\n    para/                  # /para Claude Skill\n  docs/\n    plans/                 # Design docs and implementation plan\n  templates/\n    para/                  # PARA vault template\n    zettelkasten/          # Zettelkasten vault template\n  .github/\n    workflows/             # CI/CD (build, test, deploy)\n```\n\n## Security (Zero Trust)\n\n- VM public IP **restricted to VPN endpoint** (WireGuard UDP 51820 only)\n- PostgreSQL listens on **localhost only** (127.0.0.1)\n- Firewall: **deny-all** default, only UDP 51820 (WireGuard) open\n- SSH via **IAP tunnel only** (Google range 35.235.240.0/20)\n- Secrets in **GCP Secret Manager** (never hardcoded)\n- Dedicated **service accounts** with least-privilege roles\n- Default VPC **deleted** to reduce attack surface\n- Cloud NAT for **outbound-only** internet access\n- **Cloud Logging** with audit trail\n\n## Development\n\n```bash\nnpm install                              # Install all dependencies\nnpm run build --workspaces               # Build all packages\nnpm run test --workspace=packages/core   # Run tests (vitest)\nnpm run test:coverage                    # Coverage report (target: 80%+)\nnpm run dev                              # Dev mode (tsx watch)\nnpm run watcher                          # Start vault watcher\nnpm run index-vault                      # One-time full vault indexing\n```\n\n## Cost\n\nEstimated monthly cost: **~US$18/month** (GCE e2-small + 30GB pd-ssd + Cloud NAT + minimal traffic).\n\n## Lox Team (Commercial)\n\nLox Team extends the personal brain into a shared, multi-user knowledge base\nfor corporate teams. It is available under a commercial license.\n\n### What Team Mode adds\n\n- **Multi-user identity** via WireGuard VPN peers -- each user is identified\n  by their VPN IP, no auth server needed.\n- **`created_by` attribution** -- every note is tagged with its author\n  automatically.\n- **Team MCP tools** -- `list_team_activity` and `search_by_author` for\n  cross-team knowledge discovery.\n- **Installer team flow** -- guided setup for license validation, peer\n  generation, and WireGuard config distribution.\n\n### Licensing\n\n| Package | License |\n|---------|---------|\n| `packages/core` | MIT |\n| `packages/shared` | MIT |\n| `packages/cli` | MIT |\n| `packages/installer` | MIT |\n| `packages/team` | Commercial (see `packages/team/LICENSE`) |\n\nPersonal mode (single user) is free and open source. Team mode (2+ users)\nrequires a commercial license key. Contact eduardo@isorensen.dev for\nlicensing inquiries.\n\n## Status\n\nLox is under active development. The installer and infrastructure setup are being tested and refined. Breaking changes may occur between minor versions. Check the [CHANGELOG](CHANGELOG.md) and [releases](https://github.com/isorensen/lox-brain/releases) for details.\n\n## Disclaimer\n\nThis software is provided \"as-is\" without warranty of any kind. By using Lox, you acknowledge that:\n\n- **You are responsible for your own data.** Lox stores personal notes, credentials, and API keys on infrastructure you provision. The authors are not responsible for any data loss, unauthorized access, or security incidents arising from misconfiguration, vulnerabilities, or misuse.\n- **GCP costs are your responsibility.** The installer provisions cloud resources (VMs, storage, networking) on your GCP account. Monitor your billing to avoid unexpected charges.\n- **No liability for data breaches.** While Lox follows Zero Trust security principles (VPN-only access, encrypted connections, least-privilege IAM), no system is immune to vulnerabilities. The authors disclaim all liability for personal or corporate data exposure.\n- **Review before deploying in production.** This project is designed for personal use. If you use it in a corporate or team environment, conduct your own security review.\n\nSee the [MIT License](LICENSE) for the full legal terms.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisorensen%2Flox-brain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fisorensen%2Flox-brain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fisorensen%2Flox-brain/lists"}