LCARS

LCARS is a private, self-hosted personal knowledge system running on an NVIDIA DGX Spark. It combines local document ingestion, retrieval-augmented generation, durable knowledge collections, a web interface, and chat adapters for an assistant named Computer.

All model inference, document extraction, embeddings, retrieval, OCR, and media transcription run locally.

Current capabilities

• Open WebUI web interface
• Local model inference through Ollama
• Local knowledge collections for System, Inbox, Canonical Knowledge, and Archive
• Incremental synchronization with Open WebUI
• Discord slash-command interface
• Secure Telegram adapter for private, natural conversation
• URL and file ingestion
• PDF and Office document extraction
• OCR for images
• Local audio and video transcription with faster-whisper
• Searchable Markdown sidecars for OCR and media transcripts
• Recoverable archive operations instead of permanent deletion
• Content-hash duplicate detection
• Git-backed application code and policy documents

Architecture

Discord / Telegram / Open WebUI
        |
        v
    Computer
        |
        +--> Open WebUI chat and retrieval APIs
        +--> brain_sync
        +--> local extraction and transcription
        |
        v
System | Inbox | Canonical Knowledge | Archive
        |
        v
Open WebUI knowledge collections and local DGX storage

The repository contains application code and non-sensitive system documentation. Personal knowledge, uploaded files, transcripts, profiles, and credentials remain local and are excluded from Git.

Discord commands

Command	Purpose
/computer	Ask LCARS a question using System and Canonical Knowledge.
/review	Ask a question that also includes Inbox material.
/remember	Store a durable memory.
/ingest	Ingest an article URL or attached file.
/upload	Ingest a file and return a summary.
/delete	Remove an Inbox item from active retrieval by moving it to Archive. Nothing is permanently erased.
/replace	Ingest a replacement, then archive the previous Inbox item.
/promote	Generate a local canonical Markdown draft for explicit review.
/approve	Approve a reviewed draft, synchronize it as canonical knowledge, and archive its Inbox source.
/reset	Clear the current Discord conversation context.

Supported uploads

Documents and structured data

• PDF
• DOCX
• PPTX
• XLSX
• Markdown and plain text
• HTML, CSV, RTF, JSON, XML, YAML, and common source-code formats

Images

• PNG
• JPEG
• TIFF
• BMP
• WebP

Images are processed locally with Tesseract OCR. Extracted text is stored as a searchable Markdown sidecar in the Inbox.

Audio and video

• MP3, WAV, M4A, AAC, FLAC, OGG, and Opus
• MP4, MKV, MOV, AVI, WebM, and M4V

Media is transcribed locally with faster-whisper. A searchable Markdown transcript sidecar is synchronized to the Inbox. Files without detectable speech return an explicit error instead of producing an empty summary.

Repository layout

brain/                  LCARS policies, schemas, and non-sensitive system docs
tools/computer.py       Discord bot and local extraction pipeline
tools/telegram_bot.py   Secure Telegram adapter
tools/lcars_core.py     Shared conversation, retrieval, and file utilities
tools/brain_sync/       Open WebUI synchronization and ingestion tools
start-computer.sh       Discord launcher
start-telegram.sh       Telegram launcher
sync.sh                 Manual synchronization entry point
.gitignore              Privacy boundary for credentials and personal data

The following local paths are intentionally ignored by Git:

inbox/
sources/
archive/
promotions/
logs/
people/
organizations/
projects/
decisions/
topics/
travel/
health/
finance/
home/
music/
watches/
reference/
brain/profile.md
brain/writing-style.md
tools/config.yaml
tools/.venv/

Configuration

Runtime configuration is read from:

/opt/personal-brain/tools/config.yaml

The file contains credentials and is intentionally excluded from Git. It provides:

• Discord bot token and guild name
• Telegram bot token and numeric user-ID allowlist
• Open WebUI URL and API key
• Open WebUI model name
• LCARS root directory
• Optional Whisper model selection

Never commit config.yaml, .env files, API keys, Discord tokens, or personal knowledge content.

A token-free template is tracked at tools/config.example.yaml. Telegram requires this additional private section in tools/config.yaml:

telegram:
  token: "your-bot-token"
  allowed_user_ids:
    - 123456789

The Telegram adapter silently ignores group chats and users whose numeric ID is not listed. Tokens are excluded from logs and object representations.

Promotion drafts and approval logs are local-only personal data and are also excluded from Git.

Running Computer

cd /opt/personal-brain
./start-computer.sh

The launcher works from any directory when called by its full path:

/opt/personal-brain/start-computer.sh

It runs Computer in the foreground so its logs remain visible. Press Ctrl-C to stop it. Successful startup reports that Computer is online and that ten Discord commands were synchronized.

Running the Telegram adapter

After the private Telegram configuration has been added:

cd /opt/personal-brain
./start-telegram.sh

The Telegram adapter is a separate foreground process. It does not replace or restart the Discord process. Its primary interface is ordinary text; /help, /status, /cancel, and /reset remain available as minimal controls.

Manual synchronization

cd /opt/personal-brain
./sync.sh

To preview synchronization changes:

cd /opt/personal-brain/tools
.venv/bin/python brain_sync/main.py --dry-run

Synchronization rebuilds isolated staging directories and updates the corresponding Open WebUI collections. Modified and removed files are detected incrementally. Empty collections are handled explicitly so the final stale item can be removed from an active index.

Ingestion behavior

Uploaded content is named with a SHA-256 prefix:

<16-character-hash>-<sanitized-original-name>

This provides deterministic duplicate detection. Re-uploading identical content refreshes extraction and indexing without creating a second stored item.

For image, audio, and video uploads, LCARS creates:

<stored-name>.extracted.md

The sidecar records the source filename, extraction type, Inbox status, and extracted text.

/delete is deliberately recoverable: the Inbox copy, original source, and extracted sidecar are moved into a timestamped Archive directory and synchronized into the Archive collection.

/replace first ingests the new file. Only after successful ingestion does it archive the previous item. An identical replacement refreshes the existing extraction and does not archive anything.

Privacy and backups

• Personal content stays on the DGX Spark.
• Personal-content paths are ignored by Git.
• Credentials are not tracked.
• The GitHub repository is private and contains application code and non-sensitive documentation only.
• Original uploads are preserved separately from extracted text.
• Archive operations are recoverable and do not permanently erase content.

Project roadmap

1. Finish ingestion — format support, searchable sidecars, update/archive handling, and validation.
2. Promotion workflow — generate reviewable drafts, explicitly approve canonical knowledge with provenance, preserve the source in Archive, and retain a local audit log.
3. iPhone workflow — use Discord as the mobile interface for questions, ingestion, uploads, promotion, approval, and notifications.
4. Shared interface foundation and Telegram — separate LCARS operations from platform-specific handlers; preserve Discord behavior; add an authorized private Telegram interface using long polling; make natural conversation and contextual buttons the primary experience; retain only a minimal set of useful slash commands; and require confirmation before state-changing actions.
5. Scheduled research agents — create one-time and recurring research jobs through either supported interface; perform bounded web research; preserve cited private reports; support durable scheduling, cancellation, recovery, and channel-neutral delivery; and require explicit promotion approval before adding results to canonical knowledge.
6. Email ingestion — dedicated address, attachments, and thread metadata.
7. Remote access — authenticated HTTPS access and an iPhone web app.
8. Conversation improvements — citations, memory management, cross-document retrieval, and summaries.
9. Automation — filesystem watching, scheduled synchronization, comprehensive background-service management, and health monitoring.
10. Long-term knowledge — meetings, daily notes, calendar, email, GitHub, and browser integration.
11. Polish — tests, packaging, installer, logging, backups, and documentation.

Status

Phases 1, 2, and 3 are complete. Phase 4 is in progress. URL ingestion, supported document formats, OCR, audio/video transcription, searchable media sidecars, duplicate refresh behavior, recoverable archive handling, replacement handling, empty-collection cleanup, and Git privacy boundaries have passed end-to-end validation. The promotion workflow creates reviewable local drafts, requires explicit approval, publishes canonical pages with provenance, archives original sources, and records a private local audit trail.

Phase 3 uses Discord as the sole iPhone interface for now. The Discord workflow was validated on macOS and is expected to behave equivalently in the iPhone app. Explicit device-specific iPhone testing is deferred; any mobile-only issue will reopen Phase 3 for targeted validation. Custom iOS Shortcuts and Share Sheet automation are out of scope unless requested later.

Phase 4 planned scope

• 4A — Shared LCARS core: separate retrieval, chat, memory, ingestion, archive, replacement, promotion, approval, authorization, auditing, and response models from Discord-specific interactions without changing current Discord behavior.
• 4B — Secure Telegram connection: create a private Telegram adapter using long polling, keep its token in ignored configuration, authorize only the configured numeric user ID, accept private chats only, and reject groups and unauthorized users.
• 4C — Natural interface: treat ordinary text as a question, present contextual buttons for URLs and attachments, ask follow-up questions when intent is ambiguous, and keep /help, /status, /cancel, and /reset as the minimal primary slash-command set.
• 4D — Safe actions and workflow parity: represent natural-language actions as validated proposals; require confirmation before remembering, ingesting, archiving, replacing, promoting, approving, or scheduling work; and support the existing LCARS workflows through conversation and buttons.
• 4E — Completion: run Discord regression tests and Telegram end-to-end tests; verify conversation isolation, provenance, restart behavior, unauthorized-user rejection, token and log privacy, and Git boundaries; then publish a code-only GitHub update.

Natural-language interpretation will not directly execute consequential actions. Read-only questions, summaries, searches, and status requests may run immediately. Actions that change LCARS state must be validated and explicitly confirmed. Existing operational slash commands may remain available as advanced fallbacks, but normal Telegram use will rely on conversation and contextual buttons.

Phase 4A's shared conversation, retrieval, and file foundations are complete. The initial Phase 4B Telegram adapter and its automated security tests are in place. Live Telegram connection testing remains disabled until a private bot token and numeric allowed user ID are added to the ignored runtime configuration.

Phase 5 planned scope

• 5A — One-time research: channel-neutral job creation, provider-neutral web search, public-page retrieval, bounded research, cited private reports, and delivery to the originating Discord or Telegram conversation.
• 5B — Scheduling: future and recurring jobs, Eastern Time handling, SQLite-backed durable job state, status, pause, resume, and cancellation controls.
• 5C — Reliability: an independently managed research worker, restart recovery, checkpoints, timeouts, retries, concurrency limits, and failure notifications.
• 5D — Hardening: prompt-injection resistance, private-network and unsafe-URL blocking, download and content-type limits, authorized-user enforcement, citation validation, and privacy auditing.
• 5E — Completion: create and manage jobs through both Discord and Telegram, complete an end-to-end overnight test, verify delivery and promotion behavior across both interfaces, document operations, and publish a code-only GitHub update.

Research agents will initially be read-only toward external systems. They may search public sources, retrieve public pages, create private local reports, and notify authorized Discord or Telegram destinations. They may not execute webpage instructions, contact third parties, make purchases, modify external systems, or automatically change canonical knowledge. Research output remains private and ignored by Git; promotion into canonical knowledge continues to require explicit review and approval.