About Twiceshy
Twiceshy is a self-hosted service that gives coding agents validated engineering lessons, including root causes and fixes, at decision time. Git-backed records and relevance-filtered retrieval help avoid repeating documented dead ends.
Key features
- 01Git-backed experience records
- 02Fingerprint, BM25, and dense retrieval
- 03Relevance floor with no-match option
- 04Quarantined submissions and human review
- 05Background validation and staleness checks
Use cases
- 01Retrieve known fixes while coding
- 02Avoid repeating documented engineering dead ends
- 03Review proposed memory records before promotion
MCP support
Exposes pull-based retrieval tools to MCP clients over streamable HTTP. Its hosted endpoint is https://api.twiceshy.app/.
Configuration
Remote servers need no local install. Pick your client, then copy the config or install in one click.
https://api.twiceshy.appclaude mcp add --transport http twiceshy https://api.twiceshy.app{"mcpServers":{"twiceshy":{"type":"http","url":"https://api.twiceshy.app"}}}Open in Cursor{"servers":{"twiceshy":{"type":"http","url":"https://api.twiceshy.app"}}}Open in VS Code{"mcpServers":{"twiceshy":{"type":"http","url":"https://api.twiceshy.app"}}}{"mcpServers":{"twiceshy":{"serverUrl":"https://api.twiceshy.app"}}}Run commands in a terminal; paste JSON into the client’s MCP config and restart. Servers that need sign-in will prompt on first connect.
https://api.twiceshy.appAuth requiredTools
Details
From the project READMEtwiceshy
Once bitten, twice shy.
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. Records are git-backed and provenance-aware; automatic retrieval applies a relevance floor so a weak match can return nothing.
Hosted alpha
The hosted instance runs at twiceshy.app — self-serve
tokens, remote MCP endpoint https://api.twiceshy.app/. External
contributions require a signed CLA before merge
(ADR-0002).
How it works (the locked architecture)
- Source of truth: git-backed markdown experience records (YAML frontmatter
- narrative) — format in docs/SCHEMA.md. The corpus is a
separate versioned data product (
twiceshy-corpus, ADR-0021); the engine ships a small frozen fixture (internal/testcorpus/) for tests.
- narrative) — format in docs/SCHEMA.md. The corpus is a
separate versioned data product (
- Index: one derived, always-rebuildable SQLite file (FTS5 plus cached, pure-Go dense vectors for pull retrieval).
- Retrieval: fingerprint-exact → BM25 → dense (RRF), stack-fingerprint filtered, hard cap k≤3 with a relevance floor — below it, nothing is injected.
- Channels: push (Claude Code hooks → trap cards), pull (MCP tools over streamable HTTP), index (generated one-liners).
- Trust: agent-proposed records are quarantined; promotion = sandbox fail-to-pass validation + human PR review. A new record IS a pull request.
- Doctors: background jobs that dedup, staleness-check, re-execute repros (CI for memories), decay, and abstract.
Full rationale: docs/research/EXPERIENCE_SERVICE_RESEARCH.md and docs/adr/ADR-0001-architecture.md.
Status
The core service is available as a hosted alpha. For the canonical snapshot of what ships now and the current roadmap, see docs/NEXT_FEATURES.md; deployment and operating details live in docs/DEPLOY-public-alpha.md.
Development
make ci # lint + race tests + coverage floor — what CI runs
See docs/CONVENTIONS.md and docs/CONTEXT.md first.
License
AGPL-3.0-only. Contribution and corpus licensing: docs/adr/ADR-0002-licensing-strategy.md.
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.