Twiceshy

@dotts-h

About Twiceshy

Once bitten, twice shy — a shared memory of validated engineering traps, dead-ends and fixes for coding agents, served over MCP. AGPL-3.0.

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "twiceshy": {
      "type": "streamable-http",
      "url": "https://api.twiceshy.app",
      "headers": {
        "Authorization": "Bearer tok_YOUR_TOKEN_FROM_twiceshy.app"
      }
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is Twiceshy?

A self‑hosted service that feeds hard‑won engineering experience — issues, dead‑ends, root causes, validated fixes — to LLM coding agents at decision time, so they stop repeating known mistakes on autopilot. It operates like a private, curated, validated StackOverflow that injects itself at the right moment.

How to use Twiceshy?

Use the hosted instance at twiceshy.app with the remote MCP endpoint https://api.twiceshy.app/, or self‑host following the development instructions (make ci). Interact via MCP tools: search_experience, get_experience (read path) and record_experience (propose‑only write path).

Key features of Twiceshy

Git‑backed markdown experience records with YAML frontmatter.
Derived SQLite index with FTS5 (dense retrieval planned).
Multi‑stage retrieval: fingerprint‑exact → BM25 → dense, with relevance floor and hard cap of 3 results.
Two channels: push (Claude Code hooks) and pull (MCP tools over streamable HTTP).
Trust model: agent‑proposed records quarantined, promoted only after sandbox validation and human PR review.
Background “doctors” for dedup, staleness, repro re‑execution, decay, and abstraction.

Use cases of Twiceshy

Prevent an agent from re‑introducing a known bug or deprecated API.
Inject verified workarounds for third‑party issues at decision time.
Record and propagate root‑cause analyses across a team.
Capture validated fixes so future agents skip dead‑end investigations.
Automatically quarantine untested proposals until they pass human review.

FAQ from Twiceshy

What retrieval stages does Twiceshy use?

Retrieval follows a cascade: fingerprint‑exact → BM25 → dense (RRF), with stack‑fingerprint filtering and a relevance floor. At most 3 results are injected; below the floor nothing is injected.

How does Twiceshy ensure experience records are trustworthy?

Agent‑proposed records are quarantined. Promotion requires a sandbox fail‑to‑pass validation and a human‑reviewed pull request. A new record is a PR.

What is the license?

The Twiceshy engine is AGPL‑3.0‑only. Contributions require a signed CLA, and the corpus has a separate licensing strategy (see ADR‑0002).

What is the current status of development?

Bootstrapping. Phase 1 (read path: parser/validator, FTS5 index, fingerprint + lexical search, MCP search_experience/get_experience) is complete. Phase 3 write path (record_experience – propose‑only) has landed. Remaining phases (hooks push channel, dense retrieval, doctors) are tracked as issues.

Frequently asked questions

What retrieval stages does Twiceshy use?

How does Twiceshy ensure experience records are trustworthy?

Agent‑proposed records are quarantined. Promotion requires a sandbox fail‑to‑pass validation and a human‑reviewed pull request. A new record *is* a PR.

What is the license?

The Twiceshy engine is AGPL‑3.0‑only. Contributions require a signed CLA, and the corpus has a separate licensing strategy (see [ADR‑0002](docs/adr/ADR‑0002‑licensing‑strategy.md)).

What is the current status of development?

Bootstrapping. Phase 1 (read path: parser/validator, FTS5 index, fingerprint + lexical search, MCP `search_experience`/`get_experience`) is complete. Phase 3 write path (`record_experience` – propose‑only) has landed. Remaining phases (hooks push channel, dense retrieval, doctors) are tracked as issues.