tachy

Self-hosted knowledge engine for work items. It archives approved lessons from past tickets and issues, then searches them when a similar one comes in. tachý only stores and retrieves; the reasoning layer is an MCP client (Claude Code, Codex CLI) or the built-in web chat agent.

What it does

• Pulls work items from Freshdesk, GitHub Issues and Azure DevOps, with relations, linked PRs and commits fetched and attached, not merely noticed.

• Archives lessons only after a human approves them, anchored to a per-product component glossary. Outdated entries are deprecated rather than deleted, so they stay searchable and can point at their replacement.

• Indexes linked git repos into local embeddings, so the agent reads bounded snippets from the right repo instead of whole files.

• Stores freeform reference docs (runbooks, architecture notes), chunked, embedded and versioned with supersede lineage.

• Hybrid search (keyword, trigram, semantic) over a deliberately customer-blind index, with fully local embeddings.

• Exposes 40+ MCP tools to any MCP client, plus a Svelte web UI whose chat agent (claude or copilot backend) pauses for approval before any write.

• Keeps API keys and source tokens in an AES-256-GCM vault, scoped user, team, global.

• Password login, bearer token or OIDC SSO, and optional PII scrubbing before anything reaches a model.

Related MCP server: claude-rag-mcp

Install

Postgres initializes from db/schema.sql, so clone the repo first. There is no published image; the stack builds locally.

git clone https://github.com/diegokoes/tachy.git
cd tachy
cp .env.example .env      # set TACHY_SECRET_KEY and TACHY_SESSION_SECRET
docker compose up -d --build
curl localhost:8787/health

On first boot with an empty database, open the web UI and the one-time setup wizard creates the admin account. Until an admin exists, and with no token or SSO configured, the server binds to 127.0.0.1 inside the container, so run the wizard before expecting LAN access.

Without Docker you need Node 24.18+ and PostgreSQL 14+ with vector, pg_trgm and pgcrypto (schema.sql creates the extensions), plus git on PATH for code search.

npm install
createdb tachy
psql "postgres://localhost:5432/tachy" -f db/schema.sql
cp .env.example .env
npm run web:build && npm run api    # SPA + API on :8787

.env is bootstrap only, everything else is configured in the app. .env.example lists and comments every variable the code reads.

MCP clients register the server from the project folder: .mcp.json for Claude Code, .vscode/mcp.json for VS Code Copilot. Other clients point at npx tsx packages/mcp/src/index.ts.

Deployment

Two stacks on one host, both driven by Jenkinsfile:

Every branch runs npm ci, typecheck, web:check and coverage, then builds an image. Only main and dev push and deploy; a feature branch gets its own branch-* tag that nothing pulls. Deploying is an SSH to the host followed by docker compose pull api && docker compose up -d api. The dev stage first resets its checkout to origin/dev, because docker-compose.yml is itself versioned and has to match the image being pulled.

The two stacks share nothing. docker-compose.yml takes its project name, ports and image tag from the environment, so dev is just a second checkout with its own .env (see .env.dev.example), its own network, containers, volumes and database. The image the servers pull is private and exists for these two stacks only, which is why a fresh install builds instead.

A restart drops in-flight chat turns. Logins survive it when TACHY_SESSION_SECRET is set, and past chats resume from the agent-home volume.

Backups. docker compose run --rm cli npm run sync backup writes a pg_dump -Fc into ./backups/. Schedule it and prune old dumps:

0 3 * * * cd /opt/tachy && docker compose run --rm cli npm run sync backup && find backups -name '*.dump' -mtime +14 -delete

Dumps hold real ticket data. Restoring vault credentials also needs the original TACHY_SECRET_KEY, so keep the .env secrets in a password manager.

There is deliberately no migrations directory, so upgrading an existing deployment is a backup, a fresh database from the current db/schema.sql, and a restore of the data tables. See CONTRIBUTING.md.

License

AGPL-3.0-or-later, see LICENSE. Contributions: CONTRIBUTING.md. Security reports: SECURITY.md.