ltcai 2.1.0

Lattice AI Workspace OS for local-first graph, memory, agent, workflow, and skill operations

Lattice AI — Local-first Agentic Workspace Platform: plugins, visual workflows, multi-agent runs, and realtime activity over your graph, memory, skills, and timeline.

---

What is Lattice AI?

Most AI tools answer one chat at a time. They do not remember your folders, your project history, your previous decisions, or how your files relate to each other.

Lattice AI turns your local workspace into a Local-first Agentic Workspace Platform.

It reads approved local folders, indexes chats and documents, builds a searchable knowledge graph, and connects the graph to snapshots, personal memory, agent runs, workflow history, skills, and an auditable timeline.

Local files + chats + folders
          ↓
Automatic knowledge graph
          ↓
Graph-aware chat, snapshots, memory, agents, workflows, skills, and timeline

Why Lattice AI?

• Local-first by default — models, data, and your knowledge graph stay on your machine (~/.ltcai/); cloud is strictly opt-in.
• Memory that compounds — every chat, file, and folder you approve becomes durable, searchable context instead of being forgotten.
• A graph, not a pile of files — people, projects, documents, decisions, and tasks are linked automatically and explored visually.
• One workspace, everywhere — the same local knowledge powers the web UI, VS Code / Cursor, Telegram, and MCP clients.
• Built-in governance — Personal and Organization workspaces, roles, an audit timeline, and sensitive-data monitoring for teams.

Core Capabilities

Capability	What it does
🧠 Automatic knowledge graph	Turns chats, files, and folders into linked nodes and edges, curated automatically
💬 Graph-aware chat & agents	Answers and multi-step agents grounded in your indexed local memory
🖥️ Local model recommendation	Scans your hardware and rates each model Recommended / Compatible / Not Recommended
🗂️ Workspaces & roles	Personal and Organization workspaces with owner / admin / member / viewer permissions
🧩 Skills & MCP	Install skills and connect MCP tools from the in-product marketplace
🔒 Admin & security	Audit timeline, permission approvals, sensitive-data detection, exportable reports

---

Quick Start

Python / PyPI

pip install ltcai
LTCAI
# open http://localhost:4825

Apple Silicon local models

pip install "ltcai[local]"
LTCAI

Node / npm

npm install -g ltcai
LTCAI

VS Code / Cursor

1. Install Lattice AI from the VS Code Marketplace or Open VSX
2. Start the local server with LTCAI
3. Press Cmd+Shift+A to open the chat panel

First run: create an account -> the first account becomes admin -> open /workspace -> complete onboarding -> choose a model -> connect folders -> start asking questions.

---

The 3-minute workflow

1. Install
   pip install ltcai && LTCAI

2. Detect hardware
   CPU, GPU, RAM are detected and a suitable local model is recommended.

3. Connect folders
   Pick the local folders you want Lattice AI to index.

4. Build knowledge
   Files and chats become nodes and edges in a local knowledge graph.

5. Ask questions
   “What did I decide about the auth migration last week?”

6. Keep working
   Use the same local knowledge from the web UI, VS Code, Telegram, or MCP clients.

---

Architecture

server:app stays a thin compatibility entrypoint; the FastAPI app is assembled in latticeai/server_app.py, and the work lives in focused API routers, a service layer, and core modules — so the app shell never grows monolithic again.

See docs/architecture.md for request and data-flow detail.

---

Product Preview

Workspace Chat Chat with local/cloud models, upload files, and control pipelines.

Knowledge Graph Automatically built from chats, files, folders, and project context.

Admin Dashboard User management, audit logs, permissions, and security monitoring.

Every image in this section is a real screenshot of the running app (Lattice AI v2.0.0), captured with a headless browser.

---

Product Experience

Onboard in minutes

A first run detects your OS, CPU, GPU, RAM, and disk, then recommends a local model and rates every option Recommended, Compatible, or Not Recommended for your machine — grouped by family (Gemma, Qwen, Llama, Phi, DeepSeek, and more), with estimated RAM and a clear next step.

Workspaces & organization

A Current Workspace card shows exactly where you are; switch instantly between a Personal workspace and shared Organization workspaces. Org data is scoped by workspace_id, and owner / admin / member / viewer roles map to a transparent permission matrix with member management. A Workspace Health panel summarizes indexed files, graph size, installed skills, memories, agent runs, current model, last sync time, and status at a glance.

Knowledge graph explorer

Your work becomes a typed knowledge graph automatically. The Entity Explorer surfaces the most important entities and, on selection, their inbound/outbound relationships, related entities, and a path back to you.

The Graph Canvas also supports node expand/collapse, focused subgraphs, relationship highlighting, shortest-path visualization, and direct navigation back into source conversations or files.

Skills & editions

Browse and install skills from an in-product marketplace; an honest editions panel shows that every Enterprise capability is an opt-in extension point, disabled in the open-source Community build.

---

Why it is different

Problem	Lattice AI approach
AI forgets every conversation	Chats and files are indexed into persistent local memory
Files are scattered across folders	Approved folders become searchable graph context
Local model setup is confusing	Hardware detection recommends and loads a suitable model
Graph tools require manual node editing	Nodes and edges are created automatically from real work
Cloud AI may expose private data	Local models keep data on your machine; cloud is opt-in
Teams need visibility	Admin dashboard, audit logs, role controls, and sensitive-data monitoring

---

Core Features

Local-first AI workspace

• Web UI running from a local server
• Local SQLite storage under ~/.ltcai/
• Local folder indexing with explicit approval
• File upload, chat history, graph search, and document generation
• Optional cloud providers when you choose to use them

Automatic knowledge graph

Lattice AI turns your work into structure automatically.

Nodes can represent:

Node type	Examples
Document	PDF, DOCX, PPTX, XLSX, Markdown, code files
Concept	technologies, project names, ideas, architecture topics
Person	you, teammates, mentioned people
Chat	previous conversations and sessions
Task	TODOs, action items, follow-ups
Decision	choices made during discussions

Edges describe relationships such as:

mentions · contains · depends on · explains · uses · replaces · supports · related to

The graph is curated automatically: noisy tokens, file extensions, generic words, and hard secrets are filtered before promotion.

Model loading that users can trust

Lattice AI keeps model identity consistent across recommendation, download, load, backend router state, and frontend display.

• unified model resolution
• local model smoke test after load
• ok / degraded / failed compatibility status
• per-family compatibility profiles for GPT-OSS, Gemma, Qwen, Llama, Mistral, Phi, Deepseek, and more
• fast post-processing path during normal chat
• recovery path only when output looks broken

Admin and security command center

For team or organization usage, Lattice AI includes admin-facing controls:

• user management and roles
• permission approvals for local file access
• audit event timeline
• sensitive chat/file detection
• risk overview by user
• raw data explorer with hard-secret redaction
• export to JSON, CSV, XLSX, TXT, or PDF

Hard secrets such as API keys, tokens, passwords, private keys, and common cloud credentials are redacted from security responses.

---

Supported Models

Local on Apple Silicon MLX

Model	Best for	Approx. size	Suggested RAM
Qwen3-VL 4B	Multimodal / low spec	~2.7 GB	8 GB
Qwen3-VL 8B	Multimodal / balanced	~4.8 GB	16 GB
GPT-OSS 20B	Reasoning / open-weight	~12.1 GB	32 GB
Gemma 4 26B	Multimodal / large	~15.6 GB	32 GB
Gemma 4 31B	Multimodal / latest Gemma 4	~18.4 GB	48 GB
Qwen3-VL 30B A3B	Multimodal / top local	~18 GB	48 GB
GPT-OSS 120B	Large reasoning model	~62.3 GB	128 GB
Phi 4 Mini	Fast coding/general chat	~2.2 GB	8 GB
Llama 3.1 8B	General chat	~4.7 GB	8 GB
Mistral 7B v0.3	General / Apache	~4.1 GB	8 GB

Cross-platform engines

Lattice AI can also work with models served by:

• Ollama
• LM Studio
• llama.cpp
• vLLM
• OpenAI-compatible local or remote endpoints

Cloud providers

Cloud models are optional. When enabled, prompts are sent to the selected provider.

Supported routes include OpenAI-compatible APIs, OpenRouter, Groq, Together, xAI, and other compatible endpoints.

---

Privacy and data storage

Area	Default behavior
Storage	Data is stored locally under ~/.ltcai/
Default binding	127.0.0.1:4825 local server
Telemetry	No built-in product telemetry by default
Folder access	Explicit approval per folder/action scope
Sensitive files	.env, credentials, keys, certificates, and similar files are auto-excluded
Cloud models	Off unless configured; cloud prompts go to the selected provider
Delete controls	Remove chats, graph nodes, indexed folders, and local data

---

Comparison

Capability	Lattice AI	Open WebUI	Continue.dev	GitHub Copilot
Local model workflow	Yes	Yes	Yes	No
Local folder indexing	Yes	Limited	Workspace-focused	Limited
Automatic knowledge graph	Yes	No	No	No
Chat + file memory	Yes	Partial	Partial	Partial
VS Code / Cursor extension	Yes	No	Yes	Yes
Admin dashboard	Yes	Yes	No	No
Security audit exports	Yes	Limited	No	No
Optional cloud models	Yes	Yes	Yes	Yes
Local-first by default	Yes	Self-hosted	Local/dev focused	No

---

Current release

2.1.0 — Agent Platform Maturity Release. Lattice AI operationalizes the v2.0 platform without replacing it: agent handoff, context packets, review/retry, planning, memory, replay, marketplace templates, and realtime execution observability are now first-class and still additive.

• Agent handoff + context packets — handoffs now carry handoff_id, source/target agent ids, reason, status, timestamps, and safe structured context packets for replayable role transfer.
• Review / retry loops — Planner -> Executor -> Reviewer records plan review, reviewer notes, retry history, retry limits, and failure propagation.
• Timeline / replay — agent and workflow runs expose replay frames showing who acted, when, why, input, output, and decisions.
• Agent memory + planning — short-term, workspace, and long-term memory kinds are supported with workspace-scoped snapshots; plans are persisted with run history and plan-review metadata.
• Workflow / agent / plugin hardening — plugin outputs enter agent context, agent outputs enter workflow outputs, and plugin/workflow/agent failures emit observable execution events.
• Marketplace foundation — local Plugin, Workflow, and Agent templates have metadata, export/import, install hooks, and a registry. No cloud marketplace service is introduced.
• Realtime execution observability — existing SSE feed now emits agent, handoff, review, retry, workflow, plugin, and execution failure events.
• Compatibility preserved — API schemas, server:app, latticeai.server_app.app, CLI, MCP, model, workspace, chat, KG, existing skills/snapshots/memories/agent history, and the VS Code extension remain backward compatible. Changes are additive; no destructive migrations.

Version	Theme
2.1.0	Agent Platform Maturity Release (handoff, context packets, review/retry, replay, memory, planning, marketplace foundation)
2.0.0	Agentic Workspace Platform (Plugin SDK, Workflow Designer, Multi-Agent Runtime, Realtime)
1.7.0	Graph & Collaboration Release
1.6.0	Product Experience Deepening (UX + real screenshots)
1.5.0	Unified Product Release (CI/VSIX recovery, model recommendation, Enterprise PoC)
1.4.0	Server App final decomposition
1.1.0–1.3.0	Organization workspaces, modularization, route safety net

See the full changelog and RELEASE.md.

---

All Features

Core experience

Feature	Description
Web UI	Chat, file upload, model picker, graph view, admin pages
Auto setup wizard	Detect hardware, recommend model, install dependencies, verify load
Graph RAG	Retrieve context from indexed chats, files, and graph relationships
Local folder indexing	Browse, audit, approve, index, and optionally watch folders
Document generation	Use graph context to generate reports, summaries, and structured drafts

Developer tools

Feature	Description
VS Code / Cursor	Chat panel, edit selection, explain code, generate code
Multi-step agent	File edit/create, grep, todo, and terminal workflow with human-in-the-loop
Multi-LLM pipeline	Plan, execute, and review with different models
MCP server	Expose Lattice tools to MCP-compatible clients
MCP registry	Install MCP servers from supported registries
Skills browser	Browse and install optional skills
Plugin browser	Browse compatible open-source plugins

Access and communication

Feature	Description
Telegram bot	Chat, upload files, and manage models remotely
PWA	Install the web UI on mobile/tablet home screens
Public tunnel	LTCAI --tunnel for a temporary Cloudflare HTTPS URL

Administration

Feature	Description
User management	Roles, permissions, account enable/disable
SSO	Entra ID / Okta OIDC configuration
Audit dashboard	AI usage, sensitive-data events, file access, exports
Security monitoring	Rate limits, approval logs, raw explorer, redaction

Security

Property	Detail
Binding	Default 127.0.0.1:4825 local only
Auth	Session required when network-exposed or public mode
Cookies	HttpOnly + SameSite=Lax; no localStorage token
Local file access	Approval-token gated by path, user, and action scope
Package install	Admin-only with audit trail for MCP, skills, pip, npm
CORS	Localhost only by default; configurable via LATTICEAI_CORS_ALLOWED_ORIGINS
File upload	Magic-number signature checks for extension spoofing defense
Rate limits	/chat 30/min · /agent 6/min · /upload 12/min per user
Telemetry	No built-in product telemetry by default

Report vulnerabilities in SECURITY.md.

Setup & Configuration

VS Code shortcuts

Shortcut	Action
Cmd+Shift+A	Open chat
Cmd+Shift+E	Edit selected code
Cmd+Shift+M	Load or switch model
Right-click	Explain / Save to Knowledge Garden

Telegram bot

LATTICEAI_TELEGRAM_BOT_TOKEN=your-token LTCAI

Public server

LATTICEAI_MODE=public \
LATTICEAI_PUBLIC_MODEL=openai:gpt-4o-mini \
OPENAI_API_KEY=sk-... \
LATTICEAI_INVITE_CODE=my-secret \
LTCAI

Public tunnel

LTCAI --tunnel
# → https://xxxx.trycloudflare.com

Auto-start on macOS

cat > ~/Library/LaunchAgents/com.ltcai.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.ltcai</string>
  <key>ProgramArguments</key><array><string>/usr/local/bin/LTCAI</string></array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/ltcai.log</string>
  <key>StandardErrorPath</key><string>/tmp/ltcai.err</string>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/com.ltcai.plist

API Reference

Method	Path	Description
GET	/health	Server status and current model
GET	/models	Model list and load state
POST	/models/load	Load a model
POST	/chat	Chat with streaming or non-streaming output
POST	/agent	Multi-step file agent
GET	/knowledge-graph/stats	Graph statistics
GET	/knowledge-graph/search?q=	Search the knowledge graph
GET	/knowledge-graph/local/roots	Discover local drives and folders
POST	/knowledge-graph/local/audit	Audit a folder before indexing
POST	/knowledge-graph/local/index	Index a folder into Graph RAG
GET	/mcp/installed	Installed MCP servers
POST	/mcp/install	Install MCP server as admin
GET	/skills/marketplace	Skills marketplace
POST	/skills/install	Install a skill as admin
GET	/admin/audit	Audit report
GET	/permissions/pending	Pending file-access approvals

Full reference: docs/mcp-tools.md

Troubleshooting

Symptom	Fix
Port 4825 is already in use	lsof -i :4825 then kill <PID>, or run LTCAI --port 4826
ModuleNotFoundError: mlx	Install local extras with pip install "ltcai[local]" on Apple Silicon
Python version is too old	Use Python 3.11 or newer
No API key warning	Set a provider key or use a local model
Cannot reach from iPad	Use LATTICEAI_HOST=0.0.0.0 LTCAI or LTCAI --tunnel
Model loads but chat looks broken	Check compatibility status; try another engine or model family

---

Platform Support

Feature	macOS Apple Silicon	macOS Intel / Windows / Linux
Web UI + cloud models	Yes	Yes
VS Code / Cursor extension	Yes	Yes
Telegram bot	Yes	Yes
MLX local models	Yes	No
Ollama / LM Studio / vLLM / llama.cpp	Yes	Yes

---

Distribution

Channel	Link
PyPI	pypi.org/project/ltcai
npm	npmjs.com/package/ltcai
VS Code Marketplace	marketplace.visualstudio.com
Open VSX	open-vsx.org

---

Documentation

Doc	What's inside
docs/architecture.md	App structure, request and data flow
docs/CHANGELOG.md	Full version history
RELEASE.md	Release notes and the build/publish checklist
SECURITY.md	Security model and vulnerability reporting
docs/ENTERPRISE.md · docs/EDITION_STRATEGY.md	Open-core boundary and edition strategy
docs/kg-schema.md · docs/mcp-tools.md	Knowledge graph schema and MCP tool catalog
docs/privacy.md · docs/public-deploy.md · docs/OPERATIONS.md	Privacy, public deployment, operations

---

Contributing

See CONTRIBUTING.md. Issues and pull requests are welcome.

License

MIT — TaeSoo Park

---

한국어 안내 (Korean)

Lattice AI

내 PC의 파일, 대화, 폴더를 기억하고 연결하는 로컬 우선 AI 워크스페이스

대부분의 AI 도구는 대화가 끝나면 맥락을 잊습니다. Lattice AI는 승인한 로컬 폴더와 대화를 인덱싱하고, 사람·프로젝트·개념·문서를 자동으로 지식 그래프로 연결합니다.

로컬 파일 + 대화 + 폴더
        ↓
자동 지식 그래프
        ↓
그래프 기반 AI 검색, 채팅, 문서 생성, 관리자 감사

설치

pip install ltcai
LTCAI
# http://localhost:4825

Apple Silicon에서 로컬 모델까지 쓰려면:

pip install "ltcai[local]"
LTCAI

사용 흐름

1. 설치한다.
2. CPU, GPU, RAM을 감지해서 적합한 로컬 모델을 추천받는다.
3. 연결할 로컬 폴더를 선택한다.
4. 파일과 대화가 자동으로 지식 그래프가 된다.
5. “지난주 인증 마이그레이션에서 결정한 게 뭐였지?”처럼 질문한다.
6. 같은 지식을 웹 UI, VS Code, Telegram, MCP에서 사용한다.

핵심 차별점

• 내 데이터가 AI의 기억이 됨 — 채팅과 파일을 자동으로 구조화
• 로컬 우선 — 기본 데이터는 ~/.ltcai/에 저장
• 자동 그래프 — 사용자가 노드와 엣지를 직접 만들 필요 없음
• 모델 추천/로드 흐름 — 하드웨어 감지 후 적합한 모델 추천
• 선택형 클라우드 — 클라우드 모델은 사용자가 설정한 경우에만 사용
• 관리자/보안 기능 — 권한, 감사 로그, 민감정보 감지, export 지원

자세한 내용은 docs/CHANGELOG.md, SECURITY.md, CONTRIBUTING.md를 참고하세요.