Achiote

Achiote

[achiote icon]

TL;DR: Achiote — food-memory and cultural taste research product. Best for researchers and builders exploring food memory and heritage taste. Keywords: food memory research, cultural taste, heritage cuisine AI.

Achiote is a Model Context Protocol (MCP) server for research-first food-and-drink memory reconstruction. It helps a host AI turn incomplete family food or drink memories into structured clues, research plans, cited/provenance-ready findings, sensory analysis, sourcing/substitution strategy, and a minimum viable nostalgia cue before any fuller recipe handoff.

"The nostalgia lives in the maillard crust's interaction with the lactic tang — here's how to reproduce that."

Super Quick Start

From this repo:

npm cinpm run buildmkdir -p ~/.codex/skills/achiotecp skill/SKILL.md ~/.codex/skills/achiote/SKILL.md

Claude Code can use the checked-in .mcp.json after the build step. For Codex, add the MCP server to ~/.codex/config.toml with an absolute path to this repo's built dist/index.js:

pwd# copy the printed path and append /dist/index.js

[mcp_servers.achiote]command = "node"args = ["/absolute/path/to/achiote/dist/index.js"]enabled = truestartup_timeout_sec = 10

Restart the host AI session, then test with:

Use the achiote skill.
My mom said my Puerto Rican grandma made something that sounded like pass-teh-lay. I don't speak Spanish. Maybe plantains or pork?

Expected behavior: the host AI should use the MCP tools to collect the memory, plan research, build a dossier, and present a minimum viable nostalgia cue first. Only after that should it ask whether the user wants something more complex, such as sourcing help or a full recipe handoff.

Public Web Surfaces

The hosted/static product surface lives under docs/landing/. The core app and launch pages are dependency-free static assets served by the optional HTTP server:

• / -> docs/landing/index.html, the public landing page.
• /app -> docs/landing/app.html, the interactive food-memory detective.
• /pricing, /about, /roadmap, /changelog, /status, /blog, and /receipt -> standalone launch/trust/growth pages.
• /ai-search, /llms.txt, /privacy, /terms, /safety, /support, /compare, /robots.txt, and /sitemap.xml -> AI-search, legal, support, comparison, and crawler surfaces.

Open the HTML files directly in a browser for static review; the full route behavior is covered by npm run package:smoke.

What It Does Today

Achiote is a research-first food-and-drink memory reconstruction server. It provides 19 MCP tools that let a host AI chat client run the workflow from a fragment to a minimum viable nostalgia cue, with optional sourcing/substitution and recipe handoff if the user wants more:

All tools return MCP structuredContent. Most tools also display JSON text; intake tools may display a short human-readable summary so Claude Code output stays readable while structured data remains available to the host.

End-to-end flow

food memory fragment  -> collect_food_memory  -> plan_dish_research  -> optional host research / family clarification  -> build_research_record / validate_research_record / extract_research_findings  -> build_reconstruction_dossier  -> generate_family_followup_questions  -> generate_minimum_viable_nostalgia   # first concrete food output  -> optional analyze_nostalgic_dish / find_sensory_substitutes / source_ingredients  -> optional generate_recipe            # only if the user wants more

This executes through the full MCP workflow and is covered by tests/reconstruction-flow-e2e.test.ts. The preferred stopping point is the minimum viable nostalgia cue: the smallest, most accessible, easiest-to-find aroma, bite, sip, condiment, or ritual that tests whether the memory is on the right track. If the user asks for more, the MCP server can then provide sourcing/substitution context and a recipe-generation handoff. The host AI writes final recipe prose because live research, family confirmation, and adaptation judgment should not be faked by bundled data.

Requirements

• Node.js >=22.0.0
• npm

better-sqlite3 is a native dependency, so unsupported Node/platform combinations may need a compiler toolchain or a supported prebuild.

Installation

Achiote is published to npm.

npm install achiote

The published package ships the built dist/ output, so no build step is needed. To run from a source checkout instead:

npm cinpm run build

Using with Claude Code or another MCP client

After building, add the stdio server to your MCP settings:

{  "mcpServers": {    "achiote": {      "command": "node",      "args": ["/path/to/achiote/dist/index.js"]    }  }}

If installed as a package, the CLI binary is achiote.

HTTP server

An optional HTTP server provides a web UI and AI agent endpoint:

node dist/http-server.js# Listening on http://localhost:3000

Hosted Achiote (https://achiote.kyanitelabs.tech) does not enforce authentication: anonymous access is open and billing-issued API keys are honored (GET /health reports authEnabled: false). Self-hosted HTTP can still require keys: configure ACHIOTE_API_KEYS for /ask, /mcp, and voice upload endpoints. Setting ACHIOTE_AUTH_ENABLED=false does not by itself expose anonymous /ask or voice processing; set ACHIOTE_ALLOW_ANON_ASK=true only for local demos. Generate a self-hosted key with npm run keygen -- --tier pro --name admin; put the printed envRecord inside the ACHIOTE_API_KEYS JSON array, not the one-time raw key. Port defaults to 3000, configurable via PORT env var.

Shareable Memory Receipt links keep receipt JSON in the URL fragment (/receipt#data=...). URL fragments are not sent to the server, so possession of the link is the access boundary. Do not put private family memory text into telemetry or server-side share records.

Local OSS speech

Voice is disabled by default and uses only local OSS speech engines when configured. The recommended stack is whisper.cpp for multilingual speech-to-text and Kokoro-82M for local read-aloud. This path is aimed at immigrant families and children of immigrants: speech input defaults to auto language detection so accents, transliterated dish names, and code-switching can reach the same food-memory workflow as typed text. Exact language and accent quality depends on the local model you install.

Example environment:

ACHIOTE_STT_PROVIDER=whispercppACHIOTE_WHISPER_CPP_BINARY=/usr/local/bin/whisper-cliACHIOTE_WHISPER_CPP_MODEL=/models/ggml-large-v3-turbo.binACHIOTE_STT_LANGUAGE=autoACHIOTE_STT_LANGUAGES=auto,es,hi,zh,ar,fr,pt,tl
ACHIOTE_TTS_PROVIDER=kokoroACHIOTE_KOKORO_COMMAND='["python","/opt/kokoro/speak.py","--text","{text}","--output","{output}","--voice","{voice}","--language","{language}"]'ACHIOTE_KOKORO_VOICE='af_heart'ACHIOTE_KOKORO_VOICES='[{"id":"af_heart","label":"Warm English","language":"en"},{"id":"ef_dora","label":"Spanish voice","language":"es"}]'

/voice/status is public readiness discovery. /voice/transcribe and /voice/synthesize use the same auth and anonymous-demo policy as /ask, because recorded family memories are sensitive.

Cache and privacy

The SQLite research cache path is:

1. $ACHIOTE_CACHE_PATH, if set
2. $XDG_CACHE_HOME/achiote/culture-cache.db, if XDG_CACHE_HOME is set
3. ~/.cache/achiote/culture-cache.db

User memories can be emotionally sensitive. Do not add optional food-data provider integrations without documenting what is sent, where it is sent, and how it is cached.

Operator reference seeding

Achiote can turn private aggregate /ask quality counters into reference seed priorities for future data hardening:

npm run reference:seeds -- --quality-report quality.json --limit 10

The command prints host-research prompts and reference bootstrap targets. It does not browse. SQLite is an optional persistent overlay for additional approved ResearchRecord objects:

npm run reference:seeds -- --fixture approved-fixture.json --cache-path ~/.cache/achiote/culture-cache.db

Fixtures must match the seed manifest and pass provenance validation before any SQLite write.

The repo also ships an approved CC0 structured-data pantry batch. Those records are committed in src/data/reference-pantry-fixtures.json, compiled into dist/data/, and used by runtime tools as the built-in baseline even when SQLite has never been bootstrapped:

npm run reference:seeds -- --fixture bundled --cache-path ~/.cache/achiote/culture-cache.db

That optional bootstrap command copies the bundled baseline into SQLite for deployments that want a single local database view, but it is not required on every request and it is not required for Achiote to see the baseline pantry. The bundled batch uses Wikidata structured labels/descriptions only. It currently contains 138 typed ResearchRecord fixtures: the original 18-record skeleton plus a 120-record expansion across 20 culture-area buckets and six food-memory bands. It covers every current food form, culture-area bucket, region scope, name system, and sensory mechanism, and remains explicit that the records are broad grounding context rather than final family-specific answers. It marks the entries as cited researched records without pretending they are family-confirmed memories or operator quality signals.

The reference pantry is intentionally conservative. src/data/reference-source-registry.json allows CC0/public-domain structured sources first, currently Wikidata structured food data and USDA FoodData Central, and marks sources such as Open Food Facts and FAO/INFOODS for manual review before fixture use. Do not copy recipe prose, paywalled database content, proprietary rankings, raw user memories, credentials, or uncited model guesses into pantry fixtures.

Development

npm ci                         # Install locked dependenciesnpm run typecheck              # TypeScript no-emit checknpm run lint                   # Dependency-free static launch checksnpm run coverage:guard         # Dependency-free test-surface threshold guardnpm run build                  # Compile TypeScriptnpm test                       # Run testsnpm run check                  # Full local gate: typecheck, static checks, coverage guard, build, citations, testsnpm audit --audit-level=moderatenpm run package:smoke          # Pack, install in temp project, and verify packaged MCP CLInpm run pack:check             # Full release gatenpm run docker:smoke           # Build the Docker image for a container smoke checknpm pack --dry-run             # Inspect publish contentsnpm start                      # Start the MCP server after build

For self-hosted GitHub Actions runner and queued-job troubleshooting, see docs/SELF_HOSTED_RUNNER.md.

Architecture

See docs/ARCHITECTURE.md.

Current long-lived module boundaries include:

• src/lib/provider-runtime.ts for provider/model profile resolution and ask-session adapter selection.
• src/lib/account-access.ts for auth, billing, credits, anonymous demo behavior, and rate-limit decisions.
• src/lib/local-speech-controller.ts for HTTP voice route behavior around local OSS speech engines.
• src/lib/cue-profile-engine.ts for minimum viable nostalgia cue profile evidence surfaces.
• src/lib/constraint-adapter.ts for dietary, allergy, and religious constraint rewrites.
• docs/landing/product-app.js for browser app primitives such as SSE parsing, actionable HTTP errors, and chat-history updates.
• scripts/lib/package-surface.mjs for the intentional package/release surface.

The Science

Food-evoked nostalgia should be handled as a sensory-memory workflow, not as a medical claim. The server preserves evidence boundaries: user memory, host-researched facts, model inference, and unknowns stay separate so the host can cite real sources and avoid pretending bundled data is research.

The bundled food-science references in src/data/food-science-references.json organize peer-reviewed research by mechanism area. Each entry includes a DOI for verification. The 12 mechanism areas are:

License

Business Source License 1.1 (BUSL-1.1). See LICENSE.

• GitHub: https://github.com/KyaniteLabs/Achiote

What is Achiote?

Achiote is a food-memory and cultural taste research product that helps researchers and builders exploring food memory and heritage taste capture and reason about food memory with structured research surfaces.

Who it's for

• Primary: researchers and builders exploring food memory and heritage taste
• Use when you need to capture and reason about food memory with structured research surfaces
• Skip if you need a recipe SEO blog

FAQ

What is Achiote?

Achiote is a food-memory and cultural taste research product. It helps researchers and builders exploring food memory and heritage taste capture and reason about food memory with structured research surfaces.

Who should use Achiote?

researchers and builders exploring food memory and heritage taste.

How is Achiote different?

Unlike recipe aggregators, Achiote focuses on memory and cultural taste research.

Is Achiote production software?

Treat the README status and release tags as source of truth for maturity. Validate against your own requirements before production use.

Status

• Maintained as of 2026 on the default branch
• Prefer release tags when pinning dependencies
• Report issues on GitHub

Agent surface

• Coding agents: read this README first, then repo docs/AGENTS.md if present
• Prefer machine-readable briefs (llms.txt) when the repo ships one
• MCP or skill entrypoints are documented in-repo when applicable

Contributing

Issues and PRs welcome on GitHub. Keep public docs free of secrets and machine-local paths.

License

See LICENSE in this repository (or package metadata if license is package-only).

Table of contents

• What is it?
• FAQ
• Status

[status] [docs]

Licensing

Achiote is source-available under the Business Source License 1.1 (BUSL-1.1).

• Free: personal, evaluation, and development use.
• Commercial / production use requires a license — see pricing (Commercial tier from $299/mo includes hosted API + MCP production access and commercial self-hosting terms).
• Alternative licensing: [email protected].
• The license converts to GPLv2+ at the Change Date (2030) per BUSL-1.1.